wkc
35fdc72ffb
详细的实现步骤，包含 4 个任务： - Task 1: 添加审计字段到响应类 - Task 2: 验证 JSON 反序列化 - Task 3: 集成测试验证 - Task 4: 更新文档 遵循 TDD 流程，提供完整的代码和测试命令
373 lines
10 KiB
Markdown
373 lines
10 KiB
Markdown
# 银行流水审计字段补充实现计划
|
||
|
||
> **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 节
|