wkc/ccdi
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9aa7dd7a2ec42de534a8b33f4260855017818487
ccdi/lsfx-mock-server/docs/plans/2026-03-12-upload-status-api-implementation.md

469 lines
12 KiB
Markdown
Raw Normal View History

完善lsfx mock服务上传状态接口与部署文档
2026-03-13 16:38:07 +08:00
# 获取单个文件上传状态接口优化实施计划
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
**Goal:** 优化 `/watson/api/project/bs/upload` 接口，实现基于 logId 的确定性数据生成，不依赖上传记录。
**Architecture:** 使用 `random.seed(log_id)` 确保相同 logId 生成相同数据，完全独立于文件上传记录，符合 Mock 服务器定位。
**Tech Stack:** FastAPI, Python random/datetime, pytest
---
## Task 1: 修复 FileRecord 类的 log_meta 默认值
**Files:**
- Modify: `services/file_service.py:47`
**Step 1: 修改 log_meta 默认值**
在 `services/file_service.py` 第 47 行，将：
```python
log_meta: str = "{\"lostHeader\":[],\"balanceAmount\":true}"
```
改为：
```python
log_meta: str = "{\"lostHeader\":[],\"balanceAmount\":\"-1\"}"
```
**Step 2: 验证修改**
运行: `python -c "from services.file_service import FileRecord; r = FileRecord(log_id=1, group_id=1, file_name='test.csv'); print(r.log_meta)"`
预期输出:
```
{"lostHeader":[],"balanceAmount":"-1"}
```
**Step 3: 提交修复**
```bash
git add services/file_service.py
git commit -m "fix: 修复 FileRecord.log_meta 中 balanceAmount 值为字符串 '-1'"
```
---
## Task 2: 编写测试 - 带 logId 查询返回数据
**Files:**
- Modify: `tests/test_api.py`
**Step 1: 编写测试用例**
在 `tests/test_api.py` 文件末尾添加：
```python
def test_get_upload_status_with_log_id():
"""测试带 logId 参数查询返回非空 logs"""
response = client.get("/watson/api/project/bs/upload?groupId=1000&logId=13994")
assert response.status_code == 200
data = response.json()
# 验证基本响应结构
assert data["code"] == "200"
assert data["status"] == "200"
assert data["successResponse"] is True
# 验证 logs 不为空
assert len(data["data"]["logs"]) == 1
# 验证返回的 logId 正确
log = data["data"]["logs"][0]
assert log["logId"] == 13994
# 验证固定成功状态
assert log["status"] == -5
assert log["uploadStatusDesc"] == "data.wait.confirm.newaccount"
# 验证 logMeta 格式正确
assert log["logMeta"] == "{\"lostHeader\":[],\"balanceAmount\":\"-1\"}"
```
**Step 2: 运行测试验证失败**
运行: `pytest tests/test_api.py::test_get_upload_status_with_log_id -v`
预期: FAIL（因为还未实现）
**Step 3: 提交测试**
```bash
git add tests/test_api.py
git commit -m "test: 添加带 logId 查询的测试用例"
```
---
## Task 3: 编写测试 - 不带 logId 查询返回空数组
**Files:**
- Modify: `tests/test_api.py`
**Step 1: 编写测试用例**
在 `tests/test_api.py` 文件末尾添加：
```python
def test_get_upload_status_without_log_id():
"""测试不带 logId 参数查询返回空 logs 数组"""
response = client.get("/watson/api/project/bs/upload?groupId=1000")
assert response.status_code == 200
data = response.json()
# 验证基本响应结构
assert data["code"] == "200"
assert data["status"] == "200"
assert data["successResponse"] is True
# 验证 logs 为空
assert len(data["data"]["logs"]) == 0
# 验证其他字段存在
assert data["data"]["status"] == ""
assert data["data"]["accountId"] == 8954
assert data["data"]["currency"] == "CNY"
```
**Step 2: 运行测试验证失败**
运行: `pytest tests/test_api.py::test_get_upload_status_without_log_id -v`
预期: FAIL（因为还未实现）
**Step 3: 提交测试**
```bash
git add tests/test_api.py
git commit -m "test: 添加不带 logId 查询的测试用例"
```
---
## Task 4: 编写测试 - 确定性数据生成
**Files:**
- Modify: `tests/test_api.py`
**Step 1: 编写测试用例**
在 `tests/test_api.py` 文件末尾添加：
```python
def test_deterministic_data_generation():
"""测试相同 logId 多次查询返回相同的核心字段值"""
# 第一次查询
response1 = client.get("/watson/api/project/bs/upload?groupId=1000&logId=13994")
log1 = response1.json()["data"]["logs"][0]
# 第二次查询
response2 = client.get("/watson/api/project/bs/upload?groupId=1000&logId=13994")
log2 = response2.json()["data"]["logs"][0]
# 验证关键字段相同
assert log1["logId"] == log2["logId"]
assert log1["bankName"] == log2["bankName"]
assert log1["accountNoList"] == log2["accountNoList"]
assert log1["enterpriseNameList"] == log2["enterpriseNameList"]
assert log1["status"] == log2["status"]
assert log1["logMeta"] == log2["logMeta"]
assert log1["templateName"] == log2["templateName"]
assert log1["trxDateStartId"] == log2["trxDateStartId"]
assert log1["trxDateEndId"] == log2["trxDateEndId"]
def test_field_completeness():
"""测试返回数据包含完整的 26 个字段"""
response = client.get("/watson/api/project/bs/upload?groupId=1000&logId=13994")
log = response.json()["data"]["logs"][0]
# 验证所有必需字段存在
required_fields = [
"accountNoList", "bankName", "dataTypeInfo", "downloadFileName",
"enterpriseNameList", "fileSize", "fileUploadBy", "fileUploadByUserName",
"fileUploadTime", "isSplit", "leId", "logId", "logMeta", "logType",
"loginLeId", "lostHeader", "realBankName", "rows", "source", "status",
"templateName", "totalRecords", "trxDateEndId", "trxDateStartId",
"uploadFileName", "uploadStatusDesc"
]
for field in required_fields:
assert field in log, f"缺少字段: {field}"
```
**Step 2: 运行测试验证失败**
运行: `pytest tests/test_api.py::test_deterministic_data_generation tests/test_api.py::test_field_completeness -v`
预期: FAIL（因为还未实现）
**Step 3: 提交测试**
```bash
git add tests/test_api.py
git commit -m "test: 添加确定性和字段完整性测试用例"
```
---
## Task 5: 实现 _generate_deterministic_record() 方法
**Files:**
- Modify: `services/file_service.py`
**Step 1: 在 FileService 类中添加新方法**
在 `services/file_service.py` 的 `FileService` 类中，在 `_delayed_parse` 方法之后（约第 200 行）添加：
```python
def _generate_deterministic_record(self, log_id: int, group_id: int) -> dict:
"""
基于 logId 生成确定性的文件记录
Args:
log_id: 文件ID（用作随机种子）
group_id: 项目ID
Returns:
文件记录字典（26个字段）
"""
# 银行类型选项
bank_options = [
("ALIPAY", "ALIPAY_T220708"),
("BSX", "BSX_T240925"),
("ZJRCU", "ZJRCU_T251114")
]
bank_name, template_name = random.choice(bank_options)
# 生成交易日期范围
end_date = datetime.now()
start_date = end_date - timedelta(days=random.randint(90, 365))
# 生成账号和主体
account_no = f"{random.randint(10000000000, 99999999999)}"
enterprise_names = ["测试主体"] if random.random() > 0.3 else [""]
return {
"accountNoList": [account_no],
"bankName": bank_name,
"dataTypeInfo": ["CSV", ","],
"downloadFileName": f"测试文件_{log_id}.csv",
"enterpriseNameList": enterprise_names,
"fileSize": random.randint(10000, 100000),
"fileUploadBy": 448,
"fileUploadByUserName": "admin@support.com",
"fileUploadTime": datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
"isSplit": 0,
"leId": 10000 + random.randint(0, 9999),
"logId": log_id,
"logMeta": "{\"lostHeader\":[],\"balanceAmount\":\"-1\"}",
"logType": "bankstatement",
"loginLeId": 10000 + random.randint(0, 9999),
"lostHeader": [],
"realBankName": bank_name,
"rows": 0,
"source": "http",
"status": -5,
"templateName": template_name,
"totalRecords": random.randint(100, 300),
"trxDateEndId": int(end_date.strftime("%Y%m%d")),
"trxDateStartId": int(start_date.strftime("%Y%m%d")),
"uploadFileName": f"测试文件_{log_id}.pdf",
"uploadStatusDesc": "data.wait.confirm.newaccount"
}
```
**Step 2: 验证语法正确**
运行: `python -m py_compile services/file_service.py`
预期: 无输出（表示语法正确）
**Step 3: 提交代码**
```bash
git add services/file_service.py
git commit -m "feat: 添加 _generate_deterministic_record 方法"
```
---
## Task 6: 重构 get_upload_status() 方法
**Files:**
- Modify: `services/file_service.py:265-300`
**Step 1: 替换整个 get_upload_status() 方法**
在 `services/file_service.py` 中，找到 `get_upload_status` 方法（约第 265-300 行），完全替换为：
```python
def get_upload_status(self, group_id: int, log_id: int = None) -> dict:
"""
获取文件上传状态（基于 logId 生成确定性数据）
Args:
group_id: 项目ID
log_id: 文件ID（可选）
Returns:
上传状态响应字典
"""
logs = []
if log_id:
# 使用 logId 作为随机种子，确保相同 logId 返回相同数据
random.seed(log_id)
# 生成确定性的文件记录
record = self._generate_deterministic_record(log_id, group_id)
logs.append(record)
# 返回响应
return {
"code": "200",
"data": {
"logs": logs,
"status": "",
"accountId": 8954,
"currency": "CNY"
},
"status": "200",
"successResponse": True
}
```
**Step 2: 验证语法正确**
运行: `python -m py_compile services/file_service.py`
预期: 无输出（表示语法正确）
**Step 3: 提交重构**
```bash
git add services/file_service.py
git commit -m "refactor: 重构 get_upload_status 方法实现独立数据生成"
```
---
## Task 7: 运行所有测试验证功能
**Files:**
- Test: `tests/test_api.py`
**Step 1: 运行新增的测试用例**
运行: `pytest tests/test_api.py::test_get_upload_status_with_log_id tests/test_api.py::test_get_upload_status_without_log_id tests/test_api.py::test_deterministic_data_generation tests/test_api.py::test_field_completeness -v`
预期: 所有测试 PASS
**Step 2: 运行完整的测试套件**
运行: `pytest tests/ -v`
预期: 所有测试 PASS（确保没有破坏其他功能）
**Step 3: 手动测试接口**
运行: `python main.py`（在后台启动服务器）
在另一个终端运行:
```bash
curl "http://localhost:8000/watson/api/project/bs/upload?groupId=1000&logId=13994"
```
预期: 返回包含 logId=13994 的 JSON 数据
**Step 4: 提交验证记录**
```bash
git add tests/
git commit -m "test: 验证所有测试通过"
```
---
## Task 8: 更新文档并提交
**Files:**
- Modify: `CLAUDE.md`（可选）
**Step 1: 检查是否需要更新 CLAUDE.md**
查看项目根目录的 `CLAUDE.md` 文件，确认是否需要添加关于接口独立性的说明。如果需要，在适当位置添加：
```markdown
### 接口说明
**获取单个文件上传状态接口 (`/watson/api/project/bs/upload`)**：
- 此接口完全独立工作，不依赖文件上传记录
- 基于 logId 参数生成确定性的随机数据
- 相同 logId 每次查询返回相同的核心字段值
```
**Step 2: 提交文档更新（如果有）**
```bash
git add CLAUDE.md
git commit -m "docs: 更新接口独立性说明"
```
**Step 3: 最终提交**
确保所有修改已提交：
```bash
git status
```
预期: 工作目录干净
---
## 验收清单
实施完成后，确认以下验收标准：
### 功能验收
- [x] 带 logId 参数查询返回非空 logs 数组
- [x] 不带 logId 参数查询返回空 logs 数组
- [x] 相同 logId 多次查询返回相同的核心字段值
- [x] 返回数据包含完整的 26 个字段
- [x] status 字段值为 -5
- [x] logMeta 字段中 balanceAmount 为字符串 "-1"
### 质量验收
- [x] 所有单元测试通过
- [x] 代码符合项目编码规范
- [x] 无语法错误和运行时错误
- [x] API 文档（Swagger UI）正确展示接口
### 文档验收
- [x] 代码注释完整清晰
- [x] 测试用例覆盖所有场景
---
## 实施说明
1. **TDD 流程**: 严格遵循"先写测试 → 运行失败 → 写代码 → 运行通过 → 提交"的流程
2. **频繁提交**: 每个小的步骤都有独立的提交，便于回滚和追踪
3. **独立性**: 此修改不影响其他接口（上传、解析状态检查等）
4. **确定性**: 使用 `random.seed(log_id)` 确保相同 logId 生成相同数据
5. **简单高效**: 代码简洁，无过度设计，符合 YAGNI 原则
---
## 参考资料
- 设计文档: `docs/plans/2026-03-12-upload-status-api-design.md`
- 接口文档: `assets/兰溪-流水分析对接3.md` 第374-516行
- 当前实现: `services/file_service.py` 第265-300行
Reference in New Issue Copy Permalink