绑盘机消费流程实施工作日志

日期：2026-08-27
状态：代码落地完成，等待真机与服务端环境验收

1. 记录说明

本日志记录本次对话从需求定稿到代码落地过程中必要的中间产物。每个记录项都包含产物、原因、证据和后续用途，避免只保留最终代码而无法解释关键决策。

2. 已完成记录

R-01 产品需求文档 V0.9.5

• 产物：docs/2026-08-27-consumption-product-requirements.md/.html。
• 记录原因：统一零元单、正金额支付、餐盘移走、卡片移走、接口 C 和补传规则，作为范围基线。
• 验证证据：Markdown/HTML 标题同步；关键业务规则扫描通过。
• 后续用途：开发验收和真机测试逐条对照。

R-02 方案 B 视觉定稿

• 产物：prototypes/2026-08-27-consumption-flow/final.html、scheme-b-ui-spec.md/.html 及6张状态证据图。
• 记录原因：三套方向中已选择金额聚焦型，需要固定页面层级、状态文案和交互基准。
• 验证证据：六类演示流程均到达末态；仅方案 B 可见；800px宽度无横向溢出；控制台0错误。
• 后续用途：Android 布局、字号、颜色、状态提示和验收截图基准。

R-03 接口 C 契约基线

• 产物：docs/2026-08-27-interface-c-contract-test-matrix.md/.html。
• 记录原因：新版 Apifox 接口替换旧字段，且零元单和正金额单请求不同。
• 验证证据：接口契约测试覆盖顶层字段、嵌套字段、零元真实读卡快照镜像和正金额三阶段数据。
• 后续用途：持久化请求快照、失败补传和服务端联调。

R-04 代码现状与测试基线

• 产物：本日志及 2026-08-27-consumption-code-implementation-design.md/.html。
• 记录原因：当前工作区已有大量未提交的消费、硬件和网络实现，必须保护有效代码并明确需求差距。
• 现状结论：可复用读盘、接口 B、读卡扣款及接口 C；必须重做用户页面、自动支付编排、移盘会话和持久化补传。
• 验证证据：使用 JDK 8 执行 bash gradlew :app:testDebugUnitTest --no-daemon，结果 BUILD SUCCESSFUL；23个测试类、80个测试、0 failure、0 error、0 skipped。
• 过程异常：第一次直接执行 ./gradlew 因文件没有执行权限而未启动；改用 bash gradlew，未修改文件权限。
• 后续用途：后续回归测试必须不低于该基线。

R-05 状态机与餐盘会话

• 产物：ConsumptionFlowStateMachine.java、ConsumptionFlowStateMachineTest.java，以及更新后的 ConsumptionOrderCoordinator 和测试。
• 记录原因：原实现把移盘当作取消事件，会丢弃在途订单；新需求要求锁定本次餐盘会话并继续向前推进。
• 实现结果：新增三页面纯 Java 状态机；所有有效订单自动进入等待放卡。零元单进入 READING_ZERO_AMOUNT_CARD 只读状态，正金额进入三阶段扣款；移盘只更新在位状态；终态且餐盘、卡片均已移走后才允许复位。订单协调器在会话锁定期间忽略重复码和新码，显式完成后才接受下一张餐盘。
• RED 证据：定向测试首次运行因状态机类和 completeSession() 尚不存在而产生33个编译错误，证明新规则先由测试表达。
• GREEN 证据：状态机、订单协调器和支付门控定向测试 BUILD SUCCESSFUL in 13s。
• 回归证据：全量单测 BUILD SUCCESSFUL in 10s；当前88个测试、0 failure、0 error、0 skipped。
• 后续用途：Activity 页面渲染、读卡阶段提示和复位逻辑统一使用该状态机，禁止重新在页面回调中散落业务判断。

R-06 本地交易记录

• 产物：ConsumptionRecordRepository、SQLiteConsumptionRecordRepository、ConsumptionTransactionSnapshotJson。
• 记录原因：接口 C 反馈不是交易事实的唯一载体；应用退出、网络异常或服务端失败时仍需保留订单及真实硬件阶段，避免重复扣款和无法追溯。
• 实现结果：独立数据库 consumption_records.db 以订单号为主键，关联餐盘码、订单金额、消费前读卡、扣款、消费后读卡、交易状态、错误码、接口 C 原始请求、上传状态、次数及下次重试时间。
• 保护规则：同一订单首次快照使用冲突忽略；已上传记录不被待上传结果覆盖；接口 C 使用持久化原请求补传，不重新计算字段。
• 后续用途：真机异常核对、重启恢复和服务端反馈追踪。

