diff --git a/docs/plans/2026-03-05-bank-statement-audit-fields-implementation.md b/docs/plans/2026-03-05-bank-statement-audit-fields-implementation.md new file mode 100644 index 0000000..72125a2 --- /dev/null +++ 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 节