195 lines
5.0 KiB
Markdown
195 lines
5.0 KiB
Markdown
# 银行流水审计字段补充设计文档
|
||
|
||
## 概述
|
||
|
||
本文档记录为 `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 '创建时间'
|
||
```
|