R-07 接口 C 补传

• 产物：ConsumptionReportSyncRunner、ConsumptionReportSyncScheduler、ConsumptionReportSyncReceiver、ConsumptionReportSyncWorker，以及应用启动/网络恢复接入。
• 记录原因：用户确认反馈成功或失败都继续前台业务，上传失败必须本地保存并每3分钟同步；记录批次和防并发规则可避免运维理解歧义。
• 实现结果：每批50条、单轮最多2批即100条；单条失败不阻塞其他记录；3分钟定时、应用启动和网络恢复统一进入 WorkManager 唯一任务；补传只调用接口 C，绝不触发读卡或扣款。
• 重复保护：前台入队时把后台最早接管时间设为3分钟后，避免前台请求尚在途时后台重复发送；服务端成功后本地标记 UPLOADED，不再入选。
• 验证证据：补传测试覆盖101条只处理100条、单条失败隔离和并发轮次跳过。
• 后续用途：现场断网、服务端失败、应用重启场景验收。

R-08 三页面与硬件阶段落地

• 产物：重构后的 ConsumptionActivity、activity_consumption.xml、方案 B 色板/尺寸/样式/面板资源及 please_place_card.wav。
• 记录原因：证明视觉定稿不是静态原型，而是已由同一状态机驱动的 Android 产品页面；同时固定用户可见文案边界。
• 实现结果：第一步等待餐盘；第二步展示订单号与金额，所有有效订单约1秒后进入第三步。零元执行单次完整读卡后反馈，正金额执行前读卡、扣款、后读卡；第三步统一处理遗留卡、等待新卡、反馈和终态。查询与卡片处理过程中不提示餐盘动作；卡片保护窗口持续提示不得拿走卡片。
• 语音规则：生成并接入“请放卡片进行支付”本地语音，每个订单会话只播放一次；消费页不再使用“请刷卡”。
• 交易安全：真实硬件阶段通过 ConsumptionCardTransactionExecutor 回调；前后卡不一致、金额不完整、部分扣款或后读卡失败均保存为异常并禁止自动重扣。
• 验证证据：资源链接、Java 编译和单测均通过；旧的临时测试地址、模拟订单和支付按钮门控类已删除。
• 后续用途：真机视觉、扫码器、读卡器和语音验收。

R-09 完整本地验证

• 产物：单测报告、Debug APK 和本日志证据。
• 记录原因：把“代码已写”与“本地可构建”区分开，并为真机测试提供确定安装包。
• 验证命令：JAVA_HOME=.../corretto-1.8.0_482/Contents/Home bash gradlew :app:testDebugUnitTest :app:assembleDebug --no-daemon --console=plain。
• 最终验证结果：BUILD SUCCESSFUL in 17s；84个测试、0 failure、0 error、0 skipped；app/build/outputs/apk/debug/app-debug.apk 约61 MB。
• 静态检查：git diff --check 通过；消费主流程不再引用临时 192.168.* 地址、模拟订单、支付按钮或 please_swipe_card。
• 生命周期检查：交易在途时短暂切后台不停止硬件串行任务，结果落库/反馈后再停止；交易期间返回操作被屏蔽。
• 已知构建提示：旧版 Android Gradle 环境仍输出 SDK schema 映射和 Java 8 build-tools 警告，不影响本次构建结果。

R-10 真机与服务端待验

• 产物：本记录中的现场验收边界。
• 记录原因：本地环境没有真实新开普读卡器、测试卡、餐盘扫码器和目标服务端数据，不能把编译通过误报为硬件验收完成。
• 待验场景：零元单只读卡且无消费 APDU、零元读卡失败后移卡重试、零元携卡接口 C；补贴足额/补贴加主钱包扣款；余额不足；遗留卡；前读卡、扣款、后读卡阶段移卡；餐盘提前移走；接口 C 失败后3分钟补传；应用重启后补传；同订单服务端最终状态。
• 协作方式：用户提供设备和环境，Codex 根据现场日志继续定位；真机测试前不再改动业务规则。

R-11 最终变更记录

• 产物：change_records/2026-08-27-consumption-scheme-b-code-implementation.md/.html。
• 记录原因：聚合本轮跨状态机、页面、硬件、本地数据库和后台任务的代码变化，说明旧记录的替代关系和回滚边界。
• 后续用途：代码审查、交接、真机验收和后续迭代。

