169 lines
7.4 KiB
Markdown
169 lines
7.4 KiB
Markdown
# Client Web 导航分级与移动侧栏设计
|
||
|
||
## 背景
|
||
|
||
`apps/client-web` 当前把业务总览、企业资料、企业成员、角色管理、菜单权限和头程订单全部渲染为同级侧栏链接。权威原型 `docs/悦/头程下单/柏悦客户端.html` 采用“一级业务域 + 二级具体任务”的导航结构，现有实现没有延续这一信息架构，也无法承接后续业务扩展。
|
||
|
||
Impeccable 验收还发现一个阻断性问题：720px 以下侧栏被隐藏，但页面上的菜单按钮没有打开移动导航的行为，导致移动端无法切换模块。
|
||
|
||
## 目标
|
||
|
||
- 将客户工作台的平铺菜单改为可扩展的两级分组导航。
|
||
- 保留现有路由、页面、文案、品牌颜色与 Element Plus 技术体系。
|
||
- 修复移动端导航不可用的问题。
|
||
- 让菜单节点显式携带图标与权限信息，避免依赖数组下标。
|
||
- 为后续真实权限集合接入保留清晰边界，不在本次伪造授权数据。
|
||
|
||
## 非目标
|
||
|
||
- 不新增原型中尚未实现的一键导入、快速下单、海外仓或财务结算入口。
|
||
- 不改变现有路由地址，不拆分当前 `ModuleView.vue` 页面。
|
||
- 不照搬原型的紫色渐变视觉，不重做登录、注册或业务内容页。
|
||
- 不实现服务端权限校验，也不把前端菜单隐藏当作安全控制。
|
||
- 不新增测试框架；当前项目尚未声明测试脚本。
|
||
|
||
## 导航信息架构
|
||
|
||
采用两级分组，业务总览保留直接入口：
|
||
|
||
```text
|
||
业务总览 /
|
||
|
||
头程业务 可展开分组
|
||
└── 头程订单 /orders/first-leg
|
||
|
||
企业管理 可展开分组
|
||
├── 企业资料 /company/profile
|
||
├── 企业成员 /organization/members
|
||
├── 角色管理 /organization/roles
|
||
└── 菜单权限 /organization/permissions
|
||
```
|
||
|
||
分组遵循原型的结构原则，但只呈现当前真实存在的客户端路由。后续功能只有在页面与路由实现后，才加入对应业务分组。
|
||
|
||
## 组件与数据结构
|
||
|
||
### 导航配置
|
||
|
||
新增客户端本地导航配置 `src/navigation/clientNavigation.ts`。定义客户端专用的 `ClientNavigationNode`，包含：
|
||
|
||
- 稳定 `key`；
|
||
- 用户可见 `title`；
|
||
- Lucide 图标组件；
|
||
- 可选 `path`；
|
||
- 可选 `permission`；
|
||
- 可选 `children`。
|
||
|
||
共享包中的 `NavigationItem` 仍保持单层公共模型，避免为了单个应用的壳层结构扩大跨项目契约。
|
||
|
||
### 侧栏菜单组件
|
||
|
||
新增独立的客户端侧栏菜单组件，使用 Element Plus 的 `el-menu`、`el-sub-menu` 与 `el-menu-item`：
|
||
|
||
- `active-path` 由当前路由提供；
|
||
- 父分组可展开和收起；
|
||
- 当前路由所在分组默认展开；
|
||
- 叶子菜单负责实际路由跳转；
|
||
- 图标来自节点配置，不依赖渲染顺序；
|
||
- 桌面与移动端复用同一组件和同一份导航数据。
|
||
|
||
本轮不额外实现展开状态持久化；Element Plus 在当前会话中维护用户开合状态，且当前路由所在分组始终可识别。持久化不是修复平铺结构与移动阻断所必需的能力。
|
||
|
||
### 应用壳层
|
||
|
||
`AppLayout.vue` 继续负责品牌、租户、用户和页面标题，同时增加：
|
||
|
||
- `mobileMenuOpen` 状态；
|
||
- 移动菜单按钮的 `aria-expanded`；
|
||
- 遮罩关闭；
|
||
- 路由切换后自动关闭；
|
||
- Escape 键关闭；
|
||
- 打开时阻止背景页面滚动；
|
||
- 退出确认取消时不产生未处理异常。
|
||
|
||
桌面侧栏保持固定宽度和现有绿色服务型视觉，不引入后台的深色侧栏，也不增加桌面折叠模式。
|
||
|
||
## 交互与状态流
|
||
|
||
### 桌面端
|
||
|
||
1. 路由加载后，菜单以 `route.path` 高亮对应叶子。
|
||
2. “业务总览”为直接入口。
|
||
3. “头程业务”和“企业管理”为分组触发器。
|
||
4. 当前页面属于某分组时，该分组保持展开并显示父级激活语义。
|
||
5. 用户可以独立展开或收起其他分组。
|
||
|
||
### 移动端
|
||
|
||
1. 720px 以下侧栏移出视口，而不是使用 `display: none` 永久移除。
|
||
2. 点击页面标题前的菜单按钮打开抽屉并显示遮罩。
|
||
3. 点击遮罩、按 Escape 或选择任一叶子路由后关闭抽屉。
|
||
4. 抽屉打开时禁止背景滚动，关闭或组件卸载时恢复。
|
||
5. 抽屉沿用完整租户导航，不维护第二份移动菜单。
|
||
|
||
### 权限
|
||
|
||
导航节点继续携带权限编码。当前模拟用户没有可靠的权限集合，因此静态阶段显示全部已实现菜单。真实认证接口返回权限集合后，再增加叶子过滤；父分组没有可访问子项时隐藏。服务端必须继续执行租户与权限校验。
|
||
|
||
## 视觉与可访问性
|
||
|
||
- 保留现有 `--primary`、`--navy`、`--border` 和 `--muted` 设计令牌。
|
||
- 一级分组与二级叶子通过缩进、字号、颜色和激活背景形成清晰层级。
|
||
- 分组触发器与移动菜单按钮使用真实可聚焦控件。
|
||
- 保持可见 `:focus-visible` 状态，不只依赖 hover 或颜色表达当前状态。
|
||
- 菜单触控目标不低于约 44px。
|
||
- 二级菜单文本允许单行省略，避免长租户业务名称破坏侧栏宽度。
|
||
- 侧栏导航区域允许纵向滚动；底部帮助区保持可达。
|
||
- 320px、720px 与桌面宽度均不能依赖水平滚动完成导航。
|
||
|
||
## 错误与边界处理
|
||
|
||
- 用户取消退出确认时保持当前页面，不产生控制台未处理异常。
|
||
- 移动抽屉在快速路由切换、浏览器后退和组件卸载后不得残留锁定滚动状态。
|
||
- 不存在或被移除的路由继续走现有兜底重定向。
|
||
- 当前不虚构客户经理电话、微信或帮助中心链接；帮助区保留为信息提示，后续有真实渠道后再做可执行入口。
|
||
- 权限为空或数据尚未加载时，本轮不提前隐藏菜单，避免模拟阶段出现无法恢复的空侧栏。
|
||
|
||
## 实施范围
|
||
|
||
预计修改或新增：
|
||
|
||
- `apps/client-web/src/navigation/clientNavigation.ts`
|
||
- `apps/client-web/src/components/ClientSidebarMenu.vue`
|
||
- `apps/client-web/src/layouts/AppLayout.vue`
|
||
- `apps/client-web/src/router/index.ts`
|
||
- `apps/client-web/src/styles/index.css`
|
||
|
||
仅当实现需要声明自动导入组件时，依赖现有插件自动生成声明，不手工编辑 `auto-imports.d.ts` 或 `components.d.ts`。
|
||
|
||
## 验收与验证
|
||
|
||
### 自动验证
|
||
|
||
在 `apps/client-web` 执行：
|
||
|
||
```bash
|
||
pnpm typecheck
|
||
pnpm build
|
||
```
|
||
|
||
项目当前没有 test 或 lint 脚本，因此不声称相应检查通过，也不为本次导航改动引入整套测试设施。
|
||
|
||
### Impeccable 验收
|
||
|
||
- 运行一次机械检测，目标覆盖本次变更的 Vue 文件。
|
||
- 桌面检查：一级分组、二级缩进、当前路由高亮、可见焦点和侧栏滚动。
|
||
- 720px 检查：断点切换时导航仍可达。
|
||
- 320px 检查：抽屉、遮罩、触控目标与页面内容不发生水平溢出。
|
||
- 浏览器可用时检查菜单打开、选择路由、遮罩关闭和 Escape 关闭；若浏览器不可用，明确记录回退证据，不伪装成已完成视觉实测。
|
||
|
||
## 完成标准
|
||
|
||
- 侧栏不再把全部功能放在一级菜单。
|
||
- 当前六个页面入口全部可达，路由地址不变。
|
||
- 桌面端当前页面与父分组状态清晰。
|
||
- 720px 以下菜单按钮能够打开和关闭真实导航抽屉。
|
||
- 导航图标不会因菜单调序或新增分组而错位。
|
||
- 未实现的原型功能不会作为无效入口出现。
|
||
- 类型检查、生产构建与 Impeccable 检测无未解释失败。
|