2026-09-12 消费记录双服务器上传与待上传订单管理设计

版本：v1.1（完整性复核修订版）
目标终端：Android 横屏消费终端
事实基线：2026-09-12 当前工作区；源码存在未提交的一卡通上传初步实现，本设计不覆盖其改动，而是在其上补齐可靠性和管理能力。

1. 目标与范围

在不改变补贴优先、现金补足和业务接口 C 既有上报口径的前提下，实现消费记录的本地可靠保存、两个服务器的独立上传、自动重传和终端手动补传。

本方案必须保证：

• 消费订单、每笔真实钱包扣款和上传请求先可靠落库，再发起网络请求。
• 一卡通服务器与业务服务器的任务、状态、重试和错误互相独立，没有先后依赖。
• 一笔订单同时扣补贴和现金时，主表仍保存 1 条订单；一卡通保存并上传 2 条真实流水；业务服务器仍上传 1 条订单。
• 自动轮询与手动上传共用数据库原子认领和租约机制，不重复发送，不记录“成果属于手动还是后台”。
• 页面只管理未完成上传的订单；两个通道均完成或无需上传后，订单自动移除。
• 页面适配横屏触控终端，采用两列网格和上拉加载，不采用电脑端表格、页码按钮、复选框或“全选”。

2. 非目标

• 不提供已完成历史订单查询。
• 不改变扣款顺序、读卡校验、扣款金额或接口 C 的业务口径。
• 不把两个服务器的状态合并为一个字段。
• 不因进入管理页面而暂停后台上传。
• 不记录或展示“手动成功几条、后台成功几条”。
• 不自动补传数据库升级前的历史一卡通流水。
• 不在本功能中提供订单、卡流水或服务器配置编辑能力。

3. 当前实现基线

当前数据库 consumption_records.db 已被并发中的初步实现升级为 V3：

• 主表 consumption_records：一行对应一笔业务订单，三个阶段结果以 SQLite TEXT 保存 JSON 字符串。
• before_result_json：扣款前读卡结果。
• debit_result_json：扣款结果；其中 transactions 可保存补贴、现金两笔流水。
• after_result_json：扣款后读卡结果。
• 主表已有业务服务器的请求快照、状态、尝试次数、错误和下次重试时间。
• V3 初步增加 onecard_upload_records，按钱包保存一卡通请求 JSON 和简单的 PENDING/UPLOADED 状态。
• 当前业务与一卡通上传在同一个 Worker 中顺序执行，两个 Runner 仅靠实例内 AtomicBoolean 防重；数据库没有跨组件原子认领。
• 当前一卡通任务只在整单成功后创建；第一钱包成功、第二钱包失败时，第一笔已扣流水仍可能没有独立任务。
• 当前上传时读取最新服务器配置，没有校验任务创建时的目标服务器。
• 当前没有待上传订单管理页面。

因此当前 V3 是可复用的初步基线，但尚不能满足断电保护、并发防重、结果不确定、配置切换和手动管理要求。本设计目标数据库版本为 V4。

4. AI 可执行 Use Case

4.1 UC-CONSUMPTION-UPLOAD-001：可靠保存并独立上传消费记录

• 状态：实施就绪；本地实现 DoR：READY；一卡通自动重传的生产启用受第 17 节现场契约门槛约束。
• 参与者：消费终端、读卡器、本地 SQLite、一卡通服务器、业务服务器。
• 触发：终端取得订单并开始一次读卡/扣款流程。
• 成功后置：真实扣款流水已本地保存并分别上传一卡通；符合接口 C 口径的订单结果已上传业务服务器。
• 失败后置：任何已发生的真实扣款均可从本地恢复；失败或结果不确定任务不会被错误覆盖或盲目重复发送。

主流程：

主要异常与恢复：

4.2 UC-CONSUMPTION-UPLOAD-002：查看并补传未完成订单

• 状态：实施就绪；DoR：READY。
• 参与者：终端操作人员、待上传订单页面、上传协调器。
• 触发：终端处于安全待机状态，操作人员进入“待上传订单”。
• 成功后置：目标订单的可处理任务完成；完成订单从列表移除。
• 失败后置：失败、结果不确定或配置不匹配的订单留在页面并显示可理解原因。

