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

银行流水接口字段补充实施计划

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: 补充 uploadSequnceNumber 字段的接收和映射，确保流水分析接口返回的上传序号正确存储到数据库。

Architecture: 在响应类中添加字段定义接收接口返回值，在实体转换方法中映射到 batchSequence 字段，通过 MyBatis Plus 自动持久化到数据库的 batch_sequence 列。

Tech Stack: Java 21, Lombok, Spring Boot 3.5.8, MyBatis Plus

---

Task 1: 响应类添加字段

Files:

• Modify: ccdi-lsfx/src/main/java/com/ruoyi/lsfx/domain/response/GetBankStatementResponse.java:132

Step 1: 在 BankStatementItem 内部类中添加字段

在 batchId 字段（第 132 行）之后添加：

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

完整上下文：

/** 上传logId */
private Integer batchId;

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

/** 项目id */
private Integer groupId;

Step 2: 验证 Lombok 注解生效

确认 @Data 注解在 BankStatementItem 类上，Lombok 会自动生成 getter/setter：

@Data
public static class BankStatementItem {
    // ... 其他字段
    private Integer batchId;
    private Integer uploadSequnceNumber;  // 新增字段
    // ... 其他字段
}

---

Task 2: 实体转换方法添加映射

Files:

• Modify: ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/entity/CcdiBankStatement.java:201

Step 1: 在 fromResponse() 方法中添加字段映射

在第 201 行（entity.setCustomerAccountName(item.getCustomerName()); 之后）添加：

entity.setBatchSequence(item.getUploadSequnceNumber());

完整上下文：

// 4. 手动映射字段名不一致的情况
entity.setLeAccountNo(item.getAccountMaskNo());
entity.setCustomerAccountNo(item.getCustomerAccountMaskNo());
entity.setLeAccountName(item.getLeName());
entity.setAmountDr(item.getDrAmount());
entity.setAmountCr(item.getCrAmount());
entity.setAmountBalance(item.getBalanceAmount());
entity.setTrxFlag(item.getTransFlag());
entity.setTrxType(item.getTransTypeId());
entity.setCustomerLeId(item.getCustomerId());
entity.setCustomerAccountName(item.getCustomerName());
entity.setBatchSequence(item.getUploadSequnceNumber());  // 新增映射

// 5. 特殊字段处理
entity.setMetaJson(null);  // 根据文档要求强制设为 null

Step 2: 验证映射逻辑

确认：

• 源字段：item.getUploadSequnceNumber() 返回 Integer
• 目标字段：entity.setBatchSequence() 接受 Integer
• 类型匹配，无需类型转换

---

Task 3: 编译验证

Files:

• 无文件修改

Step 1: 编译项目

在项目根目录执行：

mvn clean compile

预期输出：

[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  X.XXX s
[INFO] Finished at: 2026-03-05T...
[INFO] ------------------------------------------------------------------------

Step 2: 检查编译错误（如果有）

如果出现编译错误，检查：

• 字段名拼写是否正确：uploadSequnceNumber（注意：Sequence 不是 Sequence）
• Lombok 注解处理器是否正确配置
• 导入语句是否需要补充（通常 Lombok 不需要额外导入）

---

Task 4: 代码审查

Files:

• 无文件修改

Step 1: 检查字段命名一致性

对比文档 assets/对接流水分析/ccdi_bank_statement.md:81：

| 28 | batch_sequence | uploadSequnceNumber |

确认：

• 响应类字段名：uploadSequnceNumber（与文档一致）
• 实体类字段名：batchSequence（与数据库列名 batch_sequence 对应）

Step 2: 检查空值处理

确认 Integer 类型允许 null 值：

• 接口返回 null 时，item.getUploadSequnceNumber() 返回 null
• entity.setBatchSequence(null) 设置 null 值
• MyBatis Plus 将 null 写入数据库

Step 3: 检查 BeanUtils.copyProperties 行为

确认 BeanUtils.copyProperties(item, entity) 不会自动映射该字段：

• 源字段名：uploadSequnceNumber
• 目标字段名：batchSequence
• 字段名不一致，BeanUtils 不会自动复制
• 必须手动映射（已在 Task 2 添加）

---

Task 5: 提交代码

Files:

• 无文件修改

Step 1: 查看修改内容

git diff

预期输出：

diff --git a/ccdi-lsfx/src/main/java/com/ruoyi/lsfx/domain/response/GetBankStatementResponse.java b/ccdi-lsfx/src/main/java/com/ruoyi/lsfx/domain/response/GetBankStatementResponse.java
index ...
--- a/ccdi-lsfx/src/main/java/com/ruoyi/lsfx/domain/response/GetBankStatementResponse.java
+++ b/ccdi-lsfx/src/main/java/com/ruoyi/lsfx/domain/response/GetBankStatementResponse.java
@@ -132,6 +132,9 @@ public class GetBankStatementResponse {
         /** 上传logId */
         private Integer batchId;

+        /** 上传序号 */
+        private Integer uploadSequnceNumber;
+
         /** 项目id */
         private Integer groupId;

diff --git a/ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/entity/CcdiBankStatement.java b/ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/entity/CcdiBankStatement.java
index ...
--- a/ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/entity/CcdiBankStatement.java
+++ b/ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/entity/CcdiBankStatement.java
@@ -199,6 +199,7 @@ public class CcdiBankStatement implements Serializable {
             entity.setTrxType(item.getTransTypeId());
             entity.setCustomerLeId(item.getCustomerId());
             entity.setCustomerAccountName(item.getCustomerName());
+            entity.setBatchSequence(item.getUploadSequnceNumber());

             // 5. 特殊字段处理
             entity.setMetaJson(null);  // 根据文档要求强制设为 null

Step 2: 添加到暂存区

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

Step 3: 提交更改

git commit -m "fix: 补充银行流水接口 uploadSequnceNumber 字段接收和映射

- 在 GetBankStatementResponse.BankStatementItem 中添加 uploadSequnceNumber 字段
- 在 CcdiBankStatement.fromResponse() 中添加字段映射到 batchSequence
- 修复流水分析接口返回的上传序号数据丢失问题"

预期输出：

[dev abc1234] fix: 补充银行流水接口 uploadSequnceNumber 字段接收和映射
 2 files changed, 2 insertions(+)

---

验收清单

• 响应类 GetBankStatementResponse.BankStatementItem 包含 uploadSequnceNumber 字段
• Lombok @Data 注解为该字段生成 getter/setter
• 实体转换方法 fromResponse() 包含 batchSequence 字段映射
• 项目编译成功（mvn clean compile）
• 字段命名与文档 assets/对接流水分析/ccdi_bank_statement.md 一致
• 代码已提交到 git

---

后续验证（可选）

如需进一步验证功能，可以：

1. 接口测试：调用流水分析接口，检查响应数据是否包含 uploadSequnceNumber 字段
2. 数据验证：查询数据库 ccdi_bank_statement 表，检查 batch_sequence 列是否有正确的值
3. 日志检查：在转换方法中添加日志，确认字段值正确传递

---

参考资料

• 设计文档：docs/plans/2026-03-05-bank-statement-field-design.md
• 字段映射文档：assets/对接流水分析/ccdi_bank_statement.md
• 接口文档：assets/对接流水分析/兰溪-流水分析对接-新版.md