397 lines
13 KiB
Markdown
397 lines
13 KiB
Markdown
# Client Web Navigation Implementation Plan
|
||
|
||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||
|
||
**Goal:** 将 client-web 的扁平侧栏改为参考原型的两级业务分组导航，并修复移动端抽屉导航。
|
||
|
||
**Architecture:** 在 client-web 内新增带图标、权限和 children 的导航树与独立侧栏菜单组件。`AppLayout.vue` 只管理租户壳层、当前路由和移动抽屉状态；桌面与移动端复用同一份菜单组件和配置，不扩展共享包的单层 `NavigationItem`。
|
||
|
||
**Tech Stack:** Vue 3、TypeScript、Vue Router、Element Plus、Lucide Vue、Vite。
|
||
|
||
---
|
||
|
||
### Task 1: 建立客户端导航树
|
||
|
||
**Files:**
|
||
- Create: `apps/client-web/src/navigation/clientNavigation.ts`
|
||
- Modify: `apps/client-web/src/router/index.ts:1-33`
|
||
|
||
- [ ] **Step 1: 定义导航节点类型和叶子展开工具**
|
||
|
||
创建完整文件：
|
||
|
||
```ts
|
||
import type { Component } from 'vue'
|
||
import {
|
||
Building2,
|
||
ClipboardList,
|
||
KeyRound,
|
||
LayoutGrid,
|
||
Settings,
|
||
ShieldCheck,
|
||
Truck,
|
||
Users,
|
||
} from '@lucide/vue'
|
||
|
||
export interface ClientNavigationNode {
|
||
key: string
|
||
title: string
|
||
icon: Component
|
||
path?: string
|
||
permission?: string
|
||
children?: ClientNavigationNode[]
|
||
}
|
||
|
||
export interface ClientNavigationLeaf extends ClientNavigationNode {
|
||
path: string
|
||
permission: string
|
||
children?: never
|
||
}
|
||
```
|
||
|
||
- [ ] **Step 2: 写入已确认的导航树**
|
||
|
||
在同一文件写入：
|
||
|
||
```ts
|
||
export const clientNavigation: ClientNavigationNode[] = [
|
||
{ key: 'dashboard', title: '业务总览', icon: LayoutGrid, path: '/', permission: 'dashboard:view' },
|
||
{
|
||
key: 'first-leg',
|
||
title: '头程业务',
|
||
icon: Truck,
|
||
children: [
|
||
{ key: 'first-leg-orders', title: '头程订单', icon: ClipboardList, path: '/orders/first-leg', permission: 'order:first-leg:list' },
|
||
],
|
||
},
|
||
{
|
||
key: 'company',
|
||
title: '企业管理',
|
||
icon: Settings,
|
||
children: [
|
||
{ key: 'company-profile', title: '企业资料', icon: Building2, path: '/company/profile', permission: 'company:profile:view' },
|
||
{ key: 'company-members', title: '企业成员', icon: Users, path: '/organization/members', permission: 'company:member:list' },
|
||
{ key: 'company-roles', title: '角色管理', icon: ShieldCheck, path: '/organization/roles', permission: 'company:role:list' },
|
||
{ key: 'company-permissions', title: '菜单权限', icon: KeyRound, path: '/organization/permissions', permission: 'company:permission:list' },
|
||
],
|
||
},
|
||
]
|
||
|
||
export function getNavigationLeaves(nodes: ClientNavigationNode[]): ClientNavigationLeaf[] {
|
||
return nodes.flatMap((node) => {
|
||
if (node.children?.length) return getNavigationLeaves(node.children)
|
||
if (!node.path || !node.permission) return []
|
||
return [node as ClientNavigationLeaf]
|
||
})
|
||
}
|
||
```
|
||
|
||
不要加入原型中尚未实现的一键导入、快速下单、海外仓或财务结算。
|
||
|
||
- [ ] **Step 3: 删除 router 中的扁平 `clientNavigation` 配置并改为从本地导航模块导出**
|
||
|
||
删除 `NavigationItem` 类型导入和扁平数组，临时保留兼容导出，让尚未修改的布局仍能通过类型检查：
|
||
|
||
```ts
|
||
export { clientNavigation } from '@/navigation/clientNavigation'
|
||
```
|
||
|
||
Task 3 改造布局后删除这行兼容导出，使 router 最终只保留路由和权限元数据。
|
||
|
||
- [ ] **Step 4: 运行类型检查**
|
||
|
||
Run: `pnpm typecheck`
|
||
|
||
Expected: 成功退出，0 个 TypeScript 错误；不要引入 `any`。
|
||
|
||
### Task 2: 实现可复用客户端侧栏菜单组件
|
||
|
||
**Files:**
|
||
- Create: `apps/client-web/src/components/ClientSidebarMenu.vue`
|
||
|
||
- [ ] **Step 1: 使用 Element Plus 菜单组件实现递归一级/二级渲染**
|
||
|
||
组件脚本为：
|
||
|
||
```vue
|
||
<script setup lang="ts">
|
||
import { computed } from 'vue'
|
||
import { clientNavigation, type ClientNavigationNode } from '@/navigation/clientNavigation'
|
||
|
||
const props = defineProps<{ activePath: string }>()
|
||
const emit = defineEmits<{ navigate: [] }>()
|
||
|
||
function findParentKey(nodes: ClientNavigationNode[], path: string): string | undefined {
|
||
for (const node of nodes) {
|
||
if (node.children?.some((child) => child.path === path)) return node.key
|
||
if (node.children?.length) {
|
||
const parentKey = findParentKey(node.children, path)
|
||
if (parentKey) return parentKey
|
||
}
|
||
}
|
||
}
|
||
|
||
const defaultOpeneds = computed(() => {
|
||
const parentKey = findParentKey(clientNavigation, props.activePath)
|
||
return parentKey ? [parentKey] : []
|
||
})
|
||
|
||
function handleSelect() {
|
||
emit('navigate')
|
||
}
|
||
</script>
|
||
```
|
||
|
||
- [ ] **Step 2: 计算当前路由所在分组**
|
||
|
||
模板使用同一导航树，并把当前路由所在父分组传给 `default-openeds`：
|
||
|
||
```vue
|
||
<template>
|
||
<el-menu
|
||
class="client-nav-menu"
|
||
:default-active="activePath"
|
||
:default-openeds="defaultOpeneds"
|
||
router
|
||
@select="handleSelect"
|
||
>
|
||
<template v-for="item in clientNavigation" :key="item.key">
|
||
<el-sub-menu v-if="item.children?.length" :index="item.key">
|
||
<template #title>
|
||
<component :is="item.icon" :size="18" :stroke-width="1.9" />
|
||
<span>{{ item.title }}</span>
|
||
</template>
|
||
<el-menu-item v-for="child in item.children" :key="child.key" :index="child.path || child.key">
|
||
<component :is="child.icon" :size="17" :stroke-width="1.9" />
|
||
<template #title>{{ child.title }}</template>
|
||
</el-menu-item>
|
||
</el-sub-menu>
|
||
<el-menu-item v-else :index="item.path || item.key">
|
||
<component :is="item.icon" :size="18" :stroke-width="1.9" />
|
||
<template #title>{{ item.title }}</template>
|
||
</el-menu-item>
|
||
</template>
|
||
</el-menu>
|
||
</template>
|
||
```
|
||
|
||
- [ ] **Step 3: 暴露菜单选择事件**
|
||
|
||
确认 `handleSelect()` 只 emit `navigate`；路由跳转由 `el-menu router` 完成，父布局只负责关闭移动抽屉。
|
||
|
||
- [ ] **Step 4: 运行类型检查**
|
||
|
||
Run: `pnpm typecheck`
|
||
|
||
Expected: 组件 props、事件和导航节点类型全部通过严格检查。
|
||
|
||
### Task 3: 接入 AppLayout 的移动抽屉状态
|
||
|
||
**Files:**
|
||
- Modify: `apps/client-web/src/layouts/AppLayout.vue:1-75`
|
||
|
||
- [ ] **Step 1: 增加移动菜单状态和路由联动**
|
||
|
||
脚本增加以下状态与清理逻辑：
|
||
|
||
```ts
|
||
import { computed, onBeforeUnmount, onMounted, ref, watch } from 'vue'
|
||
import { X } from '@lucide/vue'
|
||
import ClientSidebarMenu from '@/components/ClientSidebarMenu.vue'
|
||
|
||
const mobileMenuOpen = ref(false)
|
||
let previousBodyOverflow = ''
|
||
|
||
function closeMobileMenu() {
|
||
mobileMenuOpen.value = false
|
||
}
|
||
|
||
function handleEscape(event: KeyboardEvent) {
|
||
if (event.key === 'Escape') closeMobileMenu()
|
||
}
|
||
|
||
watch(() => route.fullPath, closeMobileMenu)
|
||
watch(mobileMenuOpen, (open) => {
|
||
if (open) {
|
||
previousBodyOverflow = document.body.style.overflow
|
||
document.body.style.overflow = 'hidden'
|
||
} else {
|
||
document.body.style.overflow = previousBodyOverflow
|
||
}
|
||
})
|
||
|
||
onMounted(() => document.addEventListener('keydown', handleEscape))
|
||
onBeforeUnmount(() => {
|
||
document.removeEventListener('keydown', handleEscape)
|
||
document.body.style.overflow = previousBodyOverflow
|
||
})
|
||
```
|
||
|
||
- [ ] **Step 2: 替换内联 `v-for` 侧栏链接**
|
||
|
||
删除 `clientNavigation`、六个菜单图标和 `icons` 数组的布局导入；删除 router 中的临时兼容导出。侧栏替换为：
|
||
|
||
```vue
|
||
<aside id="client-sidebar" class="client-sidebar" aria-label="客户工作台导航">
|
||
<div class="client-sidebar-mobile-header">
|
||
<strong>功能导航</strong>
|
||
<button type="button" aria-label="关闭导航" @click="closeMobileMenu"><X :size="20" /></button>
|
||
</div>
|
||
<nav>
|
||
<ClientSidebarMenu :active-path="route.path" @navigate="closeMobileMenu" />
|
||
</nav>
|
||
<div class="sidebar-help"><strong>需要帮助？</strong><span>联系您的专属客户经理</span></div>
|
||
</aside>
|
||
```
|
||
|
||
- [ ] **Step 3: 给移动菜单按钮补齐语义和行为**
|
||
|
||
根节点、遮罩和菜单按钮使用：
|
||
|
||
```vue
|
||
<div class="client-shell" :class="{ 'mobile-menu-open': mobileMenuOpen }">
|
||
<button v-if="mobileMenuOpen" class="client-sidebar-scrim" type="button" aria-label="关闭导航" @click="closeMobileMenu" />
|
||
<!-- existing header and sidebar -->
|
||
<button type="button" aria-label="打开导航" aria-controls="client-sidebar" :aria-expanded="mobileMenuOpen" @click="mobileMenuOpen = true">
|
||
<Menu :size="20" />
|
||
</button>
|
||
</div>
|
||
```
|
||
|
||
- [ ] **Step 4: 添加遮罩和移动关闭按钮**
|
||
|
||
确认遮罩位于侧栏之前、侧栏 z-index 高于遮罩；关闭按钮只在移动断点可见。
|
||
|
||
- [ ] **Step 5: 运行类型检查**
|
||
|
||
Run: `pnpm typecheck`
|
||
|
||
Expected: 通过；退出登录确认取消时保持现有页面。
|
||
|
||
### Task 4: 调整 client-web 导航样式和响应式行为
|
||
|
||
**Files:**
|
||
- Modify: `apps/client-web/src/styles/index.css:20-75, 220-270`
|
||
|
||
- [ ] **Step 1: 将侧栏改为可滚动的分组菜单容器**
|
||
|
||
用以下菜单变量与结构样式替换原 `.client-sidebar nav a` 规则：
|
||
|
||
```css
|
||
.client-sidebar { overflow: hidden; }
|
||
.client-sidebar nav { flex: 1; min-height: 0; overflow-y: auto; }
|
||
.client-nav-menu {
|
||
border-right: 0;
|
||
--el-menu-bg-color: transparent;
|
||
--el-menu-text-color: #52616b;
|
||
--el-menu-hover-bg-color: #f2f7f6;
|
||
--el-menu-active-color: var(--primary);
|
||
}
|
||
.client-nav-menu .el-menu-item,
|
||
.client-nav-menu .el-sub-menu__title { height: 44px; margin: 3px 0; border-radius: 7px; line-height: 44px; }
|
||
.client-nav-menu .el-menu-item.is-active { background: #e9f4f2; color: var(--primary); font-weight: 650; }
|
||
.client-nav-menu .el-sub-menu .el-menu-item { min-width: 0; padding-left: 46px !important; }
|
||
.client-nav-menu .el-menu-item svg,
|
||
.client-nav-menu .el-sub-menu__title svg { flex: 0 0 auto; margin-right: 11px; }
|
||
.client-nav-menu .el-menu-item span,
|
||
.client-nav-menu .el-sub-menu__title span { min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
|
||
```
|
||
|
||
- [ ] **Step 2: 增加焦点与触控反馈**
|
||
|
||
增加：
|
||
|
||
```css
|
||
.client-nav-menu .el-menu-item:focus-visible,
|
||
.client-nav-menu .el-sub-menu__title:focus-visible,
|
||
.client-page-heading button:focus-visible,
|
||
.client-sidebar-mobile-header button:focus-visible {
|
||
outline: 2px solid var(--primary);
|
||
outline-offset: 2px;
|
||
}
|
||
.client-sidebar-mobile-header { display: none; }
|
||
.client-sidebar-scrim { display: none; }
|
||
```
|
||
|
||
- [ ] **Step 3: 实现移动抽屉与遮罩**
|
||
|
||
在现有 `@media (max-width: 720px)` 中删除 `.client-sidebar { display: none; }`，加入：
|
||
|
||
```css
|
||
.client-sidebar {
|
||
display: flex;
|
||
width: min(286px, 86vw);
|
||
transform: translateX(-100%);
|
||
transition: transform .2s ease;
|
||
}
|
||
.mobile-menu-open .client-sidebar { transform: translateX(0); }
|
||
.client-sidebar-scrim {
|
||
position: fixed;
|
||
inset: 68px 0 0 0;
|
||
z-index: 18;
|
||
display: block;
|
||
border: 0;
|
||
background: rgba(23, 50, 77, .46);
|
||
}
|
||
.client-sidebar-mobile-header {
|
||
display: flex;
|
||
min-height: 52px;
|
||
align-items: center;
|
||
justify-content: space-between;
|
||
padding: 0 14px;
|
||
border-bottom: 1px solid var(--border);
|
||
}
|
||
.client-sidebar-mobile-header button { display: grid; width: 44px; height: 44px; place-items: center; border: 0; background: transparent; color: var(--navy); }
|
||
```
|
||
|
||
- [ ] **Step 4: 防止移动端横向溢出**
|
||
|
||
保留 `html, body, #app { min-width: 320px; }`，并加入：
|
||
|
||
```css
|
||
.client-shell { overflow-x: hidden; }
|
||
.top-header, .client-main { max-width: 100%; }
|
||
```
|
||
|
||
在 320px 浏览器检查中确认 `document.documentElement.scrollWidth === document.documentElement.clientWidth`。
|
||
|
||
- [ ] **Step 5: 运行构建**
|
||
|
||
Run: `pnpm build`
|
||
|
||
Expected: `vue-tsc --noEmit` 与 `vite build` 均成功。
|
||
|
||
### Task 5: 完成浏览器与 Impeccable 验收
|
||
|
||
**Files:**
|
||
- Verify: `apps/client-web/src/navigation/clientNavigation.ts`
|
||
- Verify: `apps/client-web/src/components/ClientSidebarMenu.vue`
|
||
- Verify: `apps/client-web/src/layouts/AppLayout.vue`
|
||
- Verify: `apps/client-web/src/styles/index.css`
|
||
|
||
- [ ] **Step 1: 启动客户端开发服务器**
|
||
|
||
Run: `pnpm dev`
|
||
|
||
Expected: 输出 `http://localhost:5174/`；若端口被占用，记录实际端口并使用该端口验收。
|
||
|
||
- [ ] **Step 2: 验证桌面菜单**
|
||
|
||
使用预填账号 `customer / 123456` 登录，确认只有“业务总览”直接一级可达；“头程业务”和“企业管理”可展开；四个企业入口和头程订单都能到达原有路由；当前路由高亮正确。
|
||
|
||
- [ ] **Step 3: 验证移动菜单**
|
||
|
||
在 720px、390px、320px 视口确认：点击汉堡按钮打开抽屉，遮罩出现；点击二级菜单后抽屉关闭并完成路由切换；点击遮罩和按 Escape 均可关闭；页面无横向溢出。
|
||
|
||
- [ ] **Step 4: 运行 Impeccable 机械检测**
|
||
|
||
Run: `node C:\Users\BY\.codex\skills\impeccable\scripts\detect.mjs --json src\layouts\AppLayout.vue src\components\ClientSidebarMenu.vue src\navigation\clientNavigation.ts`
|
||
|
||
Expected: 0 条未解释告警；若有告警，逐条处理或在交付说明中记录明确原因。
|
||
|
||
- [ ] **Step 5: 复跑质量门禁**
|
||
|
||
Run: `pnpm typecheck; pnpm build`
|
||
|
||
Expected: 两个命令均成功后再声称完成。浏览器不可用时必须说明采用源码与 HTTP 回退证据。
|