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

银行流水审计字段补充实现计划

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 行之后添加以下代码：

    /** 交易余额 */
    private BigDecimal trxBalance;

    // ===== 审计字段 =====

    /** 创建者 */
    private Long createdBy;

    /** 创建时间 */
    private String createDate;
}

完整修改后的类尾部：

    /** 转换余额 */
    private BigDecimal transfromBalanceAmount;

    /** 交易余额 */
    private BigDecimal trxBalance;

    // ===== 审计字段 =====

    /** 创建者 */
    private Long createdBy;

    /** 创建时间 */
    private String createDate;
}

Step 3: 验证代码编译

运行以下命令验证代码编译通过：

cd D:/ccdi/ccdi
mvn clean compile -pl ccdi-lsfx -am

Expected: BUILD SUCCESS

Step 4: 提交代码

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: 编写测试代码

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: 运行测试

cd D:/ccdi/ccdi
mvn test -Dtest=GetBankStatementResponseTest -pl ccdi-lsfx

Expected: Tests run: 2, Failures: 0, Errors: 0, Skipped: 0

Step 4: 提交测试代码

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 服务器未返回这两个字段，添加以下内容到响应中：

# 在 bank_statement_data 字典中添加
'createdBy': 12345,
'createDate': '2026-03-05 14:30:00',

Step 2: 启动后端服务

提示用户手动启动后端服务：

# 在项目根目录执行
mvn spring-boot:run

# 或者运行启动脚本
ry.bat

Step 3: 启动 mock 服务器（新终端）

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. 输入测试参数：

{
  "groupId": 1,
  "logId": 1,
  "pageNow": 1,
  "pageSize": 10
}

6. 点击 "Execute"
7. 查看响应，验证 createdBy 和 createDate 字段存在

Expected: 响应中的 bankStatementList 包含 createdBy 和 createDate 字段

Step 5: 使用 curl 测试（可选）

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 服务器更新（如果有修改）

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: 提交文档更新

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 节