主流程：

本版本明确不提供批量勾选、“全选”或“上传当前已加载”。“全部上传”表示处理点击瞬间数据库中已经存在的全部可处理任务；点击后新产生的任务不属于本次范围。

5. 核心模型

5.1 一张订单主表加一张一卡通流水子表

consumption_records（一笔业务订单）
├── 订单交易三阶段 JSON
├── 业务服务器上传任务：0 或 1 个
└── onecard_upload_records（真实钱包扣款）
    ├── 补贴扣款：0 或 1 条
    └── 现金扣款：0 或 1 条

不能只在主表增加一个一卡通状态字段。两笔钱包流水可能一笔成功、一笔失败，必须在子表逐笔保存和重传；主表页面状态由子表聚合得出。

5.2 两个通道互不阻塞

• 业务上传异常不得跳过一卡通扫描。
• 一卡通上传异常不得改变业务任务状态。
• Worker 可以分别存在，也可以由一个调度入口触发，但必须在独立 try/catch 边界内运行。
• 手动与自动只是触发方式，不进入持久化归属模型。

6. V4 数据库设计

6.1 主表 consumption_records

保留 V3 所有订单、交易和业务上传字段，新增：

report_failure_category TEXT,
report_auto_retry_allowed INTEGER NOT NULL DEFAULT 1,
report_result_uncertain INTEGER NOT NULL DEFAULT 0,
report_lease_id TEXT,
report_destination_key TEXT NOT NULL DEFAULT '',
report_payload_schema_version INTEGER NOT NULL DEFAULT 1,
report_enqueued_at INTEGER NOT NULL DEFAULT 0,
report_upload_started_at INTEGER NOT NULL DEFAULT 0,
report_uploaded_at INTEGER NOT NULL DEFAULT 0

业务字段规则：

• report_status 保存订单级业务上传状态。
• report_lease_id 是一次认领的随机令牌，不是手动/后台归属。
• report_destination_key 是任务创建时对业务 API 基址、设备/租户身份和配置版本生成的稳定指纹；不保存口令、Token 或密钥。
• report_payload_schema_version 用于未来兼容旧请求快照。
• report_attempts 在认领成功、真正准备发送时加 1，不能等响应后再加。

6.2 子表 onecard_upload_records

沿用当前 V3 物理表名，V4 通过重建临时表后复制数据补齐约束：

CREATE TABLE onecard_upload_records_v4 (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    order_no TEXT NOT NULL,
    flow_id TEXT NOT NULL,
    segment_index INTEGER NOT NULL,
    wallet_type TEXT NOT NULL,
    record_json TEXT NOT NULL,
    payload_schema_version INTEGER NOT NULL DEFAULT 1,
    destination_key TEXT NOT NULL DEFAULT '',
    upload_status TEXT NOT NULL,
    upload_attempts INTEGER NOT NULL DEFAULT 0,
    failure_category TEXT,
    auto_retry_allowed INTEGER NOT NULL DEFAULT 1,
    result_uncertain INTEGER NOT NULL DEFAULT 0,
    upload_lease_id TEXT,
    last_upload_error TEXT,
    next_retry_at INTEGER NOT NULL DEFAULT 0,
    upload_enqueued_at INTEGER NOT NULL DEFAULT 0,
    upload_started_at INTEGER NOT NULL DEFAULT 0,
    uploaded_at INTEGER NOT NULL DEFAULT 0,
    psam_id TEXT,
    psam_transaction_no INTEGER,
    tac INTEGER,
    psam_confirmed INTEGER NOT NULL DEFAULT 1,
    created_at INTEGER NOT NULL,
    updated_at INTEGER NOT NULL,
    FOREIGN KEY(order_no) REFERENCES consumption_records(order_no) ON DELETE CASCADE,
    UNIQUE(order_no, segment_index)
);

不直接建立 UNIQUE(psam_id, psam_transaction_no)，因为 PSAM 流水号是否复位或回绕尚需现场确认。应用层使用以下组合做审计和软去重：

destination_key + terminal_id + psam_id + psam_transaction_no + card_no + wallet_type

