ccdi/lsfx-mock-server/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

这是一个基于 FastAPI 的 Mock 服务器，用于模拟流水分析平台的 7 个核心接口。主要特点：

• 无数据库设计 - 使用内存存储，服务重启后数据丢失
• 配置驱动 - 响应数据来自 config/responses/ 下的 JSON 模板
• 错误场景模拟 - 通过 error_XXXX 标记触发特定错误码
• 异步文件解析 - 使用 FastAPI BackgroundTasks 模拟 4 秒解析延迟

常用命令

开发运行

# 安装依赖
pip install -r requirements.txt

# 启动服务（普通模式）
python main.py

# 启动服务（热重载模式，推荐开发时使用）
uvicorn main:app --reload --host 0.0.0.0 --port 8000

# 访问 API 文档
# Swagger UI: http://localhost:8000/docs
# ReDoc: http://localhost:8000/redoc

测试

# 运行所有测试
pytest tests/ -v

# 运行单个测试文件
pytest tests/test_api.py -v

# 生成覆盖率报告
pytest tests/ -v --cov=. --cov-report=html

Docker 部署

# 构建镜像
docker build -t lsfx-mock-server .

# 运行容器
docker run -d -p 8000:8000 --name lsfx-mock lsfx-mock-server

# 或使用 Docker Compose
docker-compose up -d

架构设计

目录结构

lsfx-mock-server/
├── main.py                 # FastAPI 应用入口
├── config/
│   ├── settings.py         # 全局配置（通过环境变量覆盖）
│   └── responses/          # JSON 响应模板（token.json, upload.json 等）
├── models/
│   ├── request.py          # Pydantic 请求模型
│   └── response.py         # Pydantic 响应模型
├── services/               # 业务逻辑层（核心）
│   ├── token_service.py    # Token 管理和项目创建
│   ├── file_service.py     # 文件上传、解析状态、删除
│   └── statement_service.py # 银行流水查询和分页
├── routers/
│   └── api.py              # API 路由定义（7个接口）
└── utils/
    ├── error_simulator.py  # 错误场景检测和响应构建
    └── response_builder.py # 从 JSON 模板构建响应

核心组件交互

1. 请求流程:

   • routers/api.py 接收请求 → 检查错误标记 → 调用 Service → 返回响应

2. 文件上传流程:

   • FileService.upload_file() 生成 logId → 存储初始记录 → 启动后台任务
   • 后台任务: 延迟 4 秒 → 更新解析状态为完成
   • 客户端轮询 check_parse_status() 查看是否解析完成

3. 错误触发机制:

   • 在任意字符串参数中包含 error_XXXX（如 projectNo: "test_error_40101"）
   • ErrorSimulator.detect_error_marker() 检测标记
   • 返回预定义的错误响应（见 error_simulator.py ERROR_CODES）

服务类职责

• TokenService: 管理 projectId 和 token 映射关系（内存字典）
• FileService: 管理文件记录、解析状态、支持后台任务
  • fetch_inner_flow(): 返回随机 logId 数组（简化管理，不存储记录）
• StatementService: 从 JSON 模板读取流水数据并分页返回

开发指南

添加新接口

1. 在 models/request.py 和 models/response.py 中定义数据模型（如果需要）
2. 在 services/ 中实现业务逻辑方法
3. 在 routers/api.py 中添加路由处理函数
4. 在 config/responses/ 中添加 JSON 响应模板（可选）
5. 在 tests/ 中添加测试用例

修改响应数据

直接编辑 config/responses/ 下的 JSON 文件，重启服务即可生效。无需修改代码。

添加新的错误码

在 utils/error_simulator.py 的 ERROR_CODES 字典中添加新条目：

ERROR_CODES = {
    "40101": {"code": "40101", "message": "appId错误"},
    # 添加新的错误码...
}

配置管理

• 默认配置在 config/settings.py 中的 Settings 类
• 通过 .env 文件覆盖（参考 .env.example）
• 重要配置项：
  • PARSE_DELAY_SECONDS: 文件解析延迟秒数（默认 4）
  • INITIAL_PROJECT_ID: 项目ID起始值（默认 1000）
  • INITIAL_LOG_ID: 文件ID起始值（默认 10000）

测试说明

• 测试框架: pytest + httpx（FastAPI 测试客户端）
• 测试文件位于 tests/ 目录
• conftest.py 包含测试夹具（fixtures）
• 所有 API 端点都有对应的集成测试
• 测试覆盖了成功场景和错误场景（通过 error_XXXX 标记）

API 接口说明

7个核心接口：

1. /account/common/getToken (POST) - 创建项目并获取 Token
2. /watson/api/project/remoteUploadSplitFile (POST) - 上传流水文件（multipart/form-data）
3. /watson/api/project/getJZFileOrZjrcuFile (POST) - 拉取行内流水
4. /watson/api/project/upload/getpendings (POST) - 检查文件解析状态
5. /watson/api/project/bs/upload (GET) - 获取单个文件上传后的状态（独立接口，基于 logId 生成确定性数据）
6. /watson/api/project/batchDeleteUploadFile (POST) - 批量删除文件
7. /watson/api/project/getBSByLogId (POST) - 获取银行流水（分页）

详细接口文档请访问 Swagger UI (/docs) 或查看 assets/兰溪-流水分析对接3.md。

注意事项

• 数据持久化: 所有数据存储在内存中，服务重启后数据丢失
• 响应字段完整性: 所有接口响应字段完全对齐接口文档示例
• 并发安全: 当前实现未考虑多线程安全，生产环境需要加锁
• 文件存储: 上传的文件不实际保存，仅模拟元数据
• 错误标记: 错误触发通过字符串匹配实现，确保测试数据唯一性
• 后台任务: FastAPI BackgroundTasks 在同一进程内执行，不会阻塞响应
• 请求头处理: X-Xencio-Client-Id 请求头不验证，接受任意值
• 行内流水接口特殊性:
  • 简化管理：不存储到 file_records
  • 随机 logId：无需持久化，仅用于返回
  • 无后续操作：不支持解析状态检查、删除或查询流水
• 获取单个文件上传状态接口特殊性:
  • 完全独立工作：不依赖文件上传记录
  • 确定性数据生成：基于 logId 参数使用随机种子生成数据
  • 相同 logId 一致性：相同 logId 每次查询返回相同的核心字段值
  • 无 logId 场景：不带 logId 参数时返回空 logs 数组