refactor: 菜单栏角色化降噪（role-based-navigation-simplification）
这个提交包含在：
@@ -167,8 +167,9 @@ header baseline instead of recreating page-local wrappers:
|
||||
|
||||
- `AppShellLayout` owns the PC shell background and content offset through
|
||||
`app-shell` and `app-shell-main`.
|
||||
- `Sidebar` and `NavLinks` own primary navigation grouping. The mental model is
|
||||
`工作` -> `业务` -> `财务` -> `管理` -> collapsed `更多`.
|
||||
- `Sidebar` and `NavLinks` own role-aware task navigation. The mental model is
|
||||
a short primary task list plus collapsed `更多`; management configuration is
|
||||
represented by one `管理` entry instead of many sidebar rows.
|
||||
- `Topbar` is a compact command surface: page title, group badge, user context,
|
||||
global search and notifications. Do not expand it back into a large hero.
|
||||
- `PageHeader` and `WorkspaceHeader` should use `page-header-shell`,
|
||||
@@ -181,6 +182,26 @@ header baseline instead of recreating page-local wrappers:
|
||||
**Why**: The shell/header baseline gives Wave3-5 pages a stable visual entry
|
||||
point and prevents each route from inventing a different title/action layout.
|
||||
|
||||
**Navigation Rules**:
|
||||
|
||||
- Sidebar entries should be role-aware and task-first for domestic tech startups
|
||||
under 10 people; do not expose all permission-allowed modules as a default
|
||||
module catalog.
|
||||
- Approvers see `待我处理`; ordinary employees should not see `待办` or
|
||||
`审批待办` in the sidebar by default.
|
||||
- PC leave navigation uses `请假记录` unless the current task explicitly opens OA
|
||||
emergency leave submission.
|
||||
- `个人设置` stays in the topbar account menu. Notifications stay in the topbar
|
||||
bell and notification center.
|
||||
- Finance labels should use work names such as `付款`, `应付账款` and `票据`;
|
||||
internal platform words like `AP 运营`, `ERP 集成` and `功能开关` should be
|
||||
hidden behind management wording or renamed for users.
|
||||
- `更多` is a lightweight collapsed row for low-frequency entries; do not add a
|
||||
sidebar explanation card, subtitle or onboarding copy around it.
|
||||
- Playwright navigation helpers should use exact names or anchored regex for
|
||||
short sidebar labels such as `管理`, otherwise fuzzy role-name matching can
|
||||
click longer labels such as `预算管理`.
|
||||
|
||||
**Example**:
|
||||
|
||||
```tsx
|
||||
|
||||
@@ -0,0 +1,2 @@
|
||||
{"file":"docs/产品设计规则.md","reason":"检查菜单职责、角色优先级、企微/OA 边界和新增功能进入一级导航的约束是否被遵守。"}
|
||||
{"file":".trellis/spec/hyb-oa/frontend-react-vite-design.md","reason":"检查全局 shell、导航壳层、前端验证和截图覆盖要求是否满足。"}
|
||||
@@ -0,0 +1,96 @@
|
||||
# 菜单栏角色化降噪重构设计
|
||||
|
||||
## Design Direction
|
||||
|
||||
采用“安静的任务型工作栏”：一级导航不是模块目录，而是每类用户今天最可能要点击的任务入口。视觉上保持当前 OA 工具气质，降低解释性文案和卡片感，让菜单通过排序、角色显隐和短中文名表达优先级。
|
||||
|
||||
## Information Architecture
|
||||
|
||||
### 普通员工
|
||||
|
||||
- 工作台
|
||||
- 报销
|
||||
- 请假记录
|
||||
- 我的进度
|
||||
- 更多
|
||||
|
||||
### 审批人 / 负责人
|
||||
|
||||
- 工作台
|
||||
- 待我处理
|
||||
- 报销
|
||||
- 项目
|
||||
- 团队
|
||||
- 更多
|
||||
|
||||
### 财务 / 管理员
|
||||
|
||||
- 工作台
|
||||
- 待我处理
|
||||
- 报销
|
||||
- 付款
|
||||
- 应付账款
|
||||
- 票据
|
||||
- 管理
|
||||
- 更多
|
||||
|
||||
具体入口仍受权限和 feature flag 限制；上面是目标信息架构，不代表绕过权限展示。
|
||||
|
||||
## Proposed Implementation
|
||||
|
||||
1. 服务端导航
|
||||
- 在 `server/src/services/workspaceSettings.js` 中统一用户可见文案：
|
||||
- `workflowTasks`: `待我处理`
|
||||
- `leaveRequests`: `请假记录`
|
||||
- `paymentBatches`: `付款`
|
||||
- `apOperations`: `应付账款`
|
||||
- `invoicePool`: `票据`
|
||||
- `featureFlags`: `功能管理`
|
||||
- `erpIntegrations`: `外部系统`
|
||||
- 调整 `DEFAULT_MODULE_VISIBILITY`：普通高频保留，低频配置、预算、集成、审计等默认后置。
|
||||
- 保证 `workflowTasks` 只对业务审批人、负责人、财务等可处理角色出现。
|
||||
- 避免普通员工看到财务、票据、管理、个人设置入口。
|
||||
|
||||
2. 前端导航分组
|
||||
- 在 `client/src/components/navigation/NavLinks.tsx` 中让服务端 placement 和角色语义成为主导。
|
||||
- 移除“按路径重新把 backup 提升到业务/财务”的行为，或改为只在同一后置层内排序。
|
||||
- `更多` 改为轻量 details/summary 行，无副标题、无大卡片。
|
||||
- 侧边栏一级分组减少到任务感更强的结构，避免展示过多 section label。
|
||||
|
||||
3. 侧边栏壳层
|
||||
- 在 `client/src/components/navigation/Sidebar.tsx` 移除 `今日优先` 说明卡。
|
||||
- 若需要轻量状态提示，后续只在有真实待处理数量时显示；本轮优先移除说明卡，不强制新增数据查询。
|
||||
|
||||
4. 顶部和账号入口
|
||||
- `个人设置` 保留在 `Topbar` 账号菜单，不出现在侧边栏。
|
||||
- 通知保留顶部铃铛，不加入侧边栏。
|
||||
|
||||
5. 移动底栏
|
||||
- 在 `client/src/components/mobile/MobileBottomNav.tsx` 中把审批人文案改为 `待办`，非审批人继续显示 `进度`。
|
||||
- 不新增移动底栏 `请假`。
|
||||
|
||||
6. 工作区设置页
|
||||
- 在 `client/src/pages/WorkspaceSetupPage.tsx` 中调整文案：从“主导航/管理区/隐藏”的模块视角，转成“常用入口/管理与低频/隐藏”或等价表达。
|
||||
- 保留现有能力，不在本轮开发复杂的拖拽或角色矩阵配置。
|
||||
|
||||
7. 文档和规则
|
||||
- 更新 `docs/产品设计规则.md`：新增功能默认不进一级侧边栏，必须先判断角色、频次和真实待办价值。
|
||||
- 更新 `.trellis/spec/hyb-oa/frontend-react-vite-design.md`：固化导航壳层和菜单降噪规则。
|
||||
|
||||
## Risk And Mitigation
|
||||
|
||||
- 风险：前端重分组和服务端 placement 互相打架，导致后置模块又被抬到一级。
|
||||
- 缓解：把服务端结果作为事实源，前端只排序和轻量归类；增加角色导航单测。
|
||||
- 风险：文案变更影响既有测试断言。
|
||||
- 缓解：同步更新导航、smoke 和截图断言。
|
||||
- 风险：管理合并入口没有完整管理首页承接。
|
||||
- 缓解：本轮可先指向现有工作区设置或现有管理承接页；不做管理页大改。
|
||||
- 风险：普通员工入口过少导致找不到低频功能。
|
||||
- 缓解：保留 `更多` 和全局搜索；低频能力隐藏/后置，不删除。
|
||||
|
||||
## Verification Plan
|
||||
|
||||
- 服务端角色导航单测覆盖 employee、manager、finance、admin、owner。
|
||||
- 前端 typecheck/build。
|
||||
- 截图检查 PC 1440 宽侧边栏和移动 390 宽底栏。
|
||||
- 文档 diff 检查新规则是否只沉淀产品事实和工程约束，不加入视觉细节到 `docs/产品设计规则.md`。
|
||||
@@ -0,0 +1,2 @@
|
||||
{"file":"docs/产品设计规则.md","reason":"产品体验事实源，包含小团队目标用户、OA/企微边界、首页/通知/个人设置职责边界。"}
|
||||
{"file":".trellis/spec/hyb-oa/frontend-react-vite-design.md","reason":"前端 shell、导航、A 类任务优先页面和验证要求的工程规约。"}
|
||||
@@ -0,0 +1,110 @@
|
||||
# 菜单栏角色化降噪重构
|
||||
|
||||
## Goal
|
||||
|
||||
把 PC 侧边栏和移动底部导航从“功能模块清单”改成“小团队任务入口”。默认菜单按角色、权限和使用频次显示，优先让用户看清今天要处理什么、要提交什么、要查什么进度；低频配置、后台管理、集成和审计能力后置到 `管理` 或 `更多`。
|
||||
|
||||
## What I Already Know
|
||||
|
||||
- 目标用户是国内、小于 10 人的科技初创公司，常见一人多岗，默认不是专职 OA 操作员。
|
||||
- 已通过 `grill-me` 和 `frontend-design` 审查确认：本轮只重构导航信息架构和菜单壳层，不顺手重构业务页面内容。
|
||||
- 当前前端主导航在 `client/src/components/navigation/NavLinks.tsx`，侧边栏在 `client/src/components/navigation/Sidebar.tsx`，顶部命令区在 `client/src/components/navigation/Topbar.tsx`。
|
||||
- 当前服务端导航注册和默认显隐在 `server/src/services/workspaceSettings.js`，系统导航接口为 `/api/system/navigation`。
|
||||
- 当前移动底部导航在 `client/src/features/mobile/navigation.ts` 和 `client/src/components/mobile/MobileBottomNav.tsx`。
|
||||
- 当前工作区设置页会展示模块显隐表：`client/src/pages/WorkspaceSetupPage.tsx`。
|
||||
- 现有文档已要求 `首页` 不承担常驻新手教学职责，`个人设置` 不承担权限维护默认面，`请假/考勤` 日常优先企业微信。
|
||||
|
||||
## Confirmed Decisions
|
||||
|
||||
- 侧边栏正式按角色显示不同首屏菜单，不再所有人共用一套模块清单。
|
||||
- PC 侧边栏 `请假` 改为 `请假记录`，提交请假不作为默认 PC 主入口；只有 OA 应急接管或指定管理场景才考虑显示提交入口。
|
||||
- 合并 `待办`、`审批待办`、通知、工作台之间的职责：审批人看到 `待我处理`，普通员工默认不显示 `待办`，通知只保留顶部铃铛，工作台只做摘要。
|
||||
- 管理入口从侧边栏多项展开改为一个 `管理`，进入管理页后再分 `人员与组织 / 流程与规则 / 系统与审计 / 功能管理`。
|
||||
- 财务入口改成真实工作名：`付款批次` -> `付款`，`AP 运营` -> `应付账款`，`ERP 集成` -> `外部系统`，`功能开关` -> `功能管理`。
|
||||
- `票据中心` 只对财务/票据管理角色保留，普通员工不显示。
|
||||
- `预算管理` 默认不放一级菜单，进入管理或更多。
|
||||
- 移除侧边栏顶部 `今日优先` 说明卡；后续只保留真实轻量状态提示，且没有真实数据时不显示。
|
||||
- `更多` 只作为低频入口折叠区，不放解释性副标题，不做大卡片。
|
||||
- 移动端底栏同步语义：`首页 / 待办或进度 / 报销 / 我的`，审批人显示 `待办`，非审批人显示 `进度`，不加入 `请假`。
|
||||
- 这套菜单规则要沉淀到 `docs/产品设计规则.md` 和 `.trellis/spec/hyb-oa/frontend-react-vite-design.md`，作为后续功能开发硬约束。
|
||||
|
||||
## Requirements
|
||||
|
||||
- R1: PC 侧边栏一级可见入口应按角色收敛到高频任务，不展示权限允许但低频的后台模块清单。
|
||||
- R2: 审批人/负责人/财务角色应看到 `待我处理`；普通员工默认不看到 `待办` 或 `审批待办` 入口。
|
||||
- R3: `审批待办` 用户文案统一改为 `待我处理`，同时保留原有路由 `/workflow/tasks`。
|
||||
- R4: PC `请假` 用户文案改为 `请假记录`；不得让 PC 默认菜单暗示 OA 是请假日常主办入口。
|
||||
- R5: `个人设置` 不出现在 PC 侧边栏，只从右上角账号菜单进入。
|
||||
- R6: 管理类入口在侧边栏合并为 `管理`；管理页内部再承接具体配置、人员、流程、审计和功能管理入口。
|
||||
- R7: 财务类入口使用真实工作名，避免 `AP 运营`、`ERP 集成`、`功能开关` 这类偏内部平台词占据主菜单。
|
||||
- R8: 前端不得把服务端 `backup` 或低频模块重新提升到 `业务` / `财务` 默认分组。
|
||||
- R9: `更多` 应是轻量折叠入口；不得使用说明卡、副标题或大圆角卡片样式。
|
||||
- R10: 移动底部导航对审批人显示 `待办`，非审批人显示 `进度`；移动底栏不加入 `请假`。
|
||||
- R11: 工作区设置页的模块显隐表达要与新菜单规则一致，减少“主导航/管理区/隐藏”导致的误解。
|
||||
- R12: 更新产品设计规则和前端 Trellis spec，明确新增功能默认不得直接进入一级侧边栏。
|
||||
|
||||
## Scope
|
||||
|
||||
- In scope: PC 侧边栏、系统导航 API、移动底部导航、管理聚合页、工作区设置文案、导航相关测试、产品设计规则和前端 Trellis spec。
|
||||
- Out of scope: 业务页面主体重构、路由路径迁移、审批状态机或权限模型重做、企业微信请假主办流程、生产部署和真实数据写入。
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [x] 普通员工 PC 侧边栏默认只显示少量高频入口，不出现 `待办`、`审批待办`、`票据中心`、`个人设置`、管理配置项。
|
||||
- [x] 审批人/负责人 PC 侧边栏显示 `待我处理`，不再显示 `审批待办`。
|
||||
- [x] 财务/管理员 PC 侧边栏显示真实工作入口，例如 `付款`、`应付账款`、`票据`、`管理`，低频配置不铺开。
|
||||
- [x] `请假` 在 PC 主菜单中改为 `请假记录`，移动底栏不新增请假入口。
|
||||
- [x] `更多` 是轻量折叠行，展开后只承载低频入口，无说明副标题和大卡片视觉。
|
||||
- [x] 侧边栏顶部不再显示 `今日优先` 解释卡。
|
||||
- [x] 移动底栏审批人显示 `待办`，非审批人显示 `进度`。
|
||||
- [x] 工作区设置页文案与新导航分层一致，不再鼓励把低频模块直接放进主导航。
|
||||
- [x] 导航相关单元测试覆盖普通员工、审批人、财务、管理员角色的菜单结果。
|
||||
- [x] 前端 typecheck/build 通过，并保留 PC/移动菜单截图证据。
|
||||
- [x] `docs/产品设计规则.md` 和 `.trellis/spec/hyb-oa/frontend-react-vite-design.md` 已更新菜单规则。
|
||||
|
||||
## Out Of Scope
|
||||
|
||||
- 不重构报销列表、审批中心、财务台账、管理页面主体内容。
|
||||
- 不改路由路径，除非现有路径无法承接新文案。
|
||||
- 不重做权限模型、审批状态机、企业微信请假主办流程。
|
||||
- 不新增真实生产数据写入、生产配置修改或企业微信写入。
|
||||
- 不把所有历史模块删除；低频能力以隐藏、更多或管理承接为主。
|
||||
|
||||
## Technical Notes
|
||||
|
||||
- 需要重点处理服务端导航和前端重分组的职责边界，避免服务端已后置的模块被前端路径规则重新提升。
|
||||
- 需要保持权限控制由服务端和现有权限工具兜底，前端只做展示和分组，不创造越权入口。
|
||||
- 管理合并入口可以先指向现有 `工作区设置` 或新建轻量管理聚合页；本轮不做深层管理页面大改。
|
||||
- 视觉方向按 `frontend-design`：安静、工具型、密集但可扫描；避免说明卡、营销式引导和模块堆砌。
|
||||
|
||||
## Test Plan
|
||||
|
||||
- `cd server && npm test -- --runInBand workspaceSettings.navigation.test.js` 或等价聚焦单测命令。
|
||||
- `cd client && npm run typecheck`
|
||||
- `cd client && npm run build`
|
||||
- 聚焦 Playwright/截图验证：
|
||||
- PC 普通员工侧边栏
|
||||
- PC 审批人/负责人侧边栏
|
||||
- PC 财务或管理员侧边栏
|
||||
- 移动底部导航审批人/非审批人文案
|
||||
- `git diff --check`
|
||||
|
||||
## Verification Results
|
||||
|
||||
- PASS: `cd server && node --check src/services/workspaceSettings.js`
|
||||
- PASS: `cd server && npm test -- workspaceSettings.navigation.test.js`
|
||||
- PASS: `cd server && npm run prisma:validate`
|
||||
- PASS: `cd client && npm run typecheck`
|
||||
- PASS: `cd client && npm run build`
|
||||
- PASS: `cd client && E2E_BASE_URL=http://127.0.0.1:3001 npx playwright test tests/e2e/visual-shell.spec.ts --workers=1 --reporter=list`
|
||||
- PASS: `cd client && E2E_BASE_URL=http://127.0.0.1:3000 npx playwright test tests/e2e/settings-governance.spec.ts --workers=1 --reporter=list`
|
||||
- PASS: `node scripts/qa/check-trellis-governance.mjs`
|
||||
- PASS: `python3 ./.trellis/scripts/task.py validate 05-29-role-based-navigation-simplification`
|
||||
- PASS: `git diff --check`
|
||||
- Screenshot evidence: `output/playwright/role-based-navigation-simplification/employee-desktop.png`, `manager-desktop.png`, `finance-mgr-desktop.png`, `employee-mobile.png`, `manager-mobile.png`.
|
||||
|
||||
## Definition Of Done
|
||||
|
||||
- 需求、实现、验证、文档和截图证据在本 Trellis task 中可追溯。
|
||||
- 代码提交使用中文 commit message，并引用 `role-based-navigation-simplification`。
|
||||
- 面向用户可测试前，如涉及部署，必须部署并完成公网检查后再告知用户可测。
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"id": "role-based-navigation-simplification",
|
||||
"name": "role-based-navigation-simplification",
|
||||
"title": "菜单栏角色化降噪重构",
|
||||
"description": "按国内 10 人以下科技初创公司的小团队使用场景，重构 PC 侧边栏与移动底部导航的信息架构，让菜单按角色和高频任务降噪。",
|
||||
"status": "in_progress",
|
||||
"dev_type": null,
|
||||
"scope": "frontend-backend-docs",
|
||||
"package": null,
|
||||
"priority": "P2",
|
||||
"creator": "shunli",
|
||||
"assignee": "shunli",
|
||||
"createdAt": "2026-05-29",
|
||||
"completedAt": null,
|
||||
"branch": null,
|
||||
"base_branch": "main",
|
||||
"worktree_path": null,
|
||||
"commit": null,
|
||||
"pr_url": null,
|
||||
"subtasks": [],
|
||||
"children": [],
|
||||
"parent": null,
|
||||
"relatedFiles": [],
|
||||
"notes": "",
|
||||
"meta": {}
|
||||
}
|
||||
在新工单中引用
屏蔽一个用户