310 lines
12 KiB
Markdown
310 lines
12 KiB
Markdown
# 流水分析 Mock 服务器接口完整对齐设计
|
||
|
||
**日期：** 2026-03-04
|
||
**目标：** 根据 `兰溪-流水分析对接3.md` 文档，完整对齐所有接口实现
|
||
|
||
## 概述
|
||
|
||
本次更新将 Mock 服务器完全对齐最新的接口文档，包括新增缺失接口、完善响应字段、统一错误处理。采用渐进式更新策略，保持现有功能不受影响。
|
||
|
||
## 设计目标
|
||
|
||
1. **新增缺失接口** - 实现文档中的第5个接口（获取单个文件上传状态）
|
||
2. **响应字段完整** - 所有7个接口的响应字段完全对齐文档示例
|
||
3. **数据模型增强** - 扩展文件记录模型以支持完整字段
|
||
4. **错误码完善** - 补充文档中提到的所有错误码
|
||
5. **无测试依赖** - 按用户要求，不涉及测试用例更新
|
||
|
||
## 架构设计
|
||
|
||
### 总体架构
|
||
|
||
保持现有无数据库架构不变，通过内存数据结构增强支持完整字段存储。
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ FastAPI 应用 │
|
||
├─────────────────────────────────────────┤
|
||
│ routers/api.py │
|
||
│ ├─ 7个接口路由（新增接口5） │
|
||
│ └─ 错误标记检测 │
|
||
├─────────────────────────────────────────┤
|
||
│ services/ │
|
||
│ ├─ token_service.py │
|
||
│ ├─ file_service.py（增强） │
|
||
│ │ ├─ FileRecord（扩展字段） │
|
||
│ │ ├─ upload_file()（初始化完整字段） │
|
||
│ │ ├─ get_upload_status()（新增） │
|
||
│ │ └─ delete_files() │
|
||
│ └─ statement_service.py │
|
||
├─────────────────────────────────────────┤
|
||
│ config/responses/ │
|
||
│ ├─ token.json（更新） │
|
||
│ ├─ upload.json（更新） │
|
||
│ ├─ parse_status.json（更新） │
|
||
│ ├─ bank_statement.json（更新） │
|
||
│ └─ upload_status.json（新建） │
|
||
├─────────────────────────────────────────┤
|
||
│ utils/ │
|
||
│ └─ error_simulator.py（补充错误码） │
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
## 核心设计
|
||
|
||
### 1. 数据模型扩展
|
||
|
||
#### FileRecord 扩展字段
|
||
|
||
在 `services/file_service.py` 中扩展 `FileRecord` 类：
|
||
|
||
**现有字段：**
|
||
- `log_id`, `group_id`, `file_name`, `status`, `upload_status_desc`, `parsing`
|
||
|
||
**新增字段（对齐文档）：**
|
||
- `account_no_list: List[str]` - 账号列表
|
||
- `enterprise_name_list: List[str]` - 主体名称列表
|
||
- `bank_name: str` - 银行名称（如 "ZJRCU", "ALIPAY", "BSX"）
|
||
- `real_bank_name: str` - 真实银行名称
|
||
- `template_name: str` - 模板名称（如 "ZJRCU_T251114"）
|
||
- `data_type_info: List[str]` - 数据类型（如 ["CSV", ","]）
|
||
- `file_size: int` - 文件大小（字节）
|
||
- `download_file_name: str` - 下载文件名
|
||
- `file_package_id: str` - 文件包ID（UUID格式）
|
||
- `file_upload_by: int` - 上传用户ID
|
||
- `file_upload_by_user_name: str` - 上传用户名
|
||
- `file_upload_time: str` - 上传时间（如 "2026-02-27 09:50:18"）
|
||
- `le_id: int` - 法律实体ID
|
||
- `login_le_id: int` - 登录法律实体ID
|
||
- `log_type: str` - 日志类型（如 "bankstatement"）
|
||
- `log_meta: str` - 日志元数据（JSON字符串）
|
||
- `lost_header: List[str]` - 丢失的头部信息
|
||
- `rows: int` - 行数
|
||
- `source: str` - 来源（如 "http"）
|
||
- `total_records: int` - 总记录数
|
||
- `trx_date_start_id: int` - 交易开始日期ID（如 20240201）
|
||
- `trx_date_end_id: int` - 交易结束日期ID（如 20240228）
|
||
- `is_split: int` - 是否分割（0或1）
|
||
|
||
#### 字段初始化策略
|
||
|
||
- `bank_name`: 根据文件名推断（包含"支付宝"→"ALIPAY"，默认"ZJRCU"）
|
||
- `template_name`: 根据 bank_name 生成（如 "ZJRCU_T251114"）
|
||
- `file_package_id`: 生成随机UUID
|
||
- `file_upload_time`: 使用当前服务器时间
|
||
- `total_records`: 随机生成（100-300）
|
||
- `trx_date_start_id`/`trx_date_end_id`: 生成合理的日期范围
|
||
- 其他字段: 使用文档示例中的典型值
|
||
|
||
### 2. 新增接口实现
|
||
|
||
#### 接口5：GET `/watson/api/project/bs/upload`
|
||
|
||
**功能：** 获取单个文件上传后的状态
|
||
|
||
**请求参数：**
|
||
- `groupId` (int, 必填) - 项目ID
|
||
- `logId` (int, 可选) - 文件ID
|
||
|
||
**响应结构：**
|
||
```json
|
||
{
|
||
"code": "200",
|
||
"data": {
|
||
"logs": [
|
||
{
|
||
"accountNoList": ["18785967364"],
|
||
"bankName": "ALIPAY",
|
||
"dataTypeInfo": ["CSV", ","],
|
||
"downloadFileName": "支付宝.csv",
|
||
"enterpriseNameList": ["曾孝成"],
|
||
"fileSize": 16322,
|
||
"fileUploadBy": 448,
|
||
"fileUploadByUserName": "admin@support.com",
|
||
"fileUploadTime": "2025-03-13 08:45:32",
|
||
"isSplit": 0,
|
||
"leId": 10741,
|
||
"logId": 13994,
|
||
"logMeta": "{\"lostHeader\":[],\"balanceAmount\":\"-1\"}",
|
||
"logType": "bankstatement",
|
||
"loginLeId": 10741,
|
||
"lostHeader": [],
|
||
"realBankName": "ALIPAY",
|
||
"rows": 0,
|
||
"source": "http",
|
||
"status": -5,
|
||
"templateName": "ALIPAY_T220708",
|
||
"totalRecords": 127,
|
||
"trxDateEndId": 20231231,
|
||
"trxDateStartId": 20230102,
|
||
"uploadFileName": "支付宝.pdf",
|
||
"uploadStatusDesc": "data.wait.confirm.newaccount"
|
||
}
|
||
],
|
||
"status": "",
|
||
"accountId": 8954,
|
||
"currency": "CNY"
|
||
},
|
||
"status": "200",
|
||
"successResponse": true
|
||
}
|
||
```
|
||
|
||
**实现逻辑：**
|
||
1. 路由：在 `routers/api.py` 添加 GET 路由
|
||
2. 服务：在 `file_service.py` 添加 `get_upload_status(groupId, logId)` 方法
|
||
3. 逻辑：
|
||
- 如果提供 `logId`，返回该特定文件的状态
|
||
- 如果不提供 `logId`，返回该项目的所有文件状态
|
||
- 从 `file_records` 中查询并构建响应
|
||
|
||
**特殊处理：**
|
||
- `accountId` 和 `currency`: 从文件记录中提取或使用默认值（8954, "CNY"）
|
||
- 空主体标识：如果 `enterpriseNameList` 仅包含空字符串，表示流水文件未生成主体
|
||
|
||
### 3. 现有接口响应字段更新
|
||
|
||
#### 接口1：`/account/common/getToken`
|
||
- 确认 `data.analysisType` 类型为 Integer
|
||
- 保持其他字段不变
|
||
|
||
#### 接口2：`/watson/api/project/remoteUploadSplitFile`
|
||
- 补充 `accountsOfLog` 结构
|
||
- 完善 `uploadLogList` 中的所有字段
|
||
- 新增 `uploadStatus` 字段（固定值 1）
|
||
|
||
#### 接口3：`/watson/api/project/getJZFileOrZjrcuFile`
|
||
- 保持现有响应格式
|
||
- 返回 `{code, data: [logId数组], status, successResponse}`
|
||
|
||
#### 接口4：`/watson/api/project/upload/getpendings`
|
||
- 补充 `data.pendingList` 中的所有字段
|
||
- 确保包含 `isSplit`, `lostHeader`, `leId`, `loginLeId` 等
|
||
|
||
#### 接口6：`/watson/api/project/batchDeleteUploadFile`
|
||
- 注意 `code` 字段为 "200 OK" 而非 "200"
|
||
- 响应格式：`{code: "200 OK", data: {message: "delete.files.success"}, ...}`
|
||
|
||
#### 接口7：`/watson/api/project/getBSByLogId`
|
||
- 补充 `bankStatementList` 中每个对象的所有50+个字段
|
||
- 字段包括：accountId, accountMaskNo, accountingDate, balanceAmount, bank, bankStatementId, bankTrxNumber, batchId, cashType, crAmount, cretNo, currency, customerAccountMaskNo, customerBank, customerId, customerName, drAmount, groupId, leId, leName, transAmount, transFlag, trxDate, userMemo 等
|
||
|
||
### 4. 错误码完善
|
||
|
||
#### 当前错误码（已有）
|
||
- 40101: appId错误
|
||
- 40102: appSecretCode错误
|
||
- 40104: 可使用项目次数为0，无法创建项目
|
||
- 40105: 只读模式下无法新建项目
|
||
- 40106: 错误的分析类型，不在规定的取值范围内
|
||
- 40107: 当前系统不支持的分析类型
|
||
- 40108: 当前用户所属行社无权限
|
||
- 501014: 无行内流水文件
|
||
|
||
#### 新增错误码
|
||
- 40100: 未知异常
|
||
|
||
#### 错误响应格式
|
||
```json
|
||
{
|
||
"code": "错误码",
|
||
"message": "错误描述",
|
||
"status": "错误码",
|
||
"successResponse": false
|
||
}
|
||
```
|
||
|
||
#### 错误触发机制
|
||
- 在任意字符串参数中包含 `error_XXXX` 标记
|
||
- 例如：`projectNo: "test_error_40100"` 触发 40100 错误
|
||
|
||
### 5. 请求头处理
|
||
|
||
#### X-Xencio-Client-Id
|
||
- **策略：** 不验证，接受任意值
|
||
- **原因：** 简化测试，不需要记住特定的 client-id
|
||
- **实现：** FastAPI 不检查该请求头
|
||
|
||
## 实施计划
|
||
|
||
### 步骤1：数据模型扩展
|
||
- **文件：** `services/file_service.py`
|
||
- **内容：** 扩展 `FileRecord` 类，添加所有新字段
|
||
- **验证：** 启动服务无报错
|
||
|
||
### 步骤2：文件服务增强
|
||
- **文件：** `services/file_service.py`
|
||
- **内容：**
|
||
- 在 `upload_file()` 方法中初始化所有新字段
|
||
- 添加 `get_upload_status()` 方法
|
||
- 更新 `delete_files()` 方法以处理新增字段
|
||
- **验证：** 上传文件后能返回完整字段
|
||
|
||
### 步骤3：新增接口路由
|
||
- **文件：** `routers/api.py`
|
||
- **内容：** 添加 GET `/watson/api/project/bs/upload` 路由
|
||
- **验证：** 访问 `/docs` 能看到新接口
|
||
|
||
### 步骤4：响应模板更新
|
||
- **文件：**
|
||
- `config/responses/token.json`
|
||
- `config/responses/upload.json`
|
||
- `config/responses/parse_status.json`
|
||
- `config/responses/bank_statement.json`
|
||
- 新建 `config/responses/upload_status.json`
|
||
- **内容：** 补充所有缺失字段，对齐文档示例
|
||
- **验证：** 调用接口返回完整字段
|
||
|
||
### 步骤5：错误码补充
|
||
- **文件：** `utils/error_simulator.py`
|
||
- **内容：** 添加 40100 错误码
|
||
- **验证：** 使用 `error_40100` 能触发对应错误
|
||
|
||
### 步骤6：文档更新
|
||
- **文件：**
|
||
- `CLAUDE.md`
|
||
- `README.md`（如存在）
|
||
- **内容：** 添加新接口说明，更新注意事项
|
||
|
||
## 文件变更清单
|
||
|
||
```
|
||
services/file_service.py [修改] - 数据模型和服务方法
|
||
routers/api.py [修改] - 新增接口路由
|
||
utils/error_simulator.py [修改] - 新增错误码
|
||
config/responses/token.json [修改] - 完善响应字段
|
||
config/responses/upload.json [修改] - 完善响应字段
|
||
config/responses/parse_status.json [修改] - 完善响应字段
|
||
config/responses/bank_statement.json [修改] - 完善响应字段
|
||
config/responses/upload_status.json [新建] - 接口5响应模板
|
||
CLAUDE.md [修改] - 更新接口说明
|
||
README.md [修改] - 更新项目说明（如存在）
|
||
```
|
||
|
||
## 风险评估
|
||
|
||
### 低风险
|
||
- 数据模型扩展：仅添加字段，不影响现有功能
|
||
- 响应模板更新：仅添加字段，向后兼容
|
||
- 错误码补充：新增错误码，不影响现有错误处理
|
||
|
||
### 需注意
|
||
- 文件上传逻辑：需要确保所有新字段都正确初始化
|
||
- 时间格式：确保 `file_upload_time` 使用正确的格式
|
||
- 字段类型：确保 Integer 字段不使用字符串
|
||
|
||
## 成功标准
|
||
|
||
1. 所有7个接口都能正常调用
|
||
2. 每个接口的响应字段完全对齐文档示例
|
||
3. 错误标记机制在所有接口中都能正常工作
|
||
4. 新增的 40100 错误码能正确触发
|
||
5. 服务启动无报错，能正常处理请求
|
||
|
||
## 后续工作
|
||
|
||
本次更新完成后，Mock 服务器将完全对齐接口文档，可以支持前端开发和集成测试。后续可根据实际使用情况：
|
||
- 调整字段生成逻辑（如更真实的数据）
|
||
- 添加更多银行的模板支持
|
||
- 优化错误场景的模拟
|