# 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 第二批（报销与支付链路）
4. `reimburse-apply`（报销申请）
   - 对齐：标题生成、费用项联动、明细维护、附件、保存/提交。
5. `reimburse-approve`（报销审批）
   - 对齐：待审批/已审批列表、审批动作、意见、审批历史。
6. `payment`（支付处理）
   - 对齐：待支付、支付确认、单笔冲抵、批量冲抵、冲抵记录查询。

### 3.3 第三批（个人与汇总视角）
7. `mine`（我的申请单）
   - 对齐：筛选、分页、详情跳转、状态标签与动作。
8. `todo`（待我审批）
   - 对齐：待办聚合、按业务类型跳转、红点与计数一致。
9. `all`（全部申请单）
   - 对齐：管理角色全量查询、组合筛选、详情查看。

### 3.4 第四批（后台配置能力）
10. `user-manage`
11. `role-manage`
12. `menu-manage`
13. `project`
14. `wf-advance`
15. `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`