Update lsfx mock base url
This commit is contained in:
172
lsfx-mock-server/CLAUDE.md
Normal file
172
lsfx-mock-server/CLAUDE.md
Normal file
@@ -0,0 +1,172 @@
|
|||||||
|
# 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 数组
|
||||||
@@ -111,7 +111,8 @@ spring:
|
|||||||
lsfx:
|
lsfx:
|
||||||
api:
|
api:
|
||||||
# Mock Server(本地测试)
|
# Mock Server(本地测试)
|
||||||
base-url: http://localhost:8000
|
# base-url: http://localhost:8000
|
||||||
|
base-url: http://116.62.17.81:62320
|
||||||
# 测试环境
|
# 测试环境
|
||||||
# base-url: http://158.234.196.5:82/c4c3
|
# base-url: http://158.234.196.5:82/c4c3
|
||||||
# 生产环境
|
# 生产环境
|
||||||
|
|||||||
Reference in New Issue
Block a user