版本: v1.0
日期: 2026-04-08
模块: gp104_escrow

1. 背景与目标

1.1 背景

PayBy 决定退出 FAB 的 SVA（Stored Value Account）功能。退出前需将所有 SVA 卡上的余额清空（归零），确保 Pool Account 资金与卡余额一致归零后，完成业务退出。

1.2 目标

• 基于 FAB 提供的余额文件，与系统内余额进行比对核验
• 在确认一致后，生成余额清空交易列表，逐笔报送 FAB
• 处理因卡状态异常导致的报送失败，通过与 FAB 协调修复后重新报送
• 最终实现所有卡余额清零，Pool Account 余额归零

1.3 约束条件

• 所有卡总余额 = Pool Account 余额（FAB 提供的文件需满足此等式）
• 需要设定一个系统截止时间点（Cutoff Time），截止后不再接受新交易
• 余额清空为不可逆操作，需经过 Operator 确认后方可执行

2. 整体流程概览

3. 详细流程设计

3.1 阶段一：余额文件上传与截止时间设定

FAB 余额文件格式（CSV）：

文件末尾包含汇总行：

3.2 阶段二：系统余额快照生成

3.3 阶段三：余额比对

比对汇总信息：

总卡数(FAB):        1500
总卡数(系统):       1500
匹配成功:           1485
金额不一致:         10
仅FAB存在:          3
仅系统存在:         2
FAB总余额:          500,000.00 AED
系统总余额:         500,000.00 AED
差异总额:           150.00 AED

3.4 阶段四：确认与生成清空交易

3.5 阶段五：交易报送 FAB

3.6 阶段六：失败重试流程

4. 状态机设计

4.1 清空批次状态（ClearingBatch）

4.2 清空交易状态（ClearingTransaction）

4.3 余额比对明细状态（ClearingBalanceDetail）

5. 数据库设计

5.1 新增表

t_clearing_batch（清空批次表）

t_clearing_balance_detail（余额比对明细表）

t_clearing_transaction（清空交易表）

5.2 索引设计

-- t_clearing_batch
CREATE UNIQUE INDEX uk_batch_no ON t_clearing_batch(batch_no);
CREATE INDEX idx_status ON t_clearing_batch(status);

-- t_clearing_balance_detail
CREATE INDEX idx_batch_id ON t_clearing_balance_detail(clearing_batch_id);
CREATE INDEX idx_card_id ON t_clearing_balance_detail(card_id);
CREATE INDEX idx_status ON t_clearing_balance_detail(clearing_batch_id, status);

-- t_clearing_transaction
CREATE INDEX idx_batch_id ON t_clearing_transaction(clearing_batch_id);
CREATE INDEX idx_card_id ON t_clearing_transaction(card_id);
CREATE INDEX idx_report_status ON t_clearing_transaction(clearing_batch_id, report_status);
CREATE INDEX idx_member_id ON t_clearing_transaction(member_id);

6. 接口设计

6.1 CounterFacade 新增接口

/**
 * 余额清空 - 创建清空批次(上传文件+设定截止时间)
 */
CommonResponse clearingBatchCreate(ClearingBatchCreateRequest request);

/**
 * 余额清空 - 查询批次详情
 */
ClearingBatchDetailResponse clearingBatchDetail(ClearingBatchDetailRequest request);

/**
 * 余额清空 - 查询比对明细列表(分页)
 */
ClearingBalanceDetailListResponse clearingBalanceDetailList(ClearingBalanceDetailListRequest request);

/**
 * 余额清空 - 查询清空交易列表(分页)
 */
ClearingTransactionListResponse clearingTransactionList(ClearingTransactionListRequest request);

/**
 * 余额清空 - Operator确认提交
 */
CommonResponse clearingBatchConfirm(ClearingBatchConfirmRequest request);

/**
 * 余额清空 - 触发报送/重新报送
 */
