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 行）之后添加：

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

完整上下文：

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

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

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

**Step 2: 验证 Lombok 注解生效**

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

```java
@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());` 之后）添加：

```java
entity.setBatchSequence(item.getUploadSequnceNumber());
```

完整上下文：

```java
// 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: 编译项目**

在项目根目录执行：

```bash
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: 查看修改内容**

```bash
git diff
```

**预期输出：**

```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: 添加到暂存区**

```bash
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: 提交更改**

```bash
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`