173 lines
6.3 KiB
Markdown
173 lines
6.3 KiB
Markdown
# 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 秒解析延迟
|
||
|
||
## 常用命令
|
||
|
||
### 开发运行
|
||
```bash
|
||
# 安装依赖
|
||
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
|
||
```
|
||
|
||
### 测试
|
||
```bash
|
||
# 运行所有测试
|
||
pytest tests/ -v
|
||
|
||
# 运行单个测试文件
|
||
pytest tests/test_api.py -v
|
||
|
||
# 生成覆盖率报告
|
||
pytest tests/ -v --cov=. --cov-report=html
|
||
```
|
||
|
||
### Docker 部署
|
||
```bash
|
||
# 构建镜像
|
||
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` 字典中添加新条目：
|
||
```python
|
||
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 数组
|