258 lines
7.6 KiB
Markdown
258 lines
7.6 KiB
Markdown
# 银行流水接口字段补充实施计划
|
||
|
||
> **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`
|