wkc/ccdi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
bb16fb2369319bc0f5747190f7164c343f8fb417
ccdi/lsfx-mock-server/docs/plans/2026-03-04-interface-alignment-design.md

12 KiB
Raw Blame History

流水分析 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

响应结构：

{
  "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: 未知异常

错误响应格式

{
  "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 服务器将完全对齐接口文档，可以支持前端开发和集成测试。后续可根据实际使用情况：

  • 调整字段生成逻辑（如更真实的数据）
  • 添加更多银行的模板支持
  • 优化错误场景的模拟
Reference in New Issue View Git Blame Copy Permalink