2026-09-03 一卡通人员全量转发与可选本地保存变更记录

已在 sync_user_list 落地：连接并取得总人数 → 一卡通每批最多 1000 人拉取并汇总 → 全量核数和字段校验 → 每 1000 条串行业务转发 → 业务零失败后按开关静默保存本地快照。

问题修正

• 一次请求 26,089 人时，ByteArrayOutputStream.toString() 为约 75 MB 响应创建字符串，导致 Android 堆 OOM。
• 修复后单次一卡通请求最多 1000 人，每页解析后只保留轻量人员记录；全部拉完后才业务上传。
• 原失败 BM is required 的原因是部门应取 CUSTDEPT。
• 当前映射为 CUSTDEPT → bm、OUTID → xh。
• 旧快照 26,082 人中 EMPCODE 仅 8 个不同值，OUTID 有 26,082 个不同值；第一次业务转发也只有 8 人成功，确认旧 EMPCODE 映射导致重复编号拒绝。
• 全部人员先完成映射校验，再发出第一批业务请求。
• 第二轮首批响应包含 unchanged=1；客户端现已接收该字段，并按 created + updated + unchanged + failed == total 校验汇总。

业务接口契约

• POST /api/oneCardTerminal/syncPersons。
• Content-Type: application/json; charset=UTF-8。
• 顶层 one_card_type 固定为 新开普。
• items 每批 1..1000；2601 条验证为 1000 + 1000 + 601。
• 继续校验 code、total/created/updated/unchanged/failed 和 trace_id；旧响应缺少 unchanged 时按 0 兼容。

全量获取

• 连接返回总人数直接驱动 1000 人分页，不重复取人数。
• 首批 custid=0，后续按最大 CUSTOMERID + 1 推进；26,089 人为 27 个源端分页。
• 0 人不调用非法查询；累计数量、游标和跨页账号必须通过校验。
• 源端与业务端的 1000 上限分别由独立常量维护。

本地保存开关

• “一卡通设置”新增“本地是否保存人员数据”，默认关闭。
• MMKV 键：setting_onecard_save_person_data_locally；每轮开始时冻结值。
• 关闭时不创建 SQLite 仓库；打开且业务累计失败为 0 时才在后台保存。
• 完整快照单事务替换，失败回滚旧快照；本地异常只记日志，不改判业务结果。

主要代码变更

• 新增 CustomerFetchResult、CustomerFullFetchService、CustomerLocalSaveService。
• 业务服务改为直接处理完整内存列表；SQLite 增加 replaceSnapshot()。
• 协调器和运行任务落地新顺序与开关装配。
• 请求 DTO / Retrofit 增加固定一卡通类型和 JSON Header。
• 响应 DTO 和业务同步服务增加 unchanged 映射与汇总校验。
• 设置页面增加 SwitchButton；文案和尺寸进入资源。
• 删除旧 CustomerSyncService、CustomerSyncResult 和旧分段入口。

自动化验证

• :app:testDebugUnitTest :app:assembleDebug：156 个测试，0 skipped、0 failure、0 error，Debug APK 构建成功。
• :app:assembleDebug：通过。
• APK 约 64 MB；SHA-256：61a98aa76ca6325f92e812718b23bfe90a929a088dbe51a6eb7f720f44a02053。
• git diff --check 通过；旧字段、固定 50000 和旧服务引用扫描为空。

测试覆盖

• 0 人、2601 人分页、26,089 人的 27 页规模、游标推进、超量响应和跨页重复。
• 字段映射、固定 type、JSON Header、1000 条边界和 2601 条分批。
• 业务响应包含 unchanged 时按完整汇总公式校验。
• 后段脏数据上传前阻断；拉取 / 上传 / 人员失败不保存；本地异常隔离。

真机验证与剩余项

Git 状态

源码分支 sync_user_list；未暂存、提交、推送、合并或切换分支。