96 lines
4.3 KiB
Markdown
96 lines
4.3 KiB
Markdown
# Admin 导航分组与静态交互设计
|
||
|
||
## 目标
|
||
|
||
将 admin 当前全部平铺的一级菜单改为可扩展的二级分组导航，同时保留现有静态页面和 Pinia 交互。Java 接口及响应结构尚未确定，本阶段不提前设计领域 API 契约。
|
||
|
||
## 范围
|
||
|
||
本次只处理 `apps/admin-web`：
|
||
|
||
- 调整侧边栏信息架构与折叠交互。
|
||
- 保留现有页面、路由地址和模拟数据行为。
|
||
- 增加 admin 项目内部测试，不在仓库根目录增加 Node 配置或依赖。
|
||
|
||
不处理 client、小程序、APP、PDA 或 Java 服务；不猜测最终后端 URL、响应信封、业务错误码或分页格式。
|
||
|
||
## 导航结构
|
||
|
||
采用两级分组，工作台保留为直接入口：
|
||
|
||
```text
|
||
工作台
|
||
|
||
业务管理
|
||
├── 客户管理
|
||
└── 头程订单
|
||
|
||
系统管理
|
||
├── 内部用户
|
||
├── 角色管理
|
||
└── 菜单权限
|
||
```
|
||
|
||
侧边栏使用 Element Plus 的菜单和子菜单能力，以获得稳定的展开、折叠、当前路由高亮和折叠态浮层。页面路由地址保持不变。
|
||
|
||
菜单配置放在 `src/navigation/adminNavigation.ts`，使用 admin 本地的 `AdminNavigationNode` 类型，避免修改共享包中的单层 `NavigationItem` 并影响 client。节点包含唯一标识、标题、图标、路径、权限编码和可选子节点。图标跟随节点配置，不再依赖 `iconMap[index]` 的数组位置。
|
||
|
||
当前静态阶段显示全部菜单，不根据模拟角色执行权限过滤，因为现有登录用户没有后端返回的权限编码集合。节点保留权限编码字段；后端权限契约确定后，再以叶子菜单为单位过滤，并只显示至少包含一个可访问子菜单的分组。
|
||
|
||
移动端继续使用现有抽屉式侧栏：选择页面后自动关闭，点击右侧遮罩关闭。桌面折叠时由 Element Plus 展示子菜单浮层，避免二级入口丢失。
|
||
|
||
## 静态数据与交互
|
||
|
||
客户、订单、内部用户、角色和权限页面继续使用 `useAdminDataStore`：
|
||
|
||
- 查询、筛选和分页在前端执行。
|
||
- 新增、编辑、审核、启停和状态流转直接修改 Pinia 内存数据。
|
||
- 刷新页面后恢复初始模拟数据，不增加持久化。
|
||
- 页面不发起真实业务网络请求。
|
||
|
||
该策略用于先验收页面结构和操作流程，不伪装成已完成后端联调。
|
||
|
||
## API 当前边界
|
||
|
||
保留现有 `src/api/http.ts` 作为 Axios 基础实例，仅包含基础地址、超时和 admin Token 注入。当前不新增客户、订单、用户、角色或权限领域 API，不定义响应信封解包，不实现业务错误转换，也不在 401 拦截器中直接引用 Router 或 Pinia Store。
|
||
|
||
后端提供接口文档后，再单独确定以下内容：
|
||
|
||
- URL 前缀和版本规则。
|
||
- 统一响应信封及成功业务码。
|
||
- 分页参数和分页结果结构。
|
||
- 业务错误码与用户提示映射。
|
||
- 401 处理方式；若需要全局退出，使用应用启动层注册的 `onUnauthorized` 回调，避免请求层与 Router、Store 循环依赖。
|
||
- 按认证、客户、头程订单、内部用户、角色和权限拆分领域模块。
|
||
|
||
真实接口接入后，由 Store 调用领域 API，并负责加载状态、错误状态和数据缓存。页面继续读取 Store，不直接调用 Axios。
|
||
|
||
## 测试与验收
|
||
|
||
在 `apps/admin-web` 内增加 Vitest，不影响其他项目。测试覆盖：
|
||
|
||
- 导航只有工作台是直接一级入口，业务管理和系统管理拥有预期子菜单。
|
||
- 每个叶子菜单的路径和权限编码唯一。
|
||
- 菜单图标由节点自身定义，不依赖数组下标。
|
||
- 静态阶段不因权限字段存在而隐藏任何菜单。
|
||
|
||
完成后执行：
|
||
|
||
```bash
|
||
cd apps/admin-web
|
||
pnpm test
|
||
pnpm typecheck
|
||
pnpm build
|
||
```
|
||
|
||
浏览器验收桌面展开态、桌面折叠态和 390px 移动端，确认二级菜单可访问、当前页面正确高亮、移动侧栏可关闭，并且原有业务交互不回归。
|
||
|
||
## 完成标准
|
||
|
||
- admin 菜单不再全部平铺在一级。
|
||
- 新增业务模块时可以放入既有分组或新增分组，不需要改写侧栏组件。
|
||
- 当前六个页面入口全部可达且路由不变。
|
||
- 静态页面的筛选、表单、详情和状态操作继续可用。
|
||
- 页面不会请求不存在的 Java 业务接口，也不会固化未经确认的响应结构。
|
||
- admin 的测试、类型检查和生产构建全部通过。
|