wkc/ccdi

Files

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

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

2026-03-05 18:10:27 +08:00

5.0 KiB

Raw Blame History

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

概述

本文档记录为 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 类的最后添加审计字段组

修改内容：

// ===== 审计字段 =====

/** 创建者 */
private Long createdBy;

/** 创建时间 */
private String createDate;

完整修改后的类结构

@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. 转换为实体

// 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

实现要点

必须实现

✅ 在 BankStatementItem 类中添加两个字段
✅ 添加 Lombok @Data 注解会自动生成 getter/setter

可选优化

日期转换： 如果需要，在 CcdiBankStatement.fromResponse() 中添加 createDate 的日期格式转换
字段验证： 添加 @JsonFormat 注解指定日期格式（如果需要）

测试计划

单元测试

验证 JSON 反序列化能正确映射这两个字段
验证 fromResponse() 方法能正确处理 createdBy 字段

集成测试

调用外部平台接口（或 mock 服务器）
验证响应中包含 createdBy 和 createDate
验证数据能正确保存到数据库

测试数据

{
  "createdBy": 12345,
  "createDate": "2026-03-05 14:30:00"
}

风险评估

风险	影响	概率	缓解措施
外部平台不返回这两个字段	低	中	字段可以为 null，不影响现有功能
日期格式不兼容	中	低	使用 String 类型接收，业务层处理转换
类型不匹配	高	低	已确认类型与实体类一致

变更影响

正面影响

✅ 补全接口字段，与外部平台文档对齐
✅ 支持审计信息传递
✅ 提升数据完整性

负面影响

无（仅添加字段，不影响现有功能）

实现计划

修改 GetBankStatementResponse.BankStatementItem 类
更新相关的 API 文档（如有）
执行集成测试验证功能
提交代码并更新 CHANGELOG

参考资料

外部流水分析平台接口文档 6.5节
CcdiBankStatement 实体类定义
项目开发规范（CLAUDE.md）

附录

数据库字段

-- ccdi_bank_statement 表
created_by BIGINT(20) COMMENT '创建者',
create_date DATETIME COMMENT '创建时间'

5.0 KiB Raw Blame History Unescape Escape