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

# 银行流水审计字段补充设计文档

## 概述

本文档记录为 `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 '创建时间'
```