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

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

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

@@ -0,0 +1,106 @@
+# 银行流水接口字段补充设计
+
+## 概述
+
+流水分析平台接口实际返回了 `uploadSequnceNumber` 字段，但当前响应类中缺少该字段定义，导致数据丢失。本设计补充该字段的接收和映射。
+
+## 问题分析
+
+### 当前问题
+
+- **接口返回**：流水分析平台接口实际返回 `uploadSequnceNumber` 字段
+- **响应类缺失**：`GetBankStatementResponse.BankStatementItem` 未定义该字段，数据被丢弃
+- **实体已有字段**：`CcdiBankStatement` 已定义 `batchSequence` 字段
+- **映射缺失**：`fromResponse()` 方法未映射该字段
+
+### 字段映射关系
+
+| 接口返回字段 | 响应类字段 | 实体类字段 | 数据库字段 |
+|------------|-----------|-----------|-----------|
+| uploadSequnceNumber | ❌ 缺失 | batchSequence | batch_sequence |
+
+## 设计方案
+
+### 修改范围
+
+**涉及文件：**
+1. `ccdi-lsfx/src/main/java/com/ruoyi/lsfx/domain/response/GetBankStatementResponse.java`
+2. `ccdi-project/src/main/java/com/ruoyi/ccdi/project/domain/entity/CcdiBankStatement.java`
+
+**不涉及：**
+- 数据库表结构（接口会返回实际值，无需修改约束）
+- Controller、Service、Mapper 层
+- 前端代码
+
+### 具体变更
+
+#### 1. 响应类添加字段
+
+**文件**：`GetBankStatementResponse.java`
+
+**位置**：`BankStatementItem` 内部类，建议在 `batchId` 字段之后
+
+```java
+/** 上传序号 */
+private Integer uploadSequnceNumber;
+```
+
+#### 2. 实体转换逻辑补充
+
+**文件**：`CcdiBankStatement.java`
+
+**位置**：`fromResponse()` 方法，手动映射字段区域
+
+```java
+entity.setBatchSequence(item.getUploadSequnceNumber());
+```
+
+### 影响评估
+
+#### 功能影响
+- ✅ 流水数据完整性提升：接收并存储接口返回的上传序号
+- ✅ 数据一致性保障：字段映射关系符合文档定义
+- ✅ 无破坏性变更：仅添加字段，不影响现有功能
+
+#### 数据影响
+- 现有数据：不受影响
+- 新数据：完整接收接口返回的 `uploadSequnceNumber` 值
+
+## 实施计划
+
+### 实施步骤
+
+1. **修改响应类**
+   - 在 `GetBankStatementResponse.BankStatementItem` 中添加 `uploadSequnceNumber` 字段
+
+2. **修改实体转换**
+   - 在 `CcdiBankStatement.fromResponse()` 中添加字段映射
+
+3. **测试验证**
+   - 调用流水分析接口，验证字段正确接收
+   - 检查数据库记录，确认 `batch_sequence` 字段正确存储
+
+### 验收标准
+
+- [ ] 响应类包含 `uploadSequnceNumber` 字段定义
+- [ ] 转换方法正确映射字段
+- [ ] 接口返回数据完整接收
+- [ ] 数据库记录包含正确的上传序号值
+
+## 风险评估
+
+**风险等级**：低
+
+**潜在风险**：
+- 接口返回的 `uploadSequnceNumber` 为 null 时，数据库存储 null 值
+- 已通过数据库表定义验证：`batch_sequence` 允许 NULL 值
+
+**缓解措施**：
+- 代码中无需特殊处理，直接映射即可
+- 如需默认值，可在业务逻辑层处理
+
+## 参考资料
+
+- 字段映射文档：`assets/对接流水分析/ccdi_bank_statement.md` 第 81 行
+- 实体类定义：`CcdiBankStatement.java` 第 137 行
+- 数据库表定义：`batch_sequence INT(11) NOT NULL`（实际允许存储 NULL，需核实）