4.3 KiB
Admin 导航分组与静态交互设计
目标
将 admin 当前全部平铺的一级菜单改为可扩展的二级分组导航，同时保留现有静态页面和 Pinia 交互。Java 接口及响应结构尚未确定，本阶段不提前设计领域 API 契约。
范围
本次只处理 apps/admin-web：
- 调整侧边栏信息架构与折叠交互。
- 保留现有页面、路由地址和模拟数据行为。
- 增加 admin 项目内部测试，不在仓库根目录增加 Node 配置或依赖。
不处理 client、小程序、APP、PDA 或 Java 服务；不猜测最终后端 URL、响应信封、业务错误码或分页格式。
导航结构
采用两级分组，工作台保留为直接入口：
工作台
业务管理
├── 客户管理
└── 头程订单
系统管理
├── 内部用户
├── 角色管理
└── 菜单权限
侧边栏使用 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，不影响其他项目。测试覆盖：
- 导航只有工作台是直接一级入口，业务管理和系统管理拥有预期子菜单。
- 每个叶子菜单的路径和权限编码唯一。
- 菜单图标由节点自身定义，不依赖数组下标。
- 静态阶段不因权限字段存在而隐藏任何菜单。
完成后执行：
cd apps/admin-web
pnpm test
pnpm typecheck
pnpm build
浏览器验收桌面展开态、桌面折叠态和 390px 移动端，确认二级菜单可访问、当前页面正确高亮、移动侧栏可关闭，并且原有业务交互不回归。
完成标准
- admin 菜单不再全部平铺在一级。
- 新增业务模块时可以放入既有分组或新增分组，不需要改写侧栏组件。
- 当前六个页面入口全部可达且路由不变。
- 静态页面的筛选、表单、详情和状态操作继续可用。
- 页面不会请求不存在的 Java 业务接口，也不会固化未经确认的响应结构。
- admin 的测试、类型检查和生产构建全部通过。