2026-09-03 人员拉取独立日志设计

目标

为消费页面的一卡通人员同步增加独立日志文件 人员拉取_yyyyMMdd.txt，并在同步弹框中分开展示一卡通拉取、业务服务器同步以及可选本地保存的状态和耗时。自动与手动同步共用同一记录链路，文件继续写入外部存储 Log 目录。

方案比较

方案 A：在同步控制器集中记录（采用）

• 统一记录自动、手动、阶段进度和整轮终态。
• 依据控制器当前阶段稳定记录失败步骤。
• 对 SOAP、业务接口和数据库实现侵入较小；现有 ReaderLog 保持不变。

方案 B：每个底层服务直接写文件

底层细节较多，但整轮关联复杂、重复内容多且改动范围更大。

方案 C：筛选复制 ReaderLog

当前事件缺少触发来源、连接结果、上传失败和整轮终态，无法直接满足要求。

文件生成规则

• 复用 LocalFileRecorder，文件前缀由字符串资源维护。
• 沿用每日文件、yyyyMMdd 日期和 .txt 后缀。
• 保持异步追加；日志失败不能改变人员同步结果。
• 现有日志查看弹框无需新增入口即可展示。

单轮关联与触发来源

• 自动入口传入 AUTO，手动入口传入 MANUAL。
• 任务被接受后生成 syncId，所有阶段使用同一个值。
• 运行中重复点击不生成新一轮开始日志，可记录任务运行中拒绝原因。

分段计时口径

一卡通服务器拉取

• 从任务被接受、准备连接一卡通开始，到全部人员分页拉取完成。
• 包含连接、总人数查询和全量分页；连接或拉取失败时保留失败耗时。

业务服务器同步

• 从一卡通全量拉取成功后、第一批业务上传前开始，到最后一批响应或上传失败结束。
• 不包含一卡通拉取和本地保存；每批仍固定最多 1000 条。

本地保存

• 仅在开关启用且业务同步零失败后，从完整快照保存前计时到成功或失败。
• 未启用时不展示；已启用但因前置失败未执行时显示“未执行”。
• 保存失败单独记录，但不反向否定业务同步结果。

弹框展示

• 保留连接区域；将人员同步拆成“一卡通服务器拉取”和“业务服务器同步”两个区域。
• 两个主要区域分别显示状态、开始时间、结束时间、耗时、进度和数量汇总。
• 启用本地保存时显示第三个区域，展示状态、起止时间、耗时和保存数量；未启用时隐藏。
• 运行中显示“计算中”，未开始或前置失败显示“暂无记录”或“未执行”。

日志事件

• PERSON_PULL_START：syncId、trigger、开始时间。
• PERSON_PULL_CONNECT_SUCCESS：一卡通总人数和累计耗时。
• PERSON_PULL_FETCH_BATCH_SUCCESS：批次、本批数量、累计拉取、预期总数和累计耗时。
• PERSON_PULL_FETCH_SUCCESS：拉取数量、起止时间和 sourceElapsedMs。
• PERSON_PULL_UPLOAD_BATCH_RESULT：批次、本批数量、累计处理、成功、失败和累计耗时。
• PERSON_PULL_UPLOAD_SUCCESS/FAILURE：业务阶段结果、起止时间和 businessElapsedMs。
• PERSON_PULL_LOCAL_SAVE_START/SUCCESS/FAILURE：保存数量、结果、起止时间和 localSaveElapsedMs。
• PERSON_PULL_SUCCESS：成功状态、数量汇总、各段耗时、整轮耗时、触发来源和 syncId。
• PERSON_PULL_FAILURE：失败状态、失败阶段、批次、进度、已执行阶段耗时、异常摘要、触发来源和 syncId。

成功数按 processed - failed 记录，使 unchanged 人员也计入成功。

数据与安全边界

• 不记录人员姓名、编号、卡号、手机号、照片、特征值或 SOAP 原文。
• 不记录服务地址和应用标识。
• 错误信息清理换行并限制长度；日志异常不影响同步。

实现边界

• 新增独立日志组件，并在同步控制器集中写入。
• 状态模型保存三个阶段的独立起止时间、结果和耗时，并兼容旧 JSON。
• 协调器提供阶段边界回调；页面自动和手动入口传递触发类型，不改变同步顺序。
• 弹框分别渲染一卡通拉取、业务同步和可选本地保存区域。
• 一卡通分页数量及业务端每批 1000 条保持不变。
• 现有 ReaderLog 和消费流水格式保持不变。

测试与验收

• 验证 AUTO/MANUAL、唯一开始与终态、CONNECT/FETCH/UPLOAD 失败阶段。
• 验证一卡通拉取含连接、业务上传独立、本地保存可选的三段计时边界。
• 验证各阶段成功、失败、未执行时的弹框显示。
• 验证数量、unchanged 成功口径、整轮及分段耗时和跨阶段 syncId。
• 验证文件名及现有日志弹框可见性。
• 运行相关单元测试、Debug 构建和 git diff --check。

不在本次范围

• 不新增远程上传、搜索、筛选或导出功能。
• 不记录人员明细或原始响应。
• 不改造旧的人脸数据同步日志。