docs: 添加银行流水审计字段补充设计文档

添加 createdBy 和 createDate 字段到 GetBankStatementResponse.BankStatementItem 类的设计方案

docs/plans/2026-03-05-bank-statement-audit-fields-design.md

@@ -0,0 +1,194 @@
+# 银行流水审计字段补充设计文档
+
+## 概述
+
+本文档记录为 `GetBankStatementResponse.BankStatementItem` 类添加 `createdBy` 和 `createDate` 审计字段的设计方案。
+
+## 背景
+
+### 问题描述
+
+外部流水分析平台的接口文档（6.5节）中包含 `createdBy` 和 `createDate` 字段，但我们的响应类 `GetBankStatementResponse.BankStatementItem` 中缺少这两个字段的定义，导致无法接收外部平台返回的审计信息。
+
+### 影响范围
+
+- **直接影响：** `GetBankStatementResponse.BankStatementItem` 类
+- **间接影响：** `CcdiBankStatement.fromResponse()` 方法（已有对应字段，无需修改）
+- **数据流：** 外部平台 → 响应类 → 实体类 → 数据库
+
+## 设计方案
+
+### 字段定义
+
+在 `GetBankStatementResponse.BankStatementItem` 类中添加两个审计字段：
+
+| 字段名 | 类型 | 说明 | 来源 |
+|--------|------|------|------|
+| `createdBy` | `Long` | 创建者用户ID | 外部平台 |
+| `createDate` | `String` | 创建时间 | 外部平台 |
+
+### 类型选择
+
+- **createdBy**: 使用 `Long` 类型
+  - 与实体类 `CcdiBankStatement` 保持一致
+  - 用户ID通常为长整型数字
+
+- **createDate**: 使用 `String` 类型
+  - 外部平台返回时间字符串格式（如 "2026-03-05 10:30:00"）
+  - 避免时间格式转换问题
+  - 由业务层负责转换为 Date 类型
+
+### 代码修改
+
+**文件：** `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/domain/response/GetBankStatementResponse.java`
+
+**修改位置：** 在 `BankStatementItem` 类的最后添加审计字段组
+
+**修改内容：**
+
+```java
+// ===== 审计字段 =====
+
+/** 创建者 */
+private Long createdBy;
+
+/** 创建时间 */
+private String createDate;
+```
+
+### 完整修改后的类结构
+
+```java
+@Data
+public static class BankStatementItem {
+    // ===== 账号相关信息 =====
+    /** 流水ID */
+    private Long bankStatementId;
+    // ... 其他字段
+
+    // ===== 附加字段 =====
+    /** 附件数量 */
+    private Integer attachments;
+    // ... 其他附加字段
+
+    // ===== 审计字段 =====
+    /** 创建者 */
+    private Long createdBy;
+
+    /** 创建时间 */
+    private String createDate;
+}
+```
+
+## 数据流分析
+
+### 1. 接收外部数据
+
+```
+外部平台 → GetBankStatementResponse.BankStatementItem
+  - createdBy: Long
+  - createDate: String
+```
+
+### 2. 转换为实体
+
+```java
+// CcdiBankStatement.fromResponse() 方法
+CcdiBankStatement entity = new CcdiBankStatement();
+BeanUtils.copyProperties(item, entity);
+// 自动复制 createdBy (Long → Long)
+// createDate 字段类型不匹配 (String → Date)，需要手动转换
+```
+
+**注意：** 如果需要自动转换 `createDate`，需要修改 `fromResponse()` 方法添加日期格式转换逻辑。
+
+### 3. 保存到数据库
+
+```
+CcdiBankStatement
+  - createdBy: Long → 数据库字段 created_by
+  - createDate: Date → 数据库字段 create_date
+```
+
+## 实现要点
+
+### 必须实现
+
+1. ✅ 在 `BankStatementItem` 类中添加两个字段
+2. ✅ 添加 Lombok `@Data` 注解会自动生成 getter/setter
+
+### 可选优化
+
+1. **日期转换：** 如果需要，在 `CcdiBankStatement.fromResponse()` 中添加 `createDate` 的日期格式转换
+2. **字段验证：** 添加 `@JsonFormat` 注解指定日期格式（如果需要）
+
+## 测试计划
+
+### 单元测试
+
+- 验证 JSON 反序列化能正确映射这两个字段
+- 验证 `fromResponse()` 方法能正确处理 `createdBy` 字段
+
+### 集成测试
+
+1. 调用外部平台接口（或 mock 服务器）
+2. 验证响应中包含 `createdBy` 和 `createDate`
+3. 验证数据能正确保存到数据库
+
+### 测试数据
+
+```json
+{
+  "createdBy": 12345,
+  "createDate": "2026-03-05 14:30:00"
+}
+```
+
+## 风险评估
+
+| 风险 | 影响 | 概率 | 缓解措施 |
+|------|------|------|----------|
+| 外部平台不返回这两个字段 | 低 | 中 | 字段可以为 null，不影响现有功能 |
+| 日期格式不兼容 | 中 | 低 | 使用 String 类型接收，业务层处理转换 |
+| 类型不匹配 | 高 | 低 | 已确认类型与实体类一致 |
+
+## 变更影响
+
+### 正面影响
+
+- ✅ 补全接口字段，与外部平台文档对齐
+- ✅ 支持审计信息传递
+- ✅ 提升数据完整性
+
+### 负面影响
+
+- 无（仅添加字段，不影响现有功能）
+
+## 实现计划
+
+1. 修改 `GetBankStatementResponse.BankStatementItem` 类
+2. 更新相关的 API 文档（如有）
+3. 执行集成测试验证功能
+4. 提交代码并更新 CHANGELOG
+
+## 参考资料
+
+- 外部流水分析平台接口文档 6.5节
+- `CcdiBankStatement` 实体类定义
+- 项目开发规范（CLAUDE.md）
+
+## 附录
+
+### 相关文件路径
+
+- 响应类：`ccdi-lsfx/src/main/java/com/ruoyi/lsfx/domain/response/GetBankStatementResponse.java`
+- 实体类：`ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/entity/CcdiBankStatement.java`
+- 客户端：`ccdi-lsfx/src/main/java/com/ruoyi/lsfx/client/LsfxAnalysisClient.java`
+
+### 数据库字段
+
+```sql
+-- ccdi_bank_statement 表
+created_by BIGINT(20) COMMENT '创建者',
+create_date DATETIME COMMENT '创建时间'
+```

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

@@ -0,0 +1,106 @@
+# 银行流水接口字段补充设计
+
+## 概述
+
+流水分析平台接口实际返回了 `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` 字段之后
+
+```java
+/** 上传序号 */
+private Integer uploadSequnceNumber;
+```
+
+#### 2. 实体转换逻辑补充
+
+**文件**：`CcdiBankStatement.java`
+
+**位置**：`fromResponse()` 方法，手动映射字段区域
+
+```java
+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，需核实）

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

@@ -0,0 +1,257 @@
+# 银行流水接口字段补充实施计划
+
+> **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`