hyb-oa/.trellis/tasks/08-05-interaction-pattern-unification/design.md

设计说明

1. 目标与约束

本任务只处理不改变业务 URL、API、数据库、权限模型和状态机的交互一致性。允许修改共享前端工具与组件，但不得引入新的页面体系或全站视觉重做。

2. 错误消息收敛

• client/src/lib/resolveErrorMessage.ts 成为普通用户错误消息的默认入口：API error 只返回 mapApiErrorMessage(...) 的自然中文，不拼 code。
• 页面内重复的 isApiError + mapApiErrorMessage helper 逐步改为共享入口；本任务覆盖当前搜索到的 58 个文件。
• 管理、审计、排障页确需 code 时使用显式技术明细函数或独立明细区，不把 code 混进普通 toast/红条文本。
• 增加源码合同测试或 QA 搜索，阻止普通消息重新出现 error.code + ':' 模式。
• 失败反馈位置按可恢复性决定：字段/材料问题就近、区域加载失败驻留在区域并可重试、短暂成功 toast；本轮不全量迁移所有历史 toast。

3. 状态与命名

• StatusBadge 未知状态统一显示“未知状态”；业务域需要更具体文案时显式传 label 或使用域映射，不扩充一个无边界的全局状态表。
• 员工在职阶段使用独立中文映射，避免 employmentStatus 原样透出。
• TodosPage 状态筛选和徽章使用自然中文。
• 审批任务、个人事项、聚合面板分别使用“待我审批 / 我的事项 / 今日待处理”；内部路由和 API 字段保持不变。

4. 首页与首次欢迎

• PC 页面顺序调整为 SummaryStrip → TodayActionPanel → QuickEntryPanel → secondary。
• PortalHomePage 已拥有权限、角色能力和 quick entries；WelcomeDialog 从调用方接收经过权限过滤的入口，避免在弹窗内复制完整权限模型。
• 移动首页移除常驻考勤说明卡；财务第三指标改为真实数据或删除该 tile，不用静态 OA 填充。
• 无真实数据的区域不渲染，保留必要空态和真实下一步。

5. 审批动作解释

• 退回说明“返回可修改环节/发起人补充后可继续”，驳回说明“本次流程终止或按规则重新发起”；最终措辞必须对应现有服务端 action 语义，不改变 action。
• 转审理由输入区显示“至少 10 个字”和实时未满足原因；禁用按钮不能成为唯一反馈。
• 费用控制按超标事实、是否阻止通过和下一步表达，不显示 controlMode 字段式文案。

6. 共享移动底部动作

• 从 BusinessEditTemplate、移动报销、移动审批和付款响应式页面提取最小共享容器，统一 fixed surface、安全区、内容底部留白和主次动作布局。
• 共享组件只接收动作内容、是否显示和测试 ID，不承载报销/审批/付款状态机。
• 先迁移至少移动报销与移动审批；付款页仅在无业务风险且结构相同时迁移，否则保留并记录后续项。

7. 差旅冻结模块缺陷

• 删除 TravelRequestsPage 在无创建权限时自动选择第一条记录的 effect。
• 未带 id 时保持列表/空详情；显式选择后的既有 ?id= 详情不变。
• 不改变导航、API、创建能力、状态机或恢复差旅主线。

8. 可访问性与兼容

• 本任务触及的输入具有关联 label、键盘可达和焦点可见性；错误出现在关联字段/区域附近。
• 聚焦页面可增加 axe 或等价语义断言，但不把全站历史债务作为本轮阻断。
• 错误文案变化不改变 API code 本身；日志、服务端响应和审计数据保持原样。

9. 回滚

• 错误消息工具、移动动作容器和页面文案分批提交，任一共享改动可连同消费者同批回滚。
• 差旅只删除一个 effect，回滚不会修改数据；若回滚则恢复旧自动选择行为。
• 无 schema、API 或生产数据回滚步骤。