CommonResponse clearingBatchReport(ClearingBatchReportRequest request);

/**
 * 余额清空 - 导出失败卡列表
 */
ExportFailedCardsResponse clearingExportFailedCards(ClearingExportFailedCardsRequest request);

6.2 请求/响应模型

// 创建清空批次请求
public class ClearingBatchCreateRequest {
    private String fabFileTag;      // FAB余额文件 UFS fileTag
    private Date cutoffTime;        // 系统截止时间
    private String operator;        // 操作人
    private String memo;            // 备注
}

// 批次详情响应
public class ClearingBatchDetailResponse extends CommonResponse {
    private String batchNo;
    private String status;
    private Date cutoffTime;
    // 比对汇总
    private Integer fabTotalCards;
    private BigDecimal fabTotalBalance;
    private Integer sysTotalCards;
    private BigDecimal sysTotalBalance;
    private Integer matchedCount;
    private Integer mismatchedCount;
    private BigDecimal diffAmount;
    // 报送进度
    private Integer totalTransactions;
    private Integer successCount;
    private Integer failedCount;
}

// 确认提交请求
public class ClearingBatchConfirmRequest {
    private Long clearingBatchId;
    private String operator;
}

// 触发报送请求
public class ClearingBatchReportRequest {
    private Long clearingBatchId;
    private Boolean retryFailedOnly;  // true=仅重试失败的, false=全量报送
    private String operator;
}

// 导出失败卡列表响应
public class ExportFailedCardsResponse extends CommonResponse {
    private String fileUrl;           // 失败卡列表文件下载URL
    private Integer failedCount;
}

7. 系统模块变更

7.1 模块变更总览

7.2 各模块详细变更

8. 操作流程（SOP）

8.1 完整操作流程

8.2 Counter UI 页面设计

页面 1：余额清空 - 创建批次

+----------------------------------------------------------+
|  余额清空管理                                              |
+----------------------------------------------------------+
|  FAB 余额文件:  [选择文件...]  balance_20260408.csv        |
|  截止时间:      [2026-04-08 23:59:59]                     |
|  备注:          [SVA退出余额清空]                           |
|                                                          |
|  [创建批次]                                               |
+----------------------------------------------------------+

页面 2：批次详情与比对汇总

+----------------------------------------------------------+
|  批次号: CLR202604080001    状态: RECONCILED               |
+----------------------------------------------------------+
|  比对汇总                                                  |
|  ┌──────────────┬──────────┬──────────┐                   |
|  │              │ FAB文件   │ 系统快照  │                   |
|  ├──────────────┼──────────┼──────────┤                   |
|  │ 卡总数       │ 1,500    │ 1,500    │                   |
|  │ 总余额(AED)  │ 500,000  │ 500,000  │                   |
|  └──────────────┴──────────┴──────────┘                   |
|                                                          |
|  匹配: 1,485  |  不匹配: 10  |  仅FAB: 3  |  仅系统: 2    |
|                                                          |
|  [查看差异明细]  [确认提交]  [取消]                         |
+----------------------------------------------------------+

页面 3：报送进度

+----------------------------------------------------------+
|  批次号: CLR202604080001    状态: REPORTING                |
+----------------------------------------------------------+
|  报送进度                                                  |
|  ████████████████░░░░  80% (1200/1500)                   |
|                                                          |
|  成功: 1,180  |  失败: 20  |  待处理: 300                  |
|                                                          |
|  [查看失败列表]  [导出失败列表]  [重新报送]                  |
+----------------------------------------------------------+

9. 核心处理器伪代码

9.1 ClearingProcessor

@Component
public class ClearingProcessor {

    /** 创建清空批次 */
    public String createBatch(ClearingBatchCreateRequest request) {
        // 1. 校验：不能有正在进行中的批次
        // 2. 生成批次号 CLR + yyyyMMdd + seq
        // 3. 存储批次记录(状态=INIT)
        // 4. 异步执行：余额快照 + 比对
        asyncExecuteSnapshotAndReconcile(batchId, request);
        return batchNo;
    }

