# 设计说明

## 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 或生产数据回滚步骤。