消费记录双通道上传管理实施记录

日期：2026-09-12
项目：ZhctTrayBindingMachine

本次落地结果

• 消费记录数据库升级到 V4，业务服务器与一卡通服务器分别保存状态、尝试次数、失败信息、自动重试资格、结果不确定标志、租约、目标指纹和版本。
• 一笔业务订单仍保存一条主记录；补贴和现金分开扣款时，每个真实钱包扣款生成一条一卡通子任务。
• 每钱包严格执行 DEBIT_INTENT -> 硬件扣款 -> DEBIT_CONFIRMED。确认结果与一卡通任务在同一个 SQLite 事务中保存，第一钱包成功、第二钱包失败时保留第一笔。
• 后台轮询与前台手动上传共用数据库租约。晚到响应必须匹配租约，不能覆盖新状态。
• 业务通道和一卡通通道独立运行；网络失败使用有上限和抖动的指数退避。一卡通请求发出后结果未知时停止自动重试。
• 上传目标配置使用不含秘密的 SHA-256 指纹冻结，配置变化后旧任务不发送到新服务器。
• 新增两列网格待上传页面，只显示未完成订单，支持单笔/全部上传、上拉加载、成功自动移除、红色失败、上传中状态和页数。
• 待上传订单页继承并初始化 BaseTitleActivity 的统一 NetWorkStatusView，复用消费终端背景、设备编号、网络、时间和返回入口；返回动作仍关闭当前页并回到消费页。
• 消费页的“待上传”入口调整到“一卡通服务状态”正下方，并直接对齐其右边缘，形成纵向状态操作区。
• 修复空列表仍可点击“全部上传”并误报“已开始上传”：空态禁用并弱化按钮，点击入口及数据库任务范围均再次校验待上传数量，空范围只提示“暂无待上传订单”且不触发上传调度。
• 全部上传使用业务主表 rowid 和一卡通子表 id 双高水位，新记录不进入本次范围。
• 消费主页提供带数量的安全入口；仅等待放盘且无当前订单、无读卡任务时允许进入。高级设置页也保留入口。
• 增加 90 天/最多 10000 条完整终态记录清理、20 MiB 扣款前空间保护和消费数据库备份排除。
• 零元订单只读卡，不生成一卡通扣款子任务；业务反馈仍可靠入队。

数据迁移与兼容

• 新安装直接创建 V4 主表和带外键级联的一卡通子表；V1/V2 逐级补齐字段。
• V3 升 V4 时复制子表、核对行数、替换旧表并重建索引。
• 历史未完成任务标记为 LEGACY_UNVERIFIED 且禁止自动重试。
• V4 不能通过安装旧 V3 APK 或删除数据库回滚；必须使用保留 V4 schema 的前向修复包或受控转换。

安全开关

一卡通 UploadBusinessRec 的现场成功码和幂等规则仍需确认。新增“一卡通消费流水上传”开关且默认关闭；本地记录和任务照常生成，现场门槛确认后由管理员开启。

已执行验证

• bash gradlew -q :app:testDebugUnitTest：通过。
• bash gradlew -q :app:assembleDebug：通过。
• bash gradlew -q :app:compileDebugAndroidTestJavaWithJavac：通过。
• JAVA_HOME=$(/usr/libexec/java_home -v 1.8) bash gradlew :app:compileDebugJavaWithJavac --no-daemon：统一标题栏调整后编译通过。
• 新增 PendingUploadActionPolicyTest，覆盖数据库无待上传记录、页面未展示记录和存在可上传记录三类“全部上传”可用性。
• bash gradlew -q :app:lintDebug：本次新增代码相关错误已清零；仍因既有 F700 USB 恢复模块的两项 API 26 兼容错误而失败，本次未越界修改该硬件模块。
• JVM 测试覆盖状态/分类、退避、指纹、脱敏、渐进扣款日志、回调顺序和入口规则。
• V3→V4 SQLite 仪器测试已编译；为避免覆盖已连接终端上的现有安装，本次未自动安装执行。

尚需现场完成

1. 在测试终端执行 V1/V2/V3→V4 实际迁移和行数核对。
2. 验证一卡通成功、明确失败、超时但服务端已接收三类响应，并确认幂等/查询能力。
3. 开启开关后验收单钱包、双钱包、部分成功、断网恢复和前后台并发。
4. 验证保留 V4 schema 的前向修复回滚包。

Git 边界

本次仅编辑、测试和构建，没有执行暂存、提交、推送、拉取、切分支、重置或清理操作。