data转换

docs: 添加银行流水审计字段补充实现计划
详细的实现步骤，包含 4 个任务： - Task 1: 添加审计字段到响应类 - Task 2: 验证 JSON 反序列化 - Task 3: 集成测试验证 - Task 4: 更新文档遵循 TDD 流程，提供完整的代码和测试命令
2026-03-05 18:23:03 +08:00 · 2026-03-05 18:12:46 +08:00 · 2026-03-05 18:10:27 +08:00
5 changed files with 940 additions and 0 deletions
--- 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
@@ -1,8 +1,10 @@
 package com.ruoyi.lsfx.domain.response;

+import com.fasterxml.jackson.annotation.JsonFormat;
 import lombok.Data;

 import java.math.BigDecimal;
+import java.util.Date;
 import java.util.List;

 /**
@@ -187,5 +189,14 @@ public class GetBankStatementResponse {

        /** 交易余额 */
        private BigDecimal trxBalance;
+
+        // ===== 审计字段 =====
+
+        /** 创建时间 */
+        @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
+        private Date createDate;
+
+        /** 创建者 */
+        private Long createdBy;
    }
 }
--- a/docs/plans/2026-03-05-bank-statement-audit-fields-design.md
+++ b/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 '创建时间'
+```
--- a/docs/plans/2026-03-05-bank-statement-audit-fields-implementation.md
+++ b/docs/plans/2026-03-05-bank-statement-audit-fields-implementation.md
@@ -0,0 +1,372 @@
+# 银行流水审计字段补充实现计划
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** 为 GetBankStatementResponse.BankStatementItem 类添加 createdBy 和 createDate 两个审计字段，使其能够接收外部流水分析平台返回的审计信息。
+
+**Architecture:** 在响应类的 BankStatementItem 内部类中添加两个审计字段，Lombok @Data 注解会自动生成 getter/setter，无需手动编写。字段类型为 Long 和 String，与外部平台接口文档对齐。
+
+**Tech Stack:** Java 21, Lombok, Jackson (JSON 序列化/反序列化)
+
+---
+
+## Task 1: 添加审计字段到响应类
+
+**Files:**
+- Modify: `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/domain/response/GetBankStatementResponse.java:189-190`
+
+**Step 1: 打开响应类文件**
+
+在编辑器中打开文件：
+```
+ccdi-lsfx/src/main/java/com/ruoyi/lsfx/domain/response/GetBankStatementResponse.java
+```
+
+定位到 `BankStatementItem` 内部类的最后，找到第 189 行附近（在 `trxBalance` 字段之后）。
+
+**Step 2: 添加审计字段**
+
+在第 189 行之后添加以下代码：
+
+```java
+    /** 交易余额 */
+    private BigDecimal trxBalance;
+
+    // ===== 审计字段 =====
+
+    /** 创建者 */
+    private Long createdBy;
+
+    /** 创建时间 */
+    private String createDate;
+}
+```
+
+**完整修改后的类尾部：**
+
+```java
+    /** 转换余额 */
+    private BigDecimal transfromBalanceAmount;
+
+    /** 交易余额 */
+    private BigDecimal trxBalance;
+
+    // ===== 审计字段 =====
+
+    /** 创建者 */
+    private Long createdBy;
+
+    /** 创建时间 */
+    private String createDate;
+}
+```
+
+**Step 3: 验证代码编译**
+
+运行以下命令验证代码编译通过：
+
+```bash
+cd D:/ccdi/ccdi
+mvn clean compile -pl ccdi-lsfx -am
+```
+
+Expected: `BUILD SUCCESS`
+
+**Step 4: 提交代码**
+
+```bash
+git add ccdi-lsfx/src/main/java/com/ruoyi/lsfx/domain/response/GetBankStatementResponse.java
+git commit -m "feat(ccdi-lsfx): 添加银行流水审计字段 createdBy 和 createDate
+
+- 在 GetBankStatementResponse.BankStatementItem 中添加 createdBy 字段（Long 类型）
+- 在 GetBankStatementResponse.BankStatementItem 中添加 createDate 字段（String 类型）
+- 补充外部流水分析平台接口文档 6.5 节中定义的审计字段
+- 支持接收外部平台返回的创建者和创建时间信息"
+```
+
+---
+
+## Task 2: 验证 JSON 反序列化（可选但推荐）
+
+**Files:**
+- Create: `ccdi-lsfx/src/test/java/com/ruoyi/lsfx/domain/response/GetBankStatementResponseTest.java`
+
+**Step 1: 创建测试类**
+
+创建测试文件：
+```
+ccdi-lsfx/src/test/java/com/ruoyi/lsfx/domain/response/GetBankStatementResponseTest.java
+```
+
+**Step 2: 编写测试代码**
+
+```java
+package com.ruoyi.lsfx.domain.response;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.Test;
+
+import java.math.BigDecimal;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * GetBankStatementResponse 单元测试
+ */
+class GetBankStatementResponseTest {
+
+    private final ObjectMapper objectMapper = new ObjectMapper();
+
+    @Test
+    void testDeserializeBankStatementItem() throws Exception {
+        // 准备测试数据（包含审计字段）
+        String json = """
+            {
+              "code": "0",
+              "status": "success",
+              "successResponse": true,
+              "data": {
+                "bankStatementList": [
+                  {
+                    "bankStatementId": 123456,
+                    "leId": 100,
+                    "accountId": 200,
+                    "leName": "测试企业",
+                    "accountMaskNo": "6222****1234",
+                    "trxDate": "2026-03-05",
+                    "currency": "CNY",
+                    "drAmount": 1000.00,
+                    "crAmount": 0,
+                    "balanceAmount": 5000.00,
+                    "createdBy": 12345,
+                    "createDate": "2026-03-05 14:30:00"
+                  }
+                ],
+                "totalCount": 1
+              }
+            }
+            """;
+
+        // 反序列化
+        GetBankStatementResponse response = objectMapper.readValue(json, GetBankStatementResponse.class);
+
+        // 验证基本字段
+        assertNotNull(response);
+        assertEquals("0", response.getCode());
+        assertEquals("success", response.getStatus());
+        assertTrue(response.getSuccessResponse());
+
+        // 验证数据列表
+        assertNotNull(response.getData());
+        assertNotNull(response.getData().getBankStatementList());
+        assertEquals(1, response.getData().getTotalCount());
+
+        // 验证流水项
+        GetBankStatementResponse.BankStatementItem item = response.getData().getBankStatementList().get(0);
+        assertNotNull(item);
+        assertEquals(123456L, item.getBankStatementId());
+        assertEquals(100, item.getLeId());
+        assertEquals("测试企业", item.getLeName());
+
+        // 验证审计字段
+        assertEquals(12345L, item.getCreatedBy());
+        assertEquals("2026-03-05 14:30:00", item.getCreateDate());
+    }
+
+    @Test
+    void testDeserializeWithNullAuditFields() throws Exception {
+        // 测试审计字段为 null 的情况
+        String json = """
+            {
+              "code": "0",
+              "data": {
+                "bankStatementList": [
+                  {
+                    "bankStatementId": 123456
+                  }
+                ],
+                "totalCount": 1
+              }
+            }
+            """;
+
+        GetBankStatementResponse response = objectMapper.readValue(json, GetBankStatementResponse.class);
+        GetBankStatementResponse.BankStatementItem item = response.getData().getBankStatementList().get(0);
+
+        // 审计字段应该为 null
+        assertNull(item.getCreatedBy());
+        assertNull(item.getCreateDate());
+    }
+}
+```
+
+**Step 3: 运行测试**
+
+```bash
+cd D:/ccdi/ccdi
+mvn test -Dtest=GetBankStatementResponseTest -pl ccdi-lsfx
+```
+
+Expected: `Tests run: 2, Failures: 0, Errors: 0, Skipped: 0`
+
+**Step 4: 提交测试代码**
+
+```bash
+git add ccdi-lsfx/src/test/java/com/ruoyi/lsfx/domain/response/GetBankStatementResponseTest.java
+git commit -m "test(ccdi-lsfx): 添加银行流水响应类单元测试
+
+- 测试 JSON 反序列化能正确映射 createdBy 和 createDate 字段
+- 测试审计字段为 null 时的处理
+- 验证字段类型和值的正确性"
+```
+
+---
+
+## Task 3: 集成测试验证
+
+**Files:**
+- Modify: `lsfx-mock-server/app.py` (如果需要更新 mock 服务器)
+- Test: 使用 Swagger UI 或 curl 测试接口
+
+**Step 1: 检查 mock 服务器是否返回审计字段**
+
+检查 `lsfx-mock-server/app.py` 文件，确认银行流水接口返回的数据中包含 `createdBy` 和 `createDate` 字段。
+
+如果 mock 服务器未返回这两个字段，添加以下内容到响应中：
+
+```python
+# 在 bank_statement_data 字典中添加
+'createdBy': 12345,
+'createDate': '2026-03-05 14:30:00',
+```
+
+**Step 2: 启动后端服务**
+
+提示用户手动启动后端服务：
+
+```bash
+# 在项目根目录执行
+mvn spring-boot:run
+
+# 或者运行启动脚本
+ry.bat
+```
+
+**Step 3: 启动 mock 服务器（新终端）**
+
+```bash
+cd lsfx-mock-server
+python app.py
+```
+
+Expected: Mock 服务器在 http://localhost:8000 启动
+
+**Step 4: 使用 Swagger UI 测试接口**
+
+1. 打开浏览器访问: http://localhost:8080/swagger-ui/index.html
+2. 找到 "流水分析平台接口测试" 分组
+3. 点击 "POST /lsfx/test/getBankStatement" 接口
+4. 点击 "Try it out"
+5. 输入测试参数：
+
+```json
+{
+  "groupId": 1,
+  "logId": 1,
+  "pageNow": 1,
+  "pageSize": 10
+}
+```
+
+6. 点击 "Execute"
+7. 查看响应，验证 `createdBy` 和 `createDate` 字段存在
+
+Expected: 响应中的 `bankStatementList` 包含 `createdBy` 和 `createDate` 字段
+
+**Step 5: 使用 curl 测试（可选）**
+
+```bash
+curl -X POST "http://localhost:8080/lsfx/test/getBankStatement" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "groupId": 1,
+    "logId": 1,
+    "pageNow": 1,
+    "pageSize": 10
+  }'
+```
+
+Expected: JSON 响应中包含 `createdBy` 和 `createDate` 字段
+
+**Step 6: 提交 mock 服务器更新（如果有修改）**
+
+```bash
+git add lsfx-mock-server/app.py
+git commit -m "feat(lsfx-mock): 添加银行流水审计字段到 mock 响应
+
+- 添加 createdBy 字段（用户ID）
+- 添加 createDate 字段（创建时间）
+- 与外部平台接口文档 6.5 节对齐"
+```
+
+---
+
+## Task 4: 更新文档（可选）
+
+**Files:**
+- Update: `docs/plans/2026-03-05-bank-statement-audit-fields-design.md`（已存在）
+
+**Step 1: 验证设计文档完整性**
+
+确认设计文档包含以下内容：
+- ✅ 问题描述
+- ✅ 字段定义
+- ✅ 代码修改
+- ✅ 测试计划
+- ✅ 风险评估
+
+**Step 2: 更新 API 文档（如果有）**
+
+如果项目中有 API 文档文件，更新银行流水接口的响应字段说明，添加：
+- `createdBy`: 创建者用户ID（Long 类型）
+- `createDate`: 创建时间（String 类型）
+
+**Step 3: 提交文档更新**
+
+```bash
+git add docs/
+git commit -m "docs: 更新银行流水接口文档，补充审计字段说明"
+```
+
+---
+
+## 完成清单
+
+- [ ] Task 1: 添加审计字段到响应类
+- [ ] Task 2: 验证 JSON 反序列化（可选但推荐）
+- [ ] Task 3: 集成测试验证
+- [ ] Task 4: 更新文档（可选）
+
+## 验收标准
+
+1. ✅ `GetBankStatementResponse.BankStatementItem` 类包含 `createdBy` 和 `createDate` 字段
+2. ✅ 字段类型正确：`createdBy` 为 Long，`createDate` 为 String
+3. ✅ 代码编译通过
+4. ✅ 单元测试通过（如果编写）
+5. ✅ 集成测试通过，能正确接收外部平台的审计字段
+6. ✅ 代码已提交到 git
+
+## 风险与缓解
+
+| 风险 | 缓解措施 |
+|------|----------|
+| 外部平台不返回审计字段 | 字段可以为 null，不影响现有功能 |
+| 日期格式不一致 | 使用 String 类型接收，业务层处理转换 |
+| JSON 反序列化失败 | 编写单元测试验证，使用 Jackson 注解处理格式 |
+
+## 参考资料
+
+- 设计文档: `docs/plans/2026-03-05-bank-statement-audit-fields-design.md`
+- 实体类: `ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/entity/CcdiBankStatement.java`
+- 项目规范: `CLAUDE.md`
+- 外部平台接口文档 6.5 节
--- a/docs/plans/2026-03-05-bank-statement-field-design.md
+++ b/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，需核实）
--- a/docs/plans/2026-03-05-bank-statement-field-implementation.md
+++ b/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`