绑盘机消费业务全链路日志实施记录

版本：V1.4
日期：2026-08-28
对应方案：2026-08-28-consumption-business-flow-logging-plan.md

1. 实施结论

消费业务全链路日志已从规划进入代码实现。应用新增独立的 ConsumptionFlowLog 日志类型，以 flowId 串联：

放盘 → 接口 B → 订单校验与金额分流 → 等待卡片 → 消费前读卡 → 扣款 → 消费后读卡 → 本地落库 → 接口 C 首传 → 后台补传 → 终态与复位

日志保存于设备外部存储根目录的 /Log/，与现有本地日志放在一起，格式为 UTF-8 JSON Lines。管理员进入“设置 → 日志查看”后，可以在 [消费流水] 分类中按时间线查看；原有 ReaderLog 继续保存 USB、APDU、PSAM 和钱包协议细节。升级时会将旧版内部 files/consumption_flow_logs/ 文件迁移到统一目录。

2. 已落地内容

2.1 独立日志存储

• 文件名：consumption-flow-YYYY-MM-DD.jsonl，超限后增加序号。
• 单文件上限：10 MB；目录上限：200 MB；保留30天。
• 单线程异步写入，业务线程只提交事件；写入失败降级 Logcat，不中断扣款。
• 每条日志包含格式版本、时间、单调时间、事件序号、业务流水号、中文事件名称及白名单业务字段。
• 文件中的核心 JSON key 直接使用中文，例如 时间、事件、业务流水号、订单号、餐盘号、阶段、结果、金额(分)、耗时(毫秒)、错误码、错误信息 和 明细。
• 事件 字段的值也改为中文；旧文件中的英文事件码由日志查看器实时转换，不要求迁移历史文件。
• 普通事件连续逐行写入；只有 业务流程结束 事件写完后增加一个空行，用于分隔前后两笔业务。

2.2 业务节点

• 餐盘：保留识别成功、移盘；锁定期间重复识别、正常扫码器开启等高频正常状态不进入业务流水。
• 服务端：接口 B 保留请求开始和一次合并结果；接口 C 每次实际请求保留一次结果、耗时、业务码和 traceId，不记录认证头和完整报文。
• 卡交易：保留发现卡、前读结果、扣款结果、后读结果和异常一致性校验；正常读卡器状态、阶段开始和成功武装不重复记录。前读、扣款、后读三个结果事件均新增嵌套的 协议解析结果，结构固定为 code/message/data，不是转义后的 JSON 字符串。
• 前读和后读的 data 保存协议解析字段：cardClass、customerID、cardNO、cardSN、status、subType、ze、ye、opCount、subYe、subCount、cardASN。
• 扣款的 data 保存请求金额、实际完成金额、完整性标记和各钱包交易明细；交易明细包含客户号、钱包类型、金额、前后余额、前后交易次数、PSAM 编号、PSAM 流水号、TAC、交易时间及 PSAM 确认结果。
• 本地数据：订单、三阶段交易及接口 C 队列只保留一次落库结果，失败信息仍完整保留。
• 补传：每批50条、单轮最多100条；空轮次不写日志，有实际任务、失败或跳过时才记录轮次结果和逐订单反馈结果。
• 收尾：每笔业务只保留一次“业务流程结束”；异常交易保护、页面销毁等必要诊断事件继续保留。

2.3 精简后的典型无订单路径

餐盘有识别结果、但接口 B 没有查到待结算订单时，业务流水固定聚焦为5个事件：

识别到餐盘 → 开始查询订单 → 订单查询完成（失败原因） → 餐盘已移走 → 业务流程结束

精简前同一场景会出现创建流水、重复餐盘、订单二次校验、终态和复位等10条左右事件；这些信息或可由上下文推导，或属于正常高频噪声，现已合并或移除。网络不可用、硬件异常、落库失败、接口 C 失败和卡片中途移走等异常仍会单独记录。

2.4 重启后的关联

consumption_records.db 升级至版本2，新增 flow_id。旧记录升级时生成 legacy-{orderNo}，新记录保存真实 flowId；因此接口 C 在应用重启后的后台补传仍能回到原订单流水。

2.5 查看方式

现有日志查看弹窗同时列出普通日志和 [消费流水] 文件。消费 JSONL 在界面中转换为：

时间 | 事件 | 业务流水号 | 订单号 | 餐盘号 | 接口 | 阶段 | 结果 | 金额 | 耗时 | 错误码 | 服务端追踪号 | 明细

新写入的原始 JSONL 已采用中文核心 key 和中文事件值；同一笔业务内的事件连续逐行显示，业务流程结束后留一个空行，直接通过文件管理器或 ADB 导出后也能理解；查看器仍兼容旧版英文 key 和英文事件码日志。

3. 数据记录与安全边界

消费流水仍不写 Access-Token、HTTP headers、完整 UID、原始 APDU 字节或接口 C 完整请求。原始 APDU 继续由 ReaderLog 保存，避免同一底层报文重复进入业务流水。

经现场明确要求，为了能够直接核对三阶段协议解析结果，消费业务日志从 V1.4 起完整保留 customerID、cardNO、cardASN、余额、交易次数以及扣款阶段的 PSAM/TAC 等解析字段。它们属于本机诊断敏感数据，只用于设备本地排障，继续受 /Log/ 目录容量、保留30天和设备访问权限约束。本次没有把 UID 加入该结构，因为用户确认的协议结果字段中不包含 UID。

4. 验证与验收边界

• 自动化覆盖普通事件连续写入、仅业务结束后加空行、轮转、多行拒绝、旧目录迁移、中文 key/事件值序列化、旧英文 key/事件码兼容、管理员可读格式化，以及三阶段协议解析结果的对象结构与原始 APDU 排除规则。
• JDK 8 完整单测共100个，0 failure、0 error、0 skipped；Debug APK 构建成功（BUILD SUCCESSFUL in 54s，当前 APK 64,329,946 字节）。
• 真机仍需由用户协助覆盖：正金额成功、PSAM失败、三阶段移卡、接口 C 断网补传和应用重启补传。
• 本次没有修改一卡通扣款协议、服务端接口字段或资金业务判断。

5. 记录原因

此前日志规划虽已形成文档，但运行代码只有分散的 ReaderLog、HTTP 日志和交易数据库，无法按一笔订单直接查看完整过程。本记录用于区分“规划完成”和“代码已落地”，并给后续真机验收提供固定的日志路径、字段边界和验证口径。