# 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 数组