ccdi/lsfx-mock-server/README.md

流水分析 Mock 服务器

基于 Python + FastAPI 的独立 Mock 服务器，用于模拟流水分析平台的 7 个核心接口。

✨ 特性

• ✅ 完整的接口模拟 - 实现所有 7 个核心接口
• ✅ 文件解析延迟 - 使用 FastAPI 后台任务模拟 4 秒解析延迟
• ✅ 错误场景触发 - 通过 error_XXXX 标记触发所有 8 个错误码
• ✅ 自动 API 文档 - Swagger UI 和 ReDoc 自动生成
• ✅ 配置驱动 - JSON 模板文件，易于修改响应数据
• ✅ 零配置启动 - 开箱即用，无需数据库

🚀 快速开始

1. 安装依赖

pip install -r requirements.txt

2. 启动服务

python main.py

或使用 uvicorn（支持热重载）：

uvicorn main:app --reload --host 0.0.0.0 --port 8000

3. 访问 API 文档

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

📖 使用示例

正常流程

import requests

# 1. 获取 Token
response = requests.post(
    "http://localhost:8000/account/common/getToken",
    json={
        "projectNo": "test_project_001",
        "entityName": "测试企业",
        "userId": "902001",
        "userName": "902001",
        "appId": "remote_app",
        "appSecretCode": "test_secret_code_12345",
        "role": "VIEWER",
        "orgCode": "902000",
        "departmentCode": "902000"
    }
)
token_data = response.json()
project_id = token_data["data"]["projectId"]

# 2. 上传文件
files = {"file": ("test.csv", open("test.csv", "rb"), "text/csv")}
response = requests.post(
    "http://localhost:8000/watson/api/project/remoteUploadSplitFile",
    files=files,
    data={"groupId": project_id}
)
log_id = response.json()["data"]["uploadLogList"][0]["logId"]

# 3. 轮询检查解析状态
import time
for i in range(10):
    response = requests.post(
        "http://localhost:8000/watson/api/project/upload/getpendings",
        json={"groupId": project_id, "inprogressList": str(log_id)}
    )
    result = response.json()
    if not result["data"]["parsing"]:
        print("解析完成")
        break
    time.sleep(1)

# 4. 获取银行流水
response = requests.post(
    "http://localhost:8000/watson/api/project/getBSByLogId",
    json={
        "groupId": project_id,
        "logId": log_id,
        "pageNow": 1,
        "pageSize": 10
    }
)

错误场景测试

# 触发 40101 错误（appId错误）
response = requests.post(
    "http://localhost:8000/account/common/getToken",
    json={
        "projectNo": "test_error_40101",  # 包含错误标记
        "entityName": "测试企业",
        "userId": "902001",
        "userName": "902001",
        "appId": "remote_app",
        "appSecretCode": "test_secret_code_12345",
        "role": "VIEWER",
        "orgCode": "902000",
        "departmentCode": "902000"
    }
)
# 返回: {"code": "40101", "message": "appId错误", ...}

🔧 配置说明

环境变量

创建 .env 文件（参考 .env.example）：

# 应用配置
APP_NAME=流水分析Mock服务
APP_VERSION=1.0.0
DEBUG=true

# 服务器配置
HOST=0.0.0.0
PORT=8000

# 模拟配置
PARSE_DELAY_SECONDS=4
MAX_FILE_SIZE=10485760

响应模板

修改 config/responses/ 下的 JSON 文件可以自定义响应数据：

• token.json - Token 响应模板
• upload.json - 上传文件响应模板
• parse_status.json - 解析状态响应模板
• bank_statement.json - 银行流水响应模板

🐳 Docker 部署

使用 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                 # 应用入口
├── config/
│   ├── settings.py         # 全局配置
│   └── responses/          # 响应模板
├── models/
│   ├── request.py          # 请求模型
│   └── response.py         # 响应模型
├── services/
│   ├── token_service.py    # Token 管理
│   ├── file_service.py     # 文件上传和解析
│   └── statement_service.py # 流水数据管理
├── routers/
│   └── api.py              # API 路由
├── utils/
│   ├── error_simulator.py  # 错误模拟
│   └── response_builder.py # 响应构建器
└── tests/                 # 测试套件

🧪 运行测试

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

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

🔌 API 接口列表

接口	方法	路径	描述
1	POST	/account/common/getToken	获取 Token
2	POST	/watson/api/project/remoteUploadSplitFile	上传文件
3	POST	/watson/api/project/getJZFileOrZjrcuFile	拉取行内流水
4	POST	/watson/api/project/upload/getpendings	检查解析状态
5	POST	/watson/api/project/batchDeleteUploadFile	删除文件
6	POST	/watson/api/project/getBSByLogId	获取银行流水

⚠️ 错误码列表

错误码	描述
40101	appId错误
40102	appSecretCode错误
40104	可使用项目次数为0，无法创建项目
40105	只读模式下无法新建项目
40106	错误的分析类型，不在规定的取值范围内
40107	当前系统不支持的分析类型
40108	当前用户所属行社无权限
501014	无行内流水文件

🛠️ 开发指南

添加新接口

1. 在 models/request.py 和 models/response.py 中添加模型
2. 在 services/ 中添加服务类
3. 在 routers/api.py 中添加路由
4. 在 config/responses/ 中添加响应模板
5. 编写测试

修改响应数据

直接编辑 config/responses/ 下的 JSON 文件，重启服务即可生效。

📝 License

MIT

🤝 Contributing

欢迎提交 Issue 和 Pull Request！