# 银行流水接口字段补充设计

## 概述

流水分析平台接口实际返回了 `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，需核实）