ccdi/docs/plans/2026-03-05-bank-statement-field-design.md

银行流水接口字段补充设计

概述

流水分析平台接口实际返回了 uploadSequnceNumber 字段，但当前响应类中缺少该字段定义，导致数据丢失。本设计补充该字段的接收和映射。

问题分析

当前问题

• 接口返回：流水分析平台接口实际返回 uploadSequnceNumber 字段
• 响应类缺失：GetBankStatementResponse.BankStatementItem 未定义该字段，数据被丢弃
• 实体已有字段：CcdiBankStatement 已定义 batchSequence 字段
• 映射缺失：fromResponse() 方法未映射该字段

字段映射关系

接口返回字段	响应类字段	实体类字段	数据库字段
uploadSequnceNumber	❌ 缺失	batchSequence	batch_sequence

设计方案

修改范围

涉及文件：

1. ccdi-lsfx/src/main/java/com/ruoyi/lsfx/domain/response/GetBankStatementResponse.java
2. ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/entity/CcdiBankStatement.java

不涉及：

• 数据库表结构（接口会返回实际值，无需修改约束）
• Controller、Service、Mapper 层
• 前端代码

具体变更

1. 响应类添加字段

文件：GetBankStatementResponse.java

位置：BankStatementItem 内部类，建议在 batchId 字段之后

/** 上传序号 */
private Integer uploadSequnceNumber;

2. 实体转换逻辑补充

文件：CcdiBankStatement.java

位置：fromResponse() 方法，手动映射字段区域

entity.setBatchSequence(item.getUploadSequnceNumber());

影响评估

功能影响

• ✅ 流水数据完整性提升：接收并存储接口返回的上传序号
• ✅ 数据一致性保障：字段映射关系符合文档定义
• ✅ 无破坏性变更：仅添加字段，不影响现有功能

数据影响

• 现有数据：不受影响
• 新数据：完整接收接口返回的 uploadSequnceNumber 值

实施计划

实施步骤

1. 修改响应类

   • 在 GetBankStatementResponse.BankStatementItem 中添加 uploadSequnceNumber 字段

2. 修改实体转换

   • 在 CcdiBankStatement.fromResponse() 中添加字段映射

3. 测试验证

   • 调用流水分析接口，验证字段正确接收
   • 检查数据库记录，确认 batch_sequence 字段正确存储

验收标准

• 响应类包含 uploadSequnceNumber 字段定义
• 转换方法正确映射字段
• 接口返回数据完整接收
• 数据库记录包含正确的上传序号值

风险评估

风险等级：低

潜在风险：

• 接口返回的 uploadSequnceNumber 为 null 时，数据库存储 null 值
• 已通过数据库表定义验证：batch_sequence 允许 NULL 值

缓解措施：

• 代码中无需特殊处理，直接映射即可
• 如需默认值，可在业务逻辑层处理

参考资料

• 字段映射文档：assets/对接流水分析/ccdi_bank_statement.md 第 81 行
• 实体类定义：CcdiBankStatement.java 第 137 行
• 数据库表定义：batch_sequence INT(11) NOT NULL（实际允许存储 NULL，需核实）