R-12 消费业务全链路日志规划

• 产物：docs/2026-08-28-consumption-business-flow-logging-plan.md/.html。
• 记录原因：现有日志分散在 Activity、ReaderLog、HTTP 原始日志和交易数据库中，能保存关键证据，但无法按订单直接查看“放盘至反馈”的完整业务时间线。
• 规划结论：新增独立 ConsumptionFlowLog JSONL 日志类型，以 flowId 和 orderNo 贯穿放盘、订单、前读卡、扣款、后读卡、落库、接口 C、补传和复位；协议原文与 HTTP 原文仍由现有日志保存。
• 安全边界：R-12 最初规划不写完整卡字段；经 R-16 用户明确要求，customerID、cardNO、cardASN、余额、交易次数和扣款解析字段纳入本地业务日志。Access-Token、完整 UID、原始 APDU 和完整网络报文仍不进入业务流水；交易事实仍以 consumption_records.db 为准。
• 后续用途：下一轮代码实施、管理员日志查看、真机验收和现场问题定位。

R-13 消费模块临时服务地址

2026-08-29 更新：该临时地址方案已按用户要求撤销，消费前台、后台补传和人员同步恢复使用基础设置中的全局 API 地址；历史实施证据保留用于追溯。

• 产物：change_records/2026-08-28-consumption-temporary-network-address.md/.html、ConsumptionNetworkProvider 及其单元测试。
• 记录原因：用户要求消费模块的查单、反馈和人员同步接口临时访问 192.168.10.38；必须同时记录作用范围和恢复方式，避免误改全局地址或忘记补传任务的目标服务端。
• 实现结果：消费页订单查询、接口 C 前台反馈和后台补传统一使用 http://192.168.10.38/；全局 NetworkManager 不变。当前消费页未实际发起 syncPersons，未新增额外同步行为。
• 验证证据：定向测试 BUILD SUCCESSFUL in 16s；全量单测及 Debug 构建 BUILD SUCCESSFUL in 46s；86个测试、0 failure、0 error、0 skipped；git diff --check 通过。
• 后续用途：临时环境联调、现场确认请求目标以及恢复正式地址。

R-14 消费流水日志中文化与精简

• 产物：change_records/2026-08-28-consumption-flow-log-readability-simplification.md/.html、ConsumptionFlowEventNames 及消费业务日志调用点调整。
• 记录原因：真机日志显示“餐盘识别成功但未查到订单”的简单流程产生约10条业务事件，且 事件 值仍为英文，不便于现场人员快速定位。
• 实现结果：新日志事件值中文化，历史英文事件码由查看器兼容转换；同一业务内普通事件连续逐行，只有“业务流程结束”后空一行；无订单典型路径精简为“识别餐盘、开始查单、查单结果、移盘、流程结束”5条，异常证据和三阶段交易结果继续保留。
• 验证证据：JDK 8 完整单测及 Debug APK 构建 BUILD SUCCESSFUL in 43s；95个测试、0 failure、0 error、0 skipped；git diff --check 通过；Debug APK 约61 MB。
• 后续用途：真机复核日志条数和可读性，并作为正金额、移卡、反馈失败及后台补传问题的统一排查入口。

R-15 接口 B 无待支付订单提示

• 产物：change_records/2026-08-28-consumption-order-business-message-display.md/.html、接口 B 空数组适配、业务码保留测试和订单失败页文案调整。
• 记录原因：实际响应为 code=1/message=未找到餐盘待支付订单/data=[]，页面却显示“未能获取订单 / 缺少订单数据”，业务语义与服务端结果不一致。
• 实现结果：空数组不再导致订单对象解析失败；消费查单保留业务码；code=1 页面只显示“未找到餐盘对应的待支付订单”，其他技术异常仍保留通用兜底。
• 验证证据：JDK 8 完整单测及 Debug APK 构建 BUILD SUCCESSFUL in 13s；98个测试、0 failure、0 error、0 skipped；git diff --check 通过；Debug APK 约61 MB。
• 后续用途：真机复测餐盘 018004，确认页面文案、日志业务码及 trace_id 一致。

R-16 三阶段协议解析结果日志

