shanxia/bx/docs/superpowers/specs/2026-04-29-bx-mobile-align-web-design.md

BX Mobile 对齐 Web 功能设计

日期： 2026-04-29
项目： bx 报销子系统
范围： bx/bx-mobile 对齐 bx/bx-web（功能一致优先）

1. 目标与边界

1.1 目标

• 将 bx/bx-mobile 业务功能补齐到与 bx/bx-web 一致。
• 优先保证业务流程、权限可达性、状态流转一致。
• 推进顺序按 web 菜单顺序逐页对齐，确保可跟踪、可验收。

1.2 已确认约束

• 一致性标准：功能一致优先（允许移动端交互形态差异）。
• 改造范围：前后端均可调整（bx/bx-mobile + bx/bx-backend）。
• 执行顺序：按 web 菜单顺序逐页对齐。

1.3 非目标

• 不做像素级视觉完全复制。
• 不做与“功能一致”无关的大规模重构。

2. 对齐策略

采用“菜单驱动逐页对齐 + 闭环验收”：

1. 建立 web->mobile 对照清单（页面、API、动作、权限、状态）。
2. 逐页补齐功能遗漏与界面遗漏。
3. 每页完成即联调，验证关键业务闭环。
4. 每一批完成后执行角色回归与流程回归。

该策略优先降低漏项风险，并保证进度透明。

3. 菜单级任务分解

3.1 第一批（备用金链路）

1. advance-apply（备用金申请）
   • 对齐：新建/编辑/提交、附件绑定、金额校验、草稿与已提交区分。
2. advance-approve（备用金审批）
   • 对齐：待审批列表、详情、同意/驳回、审批意见、审批记录。
3. advance-issue（备用金发放）
   • 对齐：待发放列表、实际发放金额、发放备注、发放结果追溯。

3.2 第二批（报销与支付链路）

1. reimburse-apply（报销申请）
   • 对齐：标题生成、费用项联动、明细维护、附件、保存/提交。
2. reimburse-approve（报销审批）
   • 对齐：待审批/已审批列表、审批动作、意见、审批历史。
3. payment（支付处理）
   • 对齐：待支付、支付确认、单笔冲抵、批量冲抵、冲抵记录查询。

3.3 第三批（个人与汇总视角）

1. mine（我的申请单）
   • 对齐：筛选、分页、详情跳转、状态标签与动作。
2. todo（待我审批）
   • 对齐：待办聚合、按业务类型跳转、红点与计数一致。
3. all（全部申请单）
   • 对齐：管理角色全量查询、组合筛选、详情查看。

3.4 第四批（后台配置能力）

1. user-manage
2. role-manage
3. menu-manage
4. project
5. wf-advance
6. wf-reimburse

对齐原则：保留移动端可用交互，但不能降低功能能力与结果一致性。

4. 数据流设计

4.1 API 访问约束

• 页面仅通过 bx/bx-mobile/src/api/index.ts 调用接口。
• 不在页面组件中直接拼接后端 URL。
• 参数命名对齐 web；必要时在 API 层做参数适配映射。

4.2 状态流转一致性

• 统一状态链路：draft -> pending -> approved/rejected -> paid/offset。
• 状态文案、按钮可用性、列表过滤行为与 web 一致。

4.3 附件链路一致性

• 上传文件后拿附件 ID，再做业务绑定，最后提交业务单据。
• 禁止“附件已上传但未关联业务单”的无主数据残留。

4.4 权限一致性

• 路由守卫 + 页面操作按钮双层校验。
• 无权限时入口不可见，且直链访问也不可执行敏感动作。

5. 错误处理与交互保护

• 接口错误分层：网络错误、鉴权错误、业务校验错误分开处理。
• 提交类操作统一防重：loading + disabled。
• 表单失败后保留输入；附件失败支持单文件重试。
• 空数据区块显示统一空态，不隐藏信息区块。
• 金额/关键字段异常时禁止提交并定位错误项。

6. 测试与验收口径

6.1 页面验收（逐页）

每页至少通过以下五项：

1. 入口可达
2. 列表正确
3. 详情正确
4. 关键动作可执行
5. 状态回写正确

6.2 角色验收

至少覆盖四类角色：

• ADMIN
• FINANCE
• GENERAL_MANAGER
• 普通申请人

6.3 流程验收

• 备用金：申请 -> 审批 -> 发放 -> 记录追溯。
• 报销：申请 -> 审批 -> 支付/冲抵 -> 记录追溯。

6.4 一致性验收标准

• 同账号、同筛选条件下，web 与 mobile 的：
  • 数据范围一致
  • 状态一致
  • 可执行动作一致

6.5 完成判定

• 核心链路无阻塞缺陷。
• 关键页面无高优先级缺陷。
• 菜单对齐清单全部关闭。

7. 风险与缓解

• 风险：web 与 mobile 字段口径不一致。
  缓解：以 API 层做字段归一，页面只消费统一结构。

• 风险：支付/冲抵规则复杂导致回归缺陷。
  缓解：先覆盖金额计算与状态回写的核心用例，再扩展边界用例。

• 风险：后台配置页在移动端交互复杂。
  缓解：优先保障功能可达，复杂交互分步提交，不牺牲能力。

8. 实施后续

本设计确认后，进入实现计划阶段：

• 使用 writing-plans 生成可执行任务计划（含文件路径、步骤、测试命令、验收标准）。

9. 批次范围冻结（按实现计划）

• Batch-1：advance-apply、advance-approve、advance-issue
• Batch-2：reimburse-apply、reimburse-approve、payment
• Batch-3：mine、todo、all
• Batch-4：user-manage、role-manage、menu-manage、project、wf-advance、wf-reimburse