docs: 添加银行流水审计字段补充设计文档

添加 createdBy 和 createDate 字段到 GetBankStatementResponse.BankStatementItem 类的设计方案

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

@@ -0,0 +1,194 @@
+# 银行流水审计字段补充设计文档
+
+## 概述
+
+本文档记录为 `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 '创建时间'
+```