• 产物：change_records/2026-08-28-consumption-three-stage-protocol-result-logging.md/.html、ConsumptionStageProtocolResultJson、消费页三阶段日志接入和对应单元测试。
• 记录原因：原消费业务流水只保存第一次读卡、消费、第二次读卡的结果、耗时和金额摘要，无法直接核对协议已经解析出的卡片字段、余额变化、交易次数和 PSAM/TAC 信息。
• 实现结果：三个结果事件都在 明细.协议解析结果 中保存原生 JSON 对象，结构固定为 code/message/data。前后读卡字段与用户确认示例一致；扣款阶段保存请求/完成金额和每个钱包的解析交易明细。原始 APDU 不重复写入消费流水，仍由 ReaderLog 负责。
• 数据边界调整原因：用户明确要求本机日志保留完整协议解析字段，因此完整客户号、卡号、ASN、余额和交易次数由原先的脱敏排除项调整为允许项；Access-Token、完整 UID、原始 APDU 和完整 HTTP 报文仍排除。
• 验证证据：JDK 8 完整单测及 Debug APK 构建 BUILD SUCCESSFUL in 54s；100个测试、0 failure、0 error、0 skipped；git diff --check 通过；当前 Debug APK 64,329,946 字节。
• 后续用途：真机完成一笔正金额订单后，按业务流水号核对三阶段 协议解析结果 与读卡器现场结果；失败路径同步检查 code/message/errorCode。

R-17 零元单读卡核验与携卡反馈

• 产物：产品需求 V0.9.5、代码实施设计 V1.1、接口 C 契约矩阵、change_records/2026-08-28-consumption-zero-amount-card-read-report.md/.html 及对应代码/测试。
• 记录原因：零元单此前获取订单后立即以空卡对象反馈，无法满足服务端需要的读卡身份信息。
• 实现结果：零元单与正金额一样等待一次新卡入场；交易器只执行一次完整读卡，不调用消费接口和第二次物理读卡；接口 C 前后卡对象镜像同一真实快照。读卡失败不反馈成功，移卡后继续等待；反馈失败沿用原请求落库补传。
• 自动化证据：状态机、交易闸门、交易器、接口 C 请求和请求快照 5 组定向测试通过；最终完整复跑 :app:testDebugUnitTest :app:assembleDebug 为 BUILD SUCCESSFUL in 21s，31 个测试类、105 个测试、0 failure、0 error、0 skipped，Debug APK 为 64,336,640 字节。
• 真机边界：仍需用测试卡确认零元路径没有消费 APDU、卡余额/次数不变，并核对服务端收到的前后卡字段。

R-18 三步页面简化与持卡人余额展示

• 产物：产品需求 V0.9.6、代码实施设计 V1.2、方案 B UI 标注 V1.1、docs/2026-08-28-consumption-ui-simplification-design.md/.html、实施计划、独立变更记录及对应 Android 代码/资源/测试。
• 记录原因：订单确认成功后的固定停留，以及前读卡、扣款、后读卡、反馈逐阶段换文案和旧项目图片，使用户需要理解过多内部流程；同时刷卡后缺少持卡人和两类余额信息。
• 实现结果：保留三步与完整业务状态机，新增纯 Java 页面状态映射；查单成功直接进入第三步；第三步只保留放卡/取卡、处理中、完成和必要异常。首次完整读卡后显示本地人员姓名、补贴余额和现金余额，正金额完整成功后更新真实后读卡余额；姓名未同步不阻断交易，新会话和复位时清空个人信息。
• 视觉结果：使用 imagegen 内置模式生成放盘、放卡、取卡三张同色系透明 PNG，统一为 1024×576 且经 Alpha 检查；消费页不再使用旧刷卡、绑盘成功或绑盘失败图片。
• 轻量验证：ConsumptionUiStateMapperTest 与 ConsumptionCardTransactionExecutorTest 定向测试通过；:app:assembleDebug 为 BUILD SUCCESSFUL in 54s；XML 语法和相关文件 git diff --check 通过。按用户要求未执行全量回归、真机自动化或截图对比。
• 回滚证据：变更前源文件快照为 artifacts/rollback/2026-08-28-consumption-ui-before-change.tar.gz，SHA-256 1bcc13616f874ffde492ef57608c5dadd16f72c52073416d42a2cee145b90cfa；不使用 Git reset、checkout、stash 或提交实现回滚。

3. 记录完成情况

4. 记录维护规则

• 每完成一个增量切片立即回填，不在全部开发结束后凭记忆补写。
• 失败的测试和修复原因同样记录，避免只保留成功结果。
• 正式过程文档同时维护同名 Markdown 与 HTML。
• 不把 Access-Token、测试卡敏感数据、服务端凭据或个人信息写入记录。
• 代码实施与验证结束后停止，不执行 Git 写操作。