待现场确认流水号生命周期后，再决定是否建立不会误伤合法交易的数据库唯一索引。

建议索引：

CREATE INDEX idx_consumption_report_pending
ON consumption_records(report_status, report_auto_retry_allowed,
                       next_retry_at, created_at);

CREATE INDEX idx_onecard_upload_pending
ON onecard_upload_records(upload_status, auto_retry_allowed,
                          next_retry_at, created_at);

CREATE INDEX idx_onecard_upload_order
ON onecard_upload_records(order_no, segment_index);

数据库连接必须启用外键；迁移测试必须实际执行 PRAGMA foreign_keys=ON 并验证级联和约束。

6.3 状态和辅助标记

两个通道共用五个主状态：

FAILED 必须结合以下字段解释：

• failure_category：NETWORK、SERVER、CONFIG、DATA、RESULT_UNKNOWN、LOCAL。
• auto_retry_allowed=1：允许自动退避重试。
• result_uncertain=1：服务端是否已入账不明确，自动和手动都不得直接重发。
• 配置不匹配和数据错误默认不可重试；当前配置重新与快照匹配后，协调器可把配置不匹配任务恢复为 PENDING。

状态字符串、失败类别、页大小、租约时长、错误最大长度和退避参数必须集中在枚举/命名常量中。

7. 逐阶段、逐钱包持久化

原“交易结束后一次性保存”的设计不足以覆盖断电窗口，改为以下强制顺序：

1. 取得订单后立即插入主表，状态 ORDER_ACQUIRED。
2. 扣款前读卡成功后立即写 before_result_json；失败则写本地失败终态。
3. 首次读卡后先校验并冻结生成一卡通任务必需的卡信息、终端号、AccCode 和目标服务器指纹；无法形成可靠任务上下文时不得开始扣款。
4. 每个钱包实际调用硬件扣款前，先把该段计划以 DEBIT_INTENT 写入 debit_result_json 并提交事务。
5. 每个钱包取得包含金额、余额、计数器、PSAM 流水号和 TAC 的 ConsumptionResult 后，在同一事务中：

• 把该段从 DEBIT_INTENT 更新为 DEBIT_CONFIRMED；
• 更新 debit_result_json.transactions；
• 插入该段的一卡通上传任务。

1. 如果确认结果写库失败，扣款前留下的 DEBIT_INTENT 必须保留；立即停止后续钱包，将订单标记为结果待核查，禁止再次扣该段。由于硬件扣款和 SQLite 无法组成同一物理事务，这个意图记录是断电恢复的最小安全证据。
2. 第一钱包成功后，即使第二钱包失败、线程异常或进程退出，第一笔已扣流水和上传任务仍然存在。
3. 后读卡结束后更新 after_result_json 和整单交易分类。
4. 只有符合接口 C 现有上报口径的完整成功订单或零元读卡成功订单，才创建业务上传任务。
5. 所有本地事务提交成功后才允许触发网络调度。

debit_result_json 需要兼容旧结构，并为每段增加稳定状态：

{
  "schema_version": 2,
  "requested_amount": 500,
  "segments": [
    {
      "sequence": 0,
      "wallet": "SUBSIDY",
      "planned_amount": 300,
      "state": "DEBIT_CONFIRMED",
      "intent_at": 1789180000000,
      "confirmed_at": 1789180001000,
      "transaction": {}
    },
    {
      "sequence": 1,
      "wallet": "MAIN",
      "planned_amount": 200,
      "state": "DEBIT_INTENT",
      "intent_at": 1789180002000
    }
  ]
}

当 psam_confirmed=false 但卡扣款返回已包含有效金额、计数器和 TAC 时，不得丢弃该真实流水或再次扣卡；仍创建并上传一卡通任务，并保存 psam_confirmed=0 供日志和现场核查。该字段表示本地 PSAM 确认步骤异常，不改变已经发生的卡扣款事实。

8. 各订单类型的保存与上传口径

9. 上传协调、租约与重试

9.1 唯一业务入口

ConsumptionUploadCoordinator 是自动和手动上传的唯一业务入口。业务和一卡通可各有 Runner/Gateway，但都必须经过协调器的认领、结果提交和状态通知。

