diff --git a/lsfx-mock-server/CLAUDE.md b/lsfx-mock-server/CLAUDE.md new file mode 100644 index 0000000..4363d4a --- /dev/null +++ b/lsfx-mock-server/CLAUDE.md @@ -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 数组 diff --git a/ruoyi-admin/src/main/resources/application-dev.yml b/ruoyi-admin/src/main/resources/application-dev.yml index 0d52e75..5a92757 100644 --- a/ruoyi-admin/src/main/resources/application-dev.yml +++ b/ruoyi-admin/src/main/resources/application-dev.yml @@ -111,7 +111,8 @@ spring: lsfx: api: # 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 # 生产环境