一卡通人员全量转发与可选本地保存设计

文档信息

1. 背景与现场结论

现有实现先按 1000 条从新开普一卡通拉取并写入 SQLite，形成完整本地快照后，再从 SQLite 按 1000 条读取并转发业务服务器。

• 2026-09-03 真机核对：新开普全量人员共 26,082 条，源端拉取和本地落库成功。
• 业务转发在发出请求前失败，错误为 BM is required。
• 源端部门字段为 CUSTDEPT；人员编号应使用 OUTID。旧快照 26,082 人中 OUTID 全部不同，EMPCODE 仅 8 个不同值，旧映射造成业务端重复编号拒绝。
• 同步状态 pulledCount=26082、processedCount=0，失败点是本地字段映射，不是一卡通连接或业务 HTTP 接口。
• 一次请求 26,089 人后，真机在 ByteArrayOutputStream.toString() 将约 75 MB 响应复制为字符串时 OOM，源端必须限制单次响应体量。

2. 已确认需求与技术决定

1. 先取得总人数，再按每批最多 1000 人调用 GetCustomerByNum；首批 custid=0，后续按上一批最大 CUSTOMERID + 1 推进。
2. 所有分页须全部解析、跨批去重和严格核数，并在发出第一批业务请求前完成全部字段映射校验。
3. 调用 POST /api/oneCardTerminal/syncPersons 时每批最多 1000 条，按原顺序串行转发。
4. 采用 JSON，Content-Type: application/json; charset=UTF-8。
5. 请求增加 one_card_type，固定为 新开普，协议常量集中定义。
6. “一卡通设置”增加“本地是否保存人员数据”，默认关闭并由 MMKV 持久化。
7. 开关关闭时不创建、不写入本地快照；打开时仅在全部业务批次成功且 failed == 0 后静默保存。
8. 本地保存失败只记录错误，不反向改判已完成的业务转发。
9. 不修改业务 Base URL、鉴权和网络日志策略。

3. 范围

In Scope

• 源端 1000 人分页获取并汇总、正确字段映射、1000 条 JSON 分批转发。
• 一卡通设置页保存开关、后置静默本地快照。
• 同步状态、日志、单元测试、构建和真机验证。

Out of Scope

• 不修改一卡通服务端或业务服务器。
• 不实现单人补偿队列、失败明细下载或断点续传。
• 不修改读卡、绑盘、扣费和消费记录上传，不新增第三方依赖。
• 不执行 Git 暂存、提交、推送、分支切换等 Git 写操作。

4. 参与者与数据边界

5. 成功与失败后置条件

• 成功：所有业务批次 code == 0 且累计 failed == 0；开关关闭时本地不写入，打开时保存完整快照。
• 拉取、核数或映射失败：不上传、不保存。
• 业务批次失败：停止后续批次、不保存；已成功批次无法由终端回滚。
• 某批存在失败人员：完成剩余转发并报告部分失败，但不保存本地。
• 本地保存失败：事务回滚、保留旧快照、记录日志，业务转发仍判成功。

6. 主流程

7. 分支与异常 / 恢复

8. 字段与接口契约

不得截断字符串或为非法值补默认值。

业务请求：POST /api/oneCardTerminal/syncPersons；Content-Type: application/json; charset=UTF-8；每批 1..1000 条。

{
  "one_card_type": "新开普",
  "items": [{
    "bm": "013",
    "xh": "employee001",
    "name": "示例人员",
    "sex": 1,
    "customerid": 1,
    "cardno": 655493,
    "status": 1,
    "cardsn": 2
  }]
}

接口资料中的 OpenAPI form-urlencoded 描述与 JSON 示例冲突，本轮以用户确认的 JSON 契约为准；下载目录中的原资料不改动。

业务成功响应兼容 unchanged（已存在且无需更新）；旧响应缺失时按 0 处理，汇总按 created + updated + unchanged + failed == total 校验。

9. 设置与本地保存契约

• 页面 / 标签：“一卡通设置” / “本地是否保存人员数据”；复用现有 SwitchButton。
• MMKV 默认值 false；每轮开始时读取一次，同步中切换只影响下一轮。
• 只有全部业务批次结束且累计失败为 0 才保存。
• 完整快照在一个 SQLite 事务中替换；失败不得留下半份新快照。
• 保存过程无独立进度或弹窗，只写开始、数量、耗时和失败日志。

10. 实现边界

• 全量人数来自本轮 GetCustomerCount，不使用固定 50000。
• 一卡通拉取由 CustomerFullFetchService.SOURCE_PAGE_SIZE = 1000 维护；业务上限由 SyncPersonsRequest.MAX_ITEMS = 1000 维护，两者不复用。
• 拆分全量获取、业务转发、可选本地保存三个职责，由协调器顺序调用。
• 开关关闭时不实例化本地人员仓库。

11. 验收标准

12. 测试矩阵

13. 非功能、安全与可观测性

• 容量至少覆盖现场 26,089 条；单个 SOAP 原始响应最多承载 1000 人。
• 业务批次串行；每个源端分页解析后释放原始 XML，只保留轻量记录，任务结束后释放全量对象。
• 日志不打印完整请求体，只记录人数、批次、业务标识、字段、耗时和 trace ID。
• 失败重试从第一批重新转发，依赖业务端按人员唯一标识幂等更新。
• 单批 1000 人沿用现有网络超时，并记录每批请求与解析耗时。

14. 风险、回滚与待确认项

• 代码可回滚到旧的“先本地快照、再上传”流程。
• 本地事务失败回滚旧快照；不涉及数据库版本迁移。
• P0 待确认项：无。
• 本轮没有唯一云效项目 / 需求编号，本文作为本地可执行需求真源；不声称已同步云效。

15. 追踪矩阵

16. 变更记录