认领操作在单条 SQL 或单个 SQLite 事务中完成：

UPDATE onecard_upload_records
SET upload_status = 'UPLOADING',
    upload_lease_id = :newLeaseId,
    upload_started_at = :now,
    upload_attempts = upload_attempts + 1,
    updated_at = :now
WHERE id = :id
  AND upload_status IN ('PENDING', 'FAILED')
  AND auto_retry_allowed = 1
  AND result_uncertain = 0
  AND next_retry_at <= :eligibleAt;

手动重试可以绕过普通退避时间，但不能绕过 UPLOADING、结果不确定、数据错误或配置不匹配保护。

成功、失败和失效回收都必须携带当前 upload_lease_id：

UPDATE onecard_upload_records
SET upload_status = :newStatus, ...
WHERE id = :id
  AND upload_status = 'UPLOADING'
  AND upload_lease_id = :leaseId;

受影响行数为 0 表示租约已变化，旧执行者的晚响应只记录日志，不能覆盖新状态。

9.2 失败分类和退避

• NETWORK、可恢复 SERVER：指数退避、上限和抖动均使用命名常量。
• CONFIG：阻止发送；配置恢复为任务快照后可重新激活。
• DATA：不自动重试，页面提示联系维护人员。
• RESULT_UNKNOWN：result_uncertain=1，自动和手动都不得盲目重发。
• LOCAL：数据库或序列化错误，记录并告警，不把任务误标成功。
• 错误摘要去除换行和敏感字段并截断到固定长度；完整卡片原始数据不得写日志。

9.3 结果不确定和幂等

• 业务服务器以 order_no 作为幂等业务键，并保持接口 C 现有判定。
• 一卡通优先以 SAMCardNO + SAMTradeNO 及终端/目标服务器身份实现服务端幂等或查询确认。
• 在现场未确认一卡通幂等或查询能力前，超时、连接中断等“可能已写入”结果一律进入结果不确定保护，不自动重发。
• 租约超时也遵守同一规则：业务通道已确认按订单号幂等时可换租约重试；一卡通未确认幂等前转为结果不确定，不能仅因 UPLOADING 超时就重新发送。
• 只有 HTTP/SOAP 成功、无 Fault 且 UploadBusinessRecResult 符合现场确认的成功契约，才能写 UPLOADED。

9.4 调度边界

• 应用启动、网络恢复、任务入队后触发一次即时唯一 Work。
• 周期任务继续作为兜底。
• 业务与一卡通扫描独立捕获异常，任何一个失败都不跳过另一个。
• 页面打开期间后台上传照常执行。
• Activity 只触发和观察任务，不持有网络生命周期；页面退出或进程重建后 WorkManager 继续执行。

10. 目标服务器配置快照

创建任务时必须同时保存请求快照和目标身份指纹：

上传前重新计算当前指纹：

• 一致：允许使用当前客户端发送已保存请求快照。
• 不一致：标记 CONFIG，不把旧交易发送到新服务器。
• 配置恢复一致：协调器清除配置错误并重新进入 PENDING。

指纹只保存非秘密配置的规范化摘要；不得把 Token、密码、证书私钥写入数据库或日志。

11. 待上传订单页面

11.1 入口与安全状态

入口位于消费主页顶部，展示待处理订单数量角标。只有同时满足以下条件才允许进入：

• 流程状态为 WAITING_TRAY。
• 没有锁定的当前订单。
• 没有读卡、扣款、后读卡或本地持久化任务在途。

WAITING_CARD 已经绑定当前订单，不属于安全入口状态。入口不可用时显示“当前交易处理中，请完成后再查看”。进入页面停止消费页自身的读卡监听，返回后按生命周期恢复；后台上传不停止。

11.2 展示范围

满足任一条件的订单才展示：

业务状态属于 PENDING / UPLOADING / FAILED
或
存在一卡通子任务属于 PENDING / UPLOADING / FAILED

两端均为 UPLOADED 或 NOT_REQUIRED 时不展示。页面标题数量按“订单数”统计，不按一卡通流水数统计。

11.3 网格与状态