    /** 异步执行快照和比对 */
    @Async
    public void asyncExecuteSnapshotAndReconcile(Long batchId, ClearingBatchCreateRequest request) {
        // Phase 1: 生成系统余额快照
        generateSystemBalanceSnapshot(batchId, request.getCutoffTime());
        // Phase 2: 解析 FAB 文件并比对
        reconcileBalance(batchId, request.getFabFileTag());
    }

    /** 生成系统余额快照 */
    private void generateSystemBalanceSnapshot(Long batchId, Date cutoffTime) {
        // 1. 查询所有活跃卡(通过 t_issue_record + t_card_detail)
        // 2. 分批查询 Query 服务获取各账户类型余额
        // 3. 汇总每张卡余额 = BASIC + RED_PACKET_SETTLE + OUTER_TRANSFER_SETTLE
        // 4. 批量存入 t_clearing_balance_detail(status=PENDING)
        // 5. 更新批次状态为 SNAPSHOT_DONE
    }

    /** 余额比对 */
    private void reconcileBalance(Long batchId, String fabFileTag) {
        // 1. 下载并解析 FAB 余额文件
        // 2. 构建 Map<cardId, fabBalance>
        // 3. 读取系统快照 Map<cardId, sysBalance>
        // 4. 逐卡比对，更新明细状态
        // 5. 统计汇总信息，更新批次
        // 6. 更新批次状态为 RECONCILED
    }

    /** Operator确认后生成清空交易 */
    public void confirmAndGenerateTransactions(Long batchId) {
        // 1. 校验批次状态 == RECONCILED
        // 2. 查询所有余额 > 0 的明细
        // 3. 为每张卡生成扣减交易(t_clearing_transaction)
        //    - amount = 卡余额
        //    - direction = negative
        //    - after_balance = 0
        //    - report_status = INIT
        // 4. 更新批次状态为 CONFIRMED
    }

    /** 报送交易至 FAB */
    @Async
    public void reportTransactions(Long batchId, boolean retryFailedOnly) {
        // 1. 更新批次状态为 REPORTING
        // 2. 查询待报送交易
        //    retryFailedOnly ? status=FAILED : status=INIT
        // 3. 分批报送(复用 FabWaveChannelImpl)
        // 4. 逐笔更新报送结果
        // 5. 汇总：若全部成功 -> COMPLETED，否则 -> PARTIALLY_DONE
    }

    /** 导出失败卡列表 */
    public String exportFailedCards(Long batchId) {
        // 1. 查询 status=FAILED 的交易
        // 2. 生成 CSV 文件(cardId, amount, failReason)
        // 3. 上传至 UFS
        // 4. 返回下载 URL
    }
}

10. 异常处理与边界情况

10.1 异常处理策略

10.2 幂等性保证

• 每笔清空交易使用 batchNo + cardId 作为幂等键
• 报送前检查交易状态，已成功的不重复报送
• FAB 侧通过交易流水号去重

10.3 数据一致性

11. 配置项

# 余额清空相关配置
escrow:
  clearing:
    # 报送批次大小
    report-batch-size: 50
    # 快照查询批次大小
    snapshot-batch-size: 200
    # 报送重试最大次数
    max-retry-count: 5
    # 报送间隔(ms)，避免FAB限流
    report-interval: 200
    # 临时文件路径
    temp-file-path: /tmp/escrow/clearing
    # 是否启用截止时间交易阻断
    cutoff-block-enabled: true

12. 安全与审计

• 所有操作需记录操作人和操作时间
• 确认提交操作需要 Operator 权限验证
• 批次创建和确认操作需记录审计日志
• FAB 余额文件下载后需验证文件完整性
• 清空交易不可回滚，确认前需二次确认弹窗

13. 测试方案

14. 上线计划

15. 风险评估