完善lsfx mock服务上传状态接口与部署文档

2026-03-13 16:38:07 +08:00
parent bda89202ba
commit 109b5220b2
29 changed files with 4489 additions and 67 deletions
--- a/lsfx-mock-server/docs/plans/2026-03-04-interface-alignment-design.md
+++ b/lsfx-mock-server/docs/plans/2026-03-04-interface-alignment-design.md
@@ -0,0 +1,309 @@
+# 流水分析 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 服务器将完全对齐接口文档，可以支持前端开发和集成测试。后续可根据实际使用情况：
+- 调整字段生成逻辑（如更真实的数据）
+- 添加更多银行的模板支持
+- 优化错误场景的模拟