• 横屏两列卡片，首批默认 4 条，上拉继续加载。
• 卡片展示订单号、时间、金额、钱包组合、一卡通状态、业务状态、失败原因和单笔“上传未完成”。
• 不显示查询按钮、复选框、批量选择、“全选”、“上传当前已加载”或页码按钮。
• 底部保留一个明确的“全部上传”按钮。
• 状态必须同时使用颜色、图标和文字，不能只靠颜色。

一卡通聚合优先级固定为：

结果不确定 > 上传失败 > 上传中 > 待上传 > 全部已上传 > 无需上传

例如两笔一卡通流水一笔成功、一笔失败，显示红色“上传失败 1/2”，不能仅显示黄色“部分完成”。

11.4 上拉加载和动态刷新

页面显示：

当前第 1 / 2 页 · 已加载 4 / 8 条 · 上拉加载下一页

全部加载后显示“已加载全部”。排序为：结果不确定、失败、上传中、待上传，再按最早创建时间和订单号稳定排序。

后台完成会动态移除数据，因此不能使用固定 OFFSET 追加。页面维护 loadedPageCount，每次刷新重新查询前 loadedPageCount × PAGE_SIZE 条，并重新计算待处理总数、总页数和当前已加载页数，防止漏单或重复。

11.5 单笔与全部上传

• 单笔“上传未完成”：只处理该订单当前可认领的业务任务和一卡通子任务。
• “全部上传”：点击时在数据库取得高水位边界，例如业务主表最大 rowid、一卡通最大 id 和创建时间；Worker 只处理边界内任务。
• 不把全部订单 ID 列表塞入 WorkManager Data，也不在 Activity 内循环发送。
• 点击后新产生的订单不属于本次全部上传，交给后台轮询或下一次手动操作。
• 全部上传期间禁用重复触发和上拉加载；卡片可更新状态但不补入新卡片。操作结束后移除完成项、保留异常项并按原容量刷新。

11.6 结果反馈

• 边界内可处理任务全部明确完成时，只提示“上传成功”。
• 不显示“选择几单、成功几单、失败几单”等统计。
• 失败订单保留红色卡片并显示最近错误。
• 结果不确定显示深红/警示状态“结果待确认，禁止重复上传”。
• 配置不匹配显示“服务器配置已变化，暂不可上传”。
• 仍有 UPLOADING 时继续显示上传中，不提前提示成功。

最终页面参考：prototypes/2026-09-12-consumption-order-upload/pending-orders-grid-v6.html。

12. 页面刷新与并发生命周期

新增 ConsumptionUploadStatusChangedEvent，只表达“数据库状态已变化”。页面收到事件后重新查询，不直接渲染事件携带的旧对象。

刷新时机：

• onResume()。
• 数据库状态事务提交后。
• 单笔或全部上传操作结束后。
• 网络恢复后。

后台刚好上传成功时：数据库先提交 UPLOADED，再发事件；页面查询后自然移除卡片。不存在“这笔算手动还是后台”的认领统计。

13. 数据留存、磁盘与安全

• 配置保留天数和最大成功订单数；只清理两个通道均 UPLOADED/NOT_REQUIRED 的旧记录。
• PENDING、UPLOADING、FAILED、结果不确定、配置不匹配和交易异常记录永不被普通清理任务删除。
• 删除主表前必须确认没有未完成的一卡通子任务；由外键级联清理已完成子任务。
• 扣款前检查数据库可写和剩余空间；低于命名阈值时停止新扣款并显示维护提示。
• 当前 Manifest 的 android:allowBackup="true" 不得把消费数据库带入云备份或设备迁移；V4 增加备份排除规则，至少排除 consumption_records.db 及其 WAL/SHM。
• 页面和日志对卡号、人员标识做脱敏；请求快照不包含认证秘密。

14. 迁移、兼容与回滚

升级链必须逐级、事务化执行：

V1 -> V2 -> V3 -> V4

V4 步骤：

1. 为主表增加业务租约、失败分类、配置指纹、结果不确定和时间字段。
2. 创建 onecard_upload_records_v4。
3. 复制 V3 子表数据；旧 PENDING/UPLOADED 状态保持，旧任务的指纹为空时标记为需配置确认，不直接发送。
4. 删除旧子表并将 V4 临时表改名为 onecard_upload_records。
5. 重建索引并执行 foreign_key_check、行数和状态数量校验。
6. 已完成业务记录可用 updated_at 回填 report_uploaded_at。
7. 不从历史 debit_result_json 自动生成一卡通任务，避免历史重复入账。

