77 行
7.5 KiB
Markdown
77 行
7.5 KiB
Markdown
# 低风险页面操作规范统一
|
||
|
||
## Goal
|
||
|
||
在不改变业务 URL、API、数据库、权限模型和状态机的前提下，统一高频页面的状态文案、首页信息优先级、权限可见性、审批动作解释、表单反馈和移动主动作，使用户在 PC 与移动端形成稳定预期。
|
||
|
||
## Confirmed Facts
|
||
|
||
- `StatusBadge` 未命中映射时直接显示原始 `status`，员工档案仍把 `employmentStatus` 直接传入，可能展示 `onboarding/probation/offboarding/inactive`。
|
||
- PC 工作台仍渲染常用入口和今日待处理，需按首屏任务优先原则复核顺序；移动首页仍无条件展示考勤说明卡，财务第三个指标值仍为静态 `OA`。
|
||
- `WelcomeDialog` 仍对所有用户硬编码“处理待办”等入口，未按审批权限过滤。
|
||
- `/todos` 状态筛选仍直接展示 `todo/doing/done/cancelled`，且“待办”与审批“待我处理”的产品命名容易混淆。
|
||
- 审批详情并列提供“退回/驳回”，但未解释后果差异；转审理由至少 10 字的门槛没有邻近说明。
|
||
- 费用标准仍向审批人显示“管控模式：阻断/预警”内部配置词。
|
||
- 页面提交失败既有 toast、页级红条和字段内联等多种方式，缺少按可恢复性划分的统一合同。
|
||
- 移动报销、移动审批、付款响应式页面分别复制了固定底部动作容器；`BusinessEditTemplate` 已提供可复用实现线索。
|
||
- 完整差旅已冻结，但 `TravelRequestsPage` 仍会在无创建权限且未选择记录时自动把第一条写入 `?id=`；修复该缺陷不恢复差旅能力。
|
||
- 当前有 58 个前端文件在普通用户路径拼接 `CODE: 中文消息`；共享 `resolveErrorMessage` 也直接返回带 code 的文本，必须成为本轮统一收敛入口。
|
||
|
||
## Scope
|
||
|
||
- 仅修改前端共享错误/状态/动作组件、PC/移动高频页面文案与布局、WelcomeDialog 权限过滤、Todo 状态显示和差旅页面自动选中 effect。
|
||
- 不改业务 URL、API、数据库、权限模型、审批/付款状态机或生产配置。
|
||
- 差旅只删除自动选择第一条记录的缺陷，不恢复冻结能力；合同、采购/资产路由迁移由其他子任务负责。
|
||
|
||
## Requirements
|
||
|
||
- R1：状态展示必须使用业务域映射；公共 `StatusBadge` 未知值显示“未知状态”，不得把技术枚举原样呈现给普通用户。
|
||
- R2：PC 工作台首屏把真实“今日待处理”置于常用入口之前；无待办时仍保持自然空态，不制造说明卡。
|
||
- R3：移动首页删除无真实数据的常驻考勤说明卡；财务指标只展示真实可比较数据，不能用 `OA` 占据数值位。
|
||
- R4：首次欢迎入口按当前用户权限与已启用能力生成；不得引导用户进入无权访问的审批页。
|
||
- R5：命名统一为“待我审批”（审批任务）、“我的事项”（个人 todo）和“今日待处理”（聚合面板）；路由可保持兼容，不因文案治理改 URL。
|
||
- R6：`todo/doing/done/cancelled` 等用户可见状态统一为自然中文。
|
||
- R7：审批详情明确说明“退回”和“驳回”的业务后果；转审理由在输入区邻近显示至少 10 字要求及未满足原因。
|
||
- R8：把“阻断/预警”等配置词转为审批人可执行的业务表达，不暴露内部控制字段名。
|
||
- R9：反馈合同固定为：短暂成功使用 toast；字段/材料问题就近内联；页面或区域加载失败在对应区域内持久显示并提供重试；不可恢复的提交失败不得只依赖会消失的 toast。
|
||
- R10：抽取或扩展共享移动底部动作容器，统一安全区、内容留白、主次动作层级和 pending/disabled 表达；页面业务动作仍由各自状态矩阵决定。
|
||
- R11：关键表单控件具有可关联 label、键盘可达性和清晰焦点；为登录、首页、审批详情、报销详情和移动报销详情中的本任务触点增加聚焦可访问性断言。
|
||
- R12：保留当前中文错误映射并收敛唯一解析入口；普通用户路径只返回自然中文，不显示错误 code、接口名、路由栈、完整路径或原始 payload。管理员、审计和排障页如确需 code，只在明确技术明细区域最小展示，不复用普通消息字符串。
|
||
- R13：优先复用现有 `ListWorkspace`、`BusinessListTemplate`、详情动作组件、错误映射和移动安全区样式，不新增第四套页面/反馈系统。
|
||
- R14：删除差旅首屏自动选择第一条记录的 effect；用户未显式选择时保持纯列表/空详情状态，不改差旅路由、功能入口或业务能力。
|
||
|
||
## Acceptance Criteria
|
||
|
||
- [ ] 员工档案和本任务触及页面不显示未映射英文状态；未知状态显示“未知状态”。
|
||
- [ ] PC 工作台首个业务内容区为“今日待处理”，常用入口后置；移动首页不再显示静态考勤说明卡或值为 `OA` 的指标。
|
||
- [ ] 无审批权限用户的 WelcomeDialog 不出现“处理待办”入口，其他入口同样按权限/能力过滤。
|
||
- [ ] PC/移动审批入口使用“待我审批”，个人 todo 使用“我的事项”，聚合区使用“今日待处理”；Todo 状态选项全部为中文。
|
||
- [ ] 审批人无需猜测即可区分退回/驳回后果；转审理由不足 10 字时在输入区看到明确原因。
|
||
- [ ] 费用控制提示说明超标事实、影响和下一步，不出现“管控模式”字段式表达。
|
||
- [ ] 成功、字段错误、区域加载失败和提交失败分别遵循统一反馈合同；聚焦回归证明错误可恢复且输入不丢失。
|
||
- [ ] 至少两个现有移动详情页复用共享底部动作容器，安全区和页面底部留白没有回退。
|
||
- [ ] 本任务触及的 A 类页面具有 label/键盘/焦点回归；若引入 axe，仅限聚焦页面，不把全站历史债务变成本任务阻断。
|
||
- [ ] 当前 58 个文件范围内的普通用户错误提示不再拼接内部 code；范围显式包含唯一收敛入口 `client/src/lib/resolveErrorMessage.ts`。代码搜索和聚焦页面回归证明没有同类前缀残留；`client/src/pages/AuditLogsPage.tsx` 作为 R12 允许的技术明细例外单独列出，不计入“无残留”判定。
|
||
- [ ] 直接进入 `/travel-requests` 且未带 `id` 时不自动写入第一条记录；用户显式选择后既有 `?id=` 详情仍可用。
|
||
- [ ] `cd client && npm run typecheck && npm run build`、聚焦 Playwright 与 Trellis 门禁通过。
|
||
|
||
## Out of Scope
|
||
|
||
- 详情路由、新建页路由、后端 API、数据库或状态机修改。
|
||
- 全站一次性迁移所有 toast、所有表单和所有页面骨架。
|
||
- 付款、报销、审批等业务动作权限或服务端规则调整。
|
||
- 冻结差旅的功能恢复、详情路由化、导航调整或能力扩展。
|
||
- 模块冻结/下线、导航产品组合调整和暗色模式。
|
||
|
||
## Test Plan
|
||
|
||
- `cd client && npm run typecheck`
|
||
- `cd client && npm run build`
|
||
- 聚焦 Playwright：工作台首屏与 WelcomeDialog 权限、审批动作解释、移动首页/底部动作、Todo 中文状态、差旅未自动选中。
|
||
- 运行普通用户错误前缀扫描；按当前 58 个文件范围核对残留，显式包含 `client/src/lib/resolveErrorMessage.ts`，并将 `client/src/pages/AuditLogsPage.tsx` 作为允许的技术明细例外单独检查、不计入“无残留”判定。
|
||
- 运行 `python3 ./.trellis/scripts/task.py validate 08-05-interaction-pattern-unification`、process contract、docs registry、Trellis governance 和 `git diff --check`。
|
||
|
||
## Open Questions
|
||
|
||
- 无；本子任务可在父任务范围确认后进入设计。
|