2026-09-03 一卡通人员拉取独立日志与分段耗时变更记录

变更结论

一卡通人员全量同步现已将耗时拆分为“一卡通服务器拉取”“业务服务器同步”和“可选本地保存”三段，并在同步弹框中分别展示状态、开始时间、结束时间和耗时。

自动拉取和手动拉取统一写入独立的 Log/人员拉取_yyyyMMdd.txt 文件；每轮日志包含触发来源、成功或失败状态、失败步骤、成功数量和各段耗时。现有日志查看弹框会自动列出该 .txt 文件。

同步批量边界

源端 2000 人/批仍需在目标设备用真实全量数据验证峰值内存；代码级通过不等同于已经证明不会 OOM。

三段计时口径

1. 一卡通服务器拉取

• 开始：控制器接受同步任务、准备连接一卡通服务器时。
• 结束：人员总数查询及全部源端分页拉取完成时；连接或拉取失败则以失败时刻结束。
• 该段包含连接、人数查询和全量分页，不包含业务上传。

2. 业务服务器同步

• 开始：源端完整快照拉取成功后、业务端第一批上传前。
• 结束：最后一批业务响应完成或业务上传失败时。
• 业务端仍固定每批最多 1000 条，不包含本地保存耗时。

3. 本地保存

• 仅在“本地是否保存人员数据”开关启用时展示和计时。
• 开始：本地完整快照保存前；结束：保存成功或失败时。
• 前置阶段失败导致未执行时显示“未执行”，不伪造耗时。
• 本地保存失败单独展示和记录，不反向否定已经成功的业务服务器同步。

独立日志

• 文件前缀通过资源 local_person_pull_log_file_prefix=人员拉取_ 统一维护。
• 复用 LocalFileRecorder 的外部存储目录、日期格式、.txt 后缀和异步追加方式。
• 日志磁盘清理时会与同日期其他业务日志一起删除人员拉取日志。
• 自动入口记录 trigger=AUTO，手动入口记录 trigger=MANUAL。
• 每轮使用 syncId 关联开始、连接、源端分页、业务批次、本地保存和最终结果。
• 不记录姓名、卡号、人员编号、照片、特征值、服务地址、应用标识或 SOAP 原文。

主要事件：PERSON_PULL_START、PERSON_PULL_CONNECT_SUCCESS、PERSON_PULL_FETCH_BATCH_SUCCESS、PERSON_PULL_FETCH_SUCCESS、PERSON_PULL_UPLOAD_START、PERSON_PULL_UPLOAD_BATCH_RESULT、PERSON_PULL_UPLOAD_SUCCESS、PERSON_PULL_UPLOAD_FAILURE、PERSON_PULL_LOCAL_SAVE_START、PERSON_PULL_LOCAL_SAVE_SUCCESS、PERSON_PULL_LOCAL_SAVE_FAILURE、PERSON_PULL_SUCCESS、PERSON_PULL_FAILURE。

失败终态通过 failedStage=CONNECT/FETCH/UPLOAD/LOCAL_SAVE 标记具体步骤，并记录错误类型和经过换行清理、长度限制的错误摘要。成功终态记录处理总数、成功数、失败数、源端耗时、业务端耗时、可选本地保存耗时和整轮耗时。

业务端返回的 unchanged 表示已存在且无需更新，本次将其计入成功数量，成功数统一为 total - failed。

弹框与状态保存

• 保留一卡通连接状态和服务器人员总数。
• “全量人员同步”区域拆分展示源端拉取与业务端同步；启用本地保存时增加第三段。
• 每段分别显示状态、开始时间、结束时间、耗时和对应数量/进度。
• 运行中的段显示“耗时：计算中”；未开始、未执行或旧状态没有分段数据时不推算耗时。
• MMKV JSON 增加三段状态和时间字段；旧 JSON 缺少字段时按 NOT_STARTED 兼容。

主要代码变更

• 新增 PersonPullLog，集中格式化独立日志并隔离日志写入异常。
• 扩展 ConsumptionPersonSyncCoordinator.Listener，提供三个阶段边界回调。
• 扩展状态模型与 JSON 编解码，保存三段结果、时间、耗时和本地保存摘要。
• 扩展控制器，区分自动/手动触发、生成单轮 ID、记录分段日志和失败步骤。
• 修改同步弹框及布局/字符串资源，按三段渲染。
• 累计业务端 unchanged 并修正成功数口径。
• 页面入口分别传递 AUTO/MANUAL 并装配 人员拉取_ 写入端。

自动化验证

• JDK：Corretto 8（1.8.0_482）。
• :app:testDebugUnitTest：164 个测试通过，0 failure、0 error、0 skipped。
• :app:assembleDebug：通过。
• git diff --check：通过。
• Debug APK：app/build/outputs/apk/debug/app-debug.apk，约 64 MB。
• APK SHA-256：913f9ca83b8891bde4c1491b563fcf9a3255d0f65f65e7be9d0f455f682fa0d1。

新增或更新的测试覆盖自动/手动触发、连接/拉取/上传失败步骤、三段状态与耗时、本地保存成功/失败隔离、旧 JSON 兼容、unchanged 成功数，以及业务端 1000 条分批边界。

未执行项

• 未安装 APK，尚未在真机弹框中做布局和滚动验收。
• 尚未在目标设备连续执行真实全量同步，未验证源端 2000 人/批的 Java Heap 峰值。
• 未执行 Git 暂存、提交、推送、合并、分支切换或工作树创建。

Git 状态

源码分支：shorten_sync_time；本记录不包含生产凭据或人员数据。