SQLite 结构升级不可自动降级，旧 V3 APK 不能被假定能够打开 V4 数据库。发布回滚必须使用“保留 V4 schema 的前向修复 APK”，或先导出并验证数据后执行受控降级；不得直接安装旧 APK 或通过删除数据库回滚。

15. 模块职责建议

consumption/upload/
├── UploadStatus.java                         状态枚举
├── UploadFailureCategory.java                失败分类
├── UploadLease.java                          租约令牌和值对象
├── UploadDestinationFingerprint.java         配置规范化和摘要
├── ConsumptionUploadCoordinator.java         手动/自动统一认领和结果提交
├── ConsumptionUploadScope.java               单笔和高水位全部范围
├── ConsumptionUploadStatusChangedEvent.java  数据变化通知
└── UploadRetryPolicy.java                     退避、抖动和重试资格

consumption/report/
├── ConsumptionRecordRepository.java
├── OnecardUploadRepository.java
├── SQLiteConsumptionRecordRepository.java
├── ConsumptionReportSyncRunner.java
└── OnecardUploadSyncRunner.java

onecard/reader/
├── CardReader.java
├── WalletDebitObserver.java                   每钱包意图/确认回调边界
├── ConsumptionCardTransactionExecutor.java
└── NewcapecUsbCardReader.java

main/
└── PendingConsumptionUploadActivity.java

consumption/upload/ui/
├── PendingConsumptionOrderAdapter.java
├── PendingConsumptionOrderViewData.java
└── PendingConsumptionOrderMapper.java

workmanager/
├── ConsumptionReportSyncWorker.java
└── ManualConsumptionUploadWorker.java

新增或职责变化的类必须写职责/边界注释；逐钱包持久化、租约晚响应、高水位快照和动态分页要写“为什么”的注释。文案、颜色、尺寸和阈值进入资源或命名常量，不散落硬编码。

16. 验收与测试矩阵

自动化层级：

• JVM 单元测试：状态聚合、失败分类、退避、配置指纹、JSON 兼容、高水位范围。
• SQLite 仪器测试：V1/V2/V3 到 V4 迁移、外键、唯一约束、原子认领、租约晚响应、分页和清理。
• Runner 测试：一个通道异常不阻塞另一个、结果不确定不重试、手动仅绕过普通退避。
• UI/仪器测试：入口安全状态、空态、加载、失败、上传中、结果不确定、上拉和动态移除。
• 契约测试：业务接口 C 幂等；一卡通 SOAP Fault、成功值、失败值和超时样本。
• 构建检查：目标 JDK 8 下单元测试、Debug 资源编译、Debug APK 和 git diff --check。

17. 发布前门槛

以下事项不阻塞本地代码和测试实施，但阻塞现场启用一卡通自动重传：

1. 用真实/测试环境样本确认 UploadBusinessRecResult 的成功值规则，不能仅凭“rtn > 100”推断。
2. 确认一卡通是否按 SAMCardNO + SAMTradeNO 幂等，或提供交易查询确认接口。
3. 验证 PSAM 流水号复位/回绕规则后，再决定是否增加数据库硬唯一索引。
4. 完成断网、服务端已写入但客户端超时、断电和重启恢复测试。
5. 完成目标终端触控、两列布局、上拉加载和状态可读性验收。

门槛未完成时，一卡通自动/手动重传入口必须由集中配置开关关闭；本地流水与任务仍正常保存，页面明确显示“上传能力待现场确认”，不能静默丢单或按暂定成功码投入生产。

18. 最终确认的页面操作

本版本页面只保留：

• 单笔订单：上传未完成。
• 全部待处理订单：全部上传。

明确移除：

• 批量勾选。
• 全选。
• 上传当前已加载。
• 成功/失败数量统计弹窗。

最终交互以本设计为准；早期原型中仍出现上述已移除控件的部分不再作为实现依据。