消费页面一卡通自动寻卡与人员同步设计

目标

在 ConsumptionActivity 进入后同时启动读卡器自动寻卡和人员全量同步：读卡器自动完成 USB 权限、连接与持续寻卡；人员同步从新开普一卡通 WebService 每批拉取 1000 条，形成完整本地快照后，再通过项目当前业务服务器地址分批调用 POST /api/oneCardTerminal/syncPersons。

已确认配置

• 设置页新增“一卡通服务器地址”和“一卡通 AppID”两个设置项。
• 默认服务器地址：http://10.128.1.19/WebService/Newcapec.eCard.ProxyWebService.asmx。
• 默认 AppID：6。
• 服务器地址必须使用 HTTP/HTTPS 且以 .asmx 结尾；AppID 必须是正整数。
• 设置值通过 MMKV 保存，默认值与键名集中维护，不在页面或同步流程中重复写入字面量。

总体架构

1. ConsumptionCardSearchManager：管理 USB 广播、权限申请、读卡器连接、寻卡轮询和资源释放。
2. ConsumptionPersonSyncCoordinator：按“连接一卡通 → 完整拉取 → 本地快照完成 → 业务系统上传”顺序编排一次同步。
3. BusinessPersonSyncService：从指定同步快照读取人员、映射接口字段、每批最多 1000 条顺序上传并汇总结果。

读卡器与人员同步分别使用单线程执行器，互不占用对方线程；所有 UI 更新切回主线程。

读卡器链路

进入页面

• onStart() 注册 USB 权限、设备接入和设备移除广播。
• 查找 VID/PID 匹配的新开普读卡器；未授权时自动申请权限，已授权时直接连接。
• 连接成功后按固定轮询间隔调用 findCard()。

寻卡与退出

• NO_CARD 是正常状态，继续轮询；找到卡片后显示 UID 并等待移卡，避免重复触发。
• 连续确认卡片移除后恢复寻卡；设备移除或致命错误会停止本轮寻卡并显示状态。
• onStop() 停止寻卡并注销广播，onDestroy() 关闭线程并断开设备。

人员全量拉取链路

1. 从 MMKV 读取服务器地址与 AppID，没有保存值时使用确认的默认值。
2. 调用 GetCustomerCount 验证连接并取得总人数。
3. 复用 CustomerSyncService，每批 1000 条调用 GetCustomerByNum。
4. 每批写入 SQLiteCustomerRepository，仅在数量完整时完成快照并删除旧人员。
5. 拉取、解析或落库失败时不调用业务系统。

业务系统上传链路

• 接口：POST /api/oneCardTerminal/syncPersons，继续使用当前 Base URL、鉴权和日志拦截器。
• 从成功完成的 syncId 快照按人员账号顺序读取，每批最多 1000 条并顺序上传。

映射不截断字符串，也不为缺失或非法数值编造默认值。每批成功且 code == 0 后继续下一批；汇总 total/created/updated/failed 并记录 trace_id。业务失败数会累计，HTTP 错误、非零 code、空响应或数量不一致会停止后续批次。

页面状态

• 读卡器状态：未检测到设备、申请权限、连接中、寻卡中、已检测到卡片、等待移卡、连接异常。
• 人员同步状态：连接一卡通、拉取进度、业务上传进度、同步完成汇总、同步失败。
• 文案放入 strings.xml，尺寸与间距放入 dimens.xml。

错误与恢复

• 一卡通拉取失败时不执行旧人员清理；已落库批次只作为失败同步痕迹，禁止上传业务系统。
• 业务上传中断时保留完整本地快照，页面显示失败批次；重新进入页面可重新执行全量同步。
• 单批业务响应包含失败人员时累计失败数和 trace ID，不盲目重试整批。
• 页面销毁后忽略迟到回调。

测试与验收

1. 覆盖配置默认值、保存值、非法输入、人员字段映射与边界。
2. 覆盖 0、1000、1001 条、部分失败、非零响应、中途异常和拉取失败不上传。
3. 覆盖自动寻卡连接、检测到卡、移卡确认和停止状态。
4. 使用 JDK 8 运行单元测试、Debug 构建、格式检查与只读差异检查。

范围边界

• 不实现扣费、钱包选择或消费记录上传。
• 不新增第三方依赖，不改变现有业务 Base URL、鉴权或日志策略。
• 不执行 Git 暂存、提交、推送、分支切换或其他 Git 写操作。