# 流水分析 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 服务器将完全对齐接口文档，可以支持前端开发和集成测试。后续可根据实际使用情况：
- 调整字段生成逻辑（如更真实的数据）
- 添加更多银行的模板支持
- 优化错误场景的模拟