完善lsfx mock服务上传状态接口与部署文档

2026-03-13 16:38:07 +08:00
parent bda89202ba
commit 109b5220b2
29 changed files with 4489 additions and 67 deletions
--- a/lsfx-mock-server/docs/plans/2026-03-04-inner-flow-response.md
+++ b/lsfx-mock-server/docs/plans/2026-03-04-inner-flow-response.md
@@ -0,0 +1,432 @@
+# 修改拉取行内流水接口返回值 - 实施计划
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** 修改拉取行内流水接口的返回格式，从错误格式改为返回随机 logId 数组
+
+**Architecture:** 修改 `FileService.fetch_inner_flow()` 方法，使用随机数生成 logId（10000-99999），返回包含 logId 数组的成功响应，保留错误模拟功能
+
+**Tech Stack:** Python 3.11, FastAPI, pytest
+
+---
+
+## Task 1: 添加测试夹具
+
+**Files:**
+- Modify: `tests/conftest.py:35-35` (在文件末尾添加)
+
+**Step 1: 添加测试夹具**
+
+在 `tests/conftest.py` 文件末尾添加：
+
+```python
+
+@pytest.fixture
+def sample_inner_flow_request():
+    """示例拉取行内流水请求"""
+    return {
+        "groupId": 1001,
+        "customerNo": "test_customer_001",
+        "dataChannelCode": "test_code",
+        "requestDateId": 20240101,
+        "dataStartDateId": 20240101,
+        "dataEndDateId": 20240131,
+        "uploadUserId": 902001,
+    }
+```
+
+**Step 2: 验证夹具定义正确**
+
+运行: `python -c "from tests.conftest import sample_inner_flow_request; print('OK')"`
+预期输出: `OK`
+
+**Step 3: 提交**
+
+```bash
+git add tests/conftest.py
+git commit -m "test: add sample_inner_flow_request fixture"
+```
+
+---
+
+## Task 2: 编写成功场景的失败测试
+
+**Files:**
+- Modify: `tests/test_api.py` (在文件末尾添加)
+
+**Step 1: 编写测试用例**
+
+在 `tests/test_api.py` 文件末尾添加：
+
+```python
+
+
+def test_fetch_inner_flow_success(client, sample_inner_flow_request):
+    """测试拉取行内流水 - 成功场景"""
+    response = client.post(
+        "/watson/api/project/getJZFileOrZjrcuFile",
+        data=sample_inner_flow_request
+    )
+    assert response.status_code == 200
+    data = response.json()
+    assert data["code"] == "200"
+    assert data["successResponse"] == True
+    assert isinstance(data["data"], list)
+    assert len(data["data"]) == 1
+    assert isinstance(data["data"][0], int)
+    assert 10000 <= data["data"][0] <= 99999
+```
+
+**Step 2: 运行测试验证失败**
+
+运行: `pytest tests/test_api.py::test_fetch_inner_flow_success -v`
+
+预期输出:
+```
+FAILED - assert data["successResponse"] == True
+```
+
+**Step 3: 暂不提交（等待实现）**
+
+---
+
+## Task 3: 实现 fetch_inner_flow 方法修改
+
+**Files:**
+- Modify: `services/file_service.py:135-150` (修改 `fetch_inner_flow` 方法)
+
+**Step 1: 读取当前实现**
+
+运行: `grep -n "def fetch_inner_flow" services/file_service.py`
+
+预期输出: `135:    def fetch_inner_flow(self, request: Union[Dict, object]) -> Dict:`
+
+**Step 2: 修改方法实现**
+
+将 `services/file_service.py` 中的 `fetch_inner_flow` 方法替换为：
+
+```python
+    def fetch_inner_flow(self, request: Union[Dict, object]) -> Dict:
+        """拉取行内流水（返回随机logId）
+
+        Args:
+            request: 拉取流水请求（可以是字典或对象）
+
+        Returns:
+            流水响应字典，包含随机生成的logId数组
+        """
+        import random
+
+        # 随机生成一个logId（范围：10000-99999）
+        log_id = random.randint(10000, 99999)
+
+        # 返回成功的响应，包含logId数组
+        return {
+            "code": "200",
+            "data": [log_id],
+            "status": "200",
+            "successResponse": True,
+        }
+```
+
+**Step 3: 运行测试验证通过**
+
+运行: `pytest tests/test_api.py::test_fetch_inner_flow_success -v`
+
+预期输出:
+```
+PASSED
+```
+
+**Step 4: 提交实现**
+
+```bash
+git add services/file_service.py tests/test_api.py
+git commit -m "feat: modify fetch_inner_flow to return random logId array"
+```
+
+---
+
+## Task 4: 编写错误场景测试
+
+**Files:**
+- Modify: `tests/test_api.py` (在 test_fetch_inner_flow_success 后添加)
+
+**Step 1: 编写错误场景测试**
+
+在 `tests/test_api.py` 的 `test_fetch_inner_flow_success` 后添加：
+
+```python
+
+
+def test_fetch_inner_flow_error_501014(client):
+    """测试拉取行内流水 - 错误场景 501014"""
+    request_data = {
+        "groupId": 1001,
+        "customerNo": "test_error_501014",
+        "dataChannelCode": "test_code",
+        "requestDateId": 20240101,
+        "dataStartDateId": 20240101,
+        "dataEndDateId": 20240131,
+        "uploadUserId": 902001,
+    }
+    response = client.post(
+        "/watson/api/project/getJZFileOrZjrcuFile",
+        data=request_data
+    )
+    assert response.status_code == 200
+    data = response.json()
+    assert data["code"] == "501014"
+    assert data["successResponse"] == False
+```
+
+**Step 2: 运行错误场景测试**
+
+运行: `pytest tests/test_api.py::test_fetch_inner_flow_error_501014 -v`
+
+预期输出:
+```
+PASSED
+```
+
+**Step 3: 提交测试**
+
+```bash
+git add tests/test_api.py
+git commit -m "test: add error scenario test for fetch_inner_flow"
+```
+
+---
+
+## Task 5: 运行完整测试套件
+
+**Files:**
+- 无文件修改
+
+**Step 1: 运行所有 fetch_inner_flow 相关测试**
+
+运行: `pytest tests/test_api.py -k "fetch_inner_flow" -v`
+
+预期输出:
+```
+test_fetch_inner_flow_success PASSED
+test_fetch_inner_flow_error_501014 PASSED
+```
+
+**Step 2: 运行完整测试套件确保无破坏**
+
+运行: `pytest tests/ -v`
+
+预期输出:
+```
+所有测试 PASSED
+```
+
+**Step 3: 无需提交**
+
+---
+
+## Task 6: 更新 README.md 文档
+
+**Files:**
+- Modify: `README.md` (更新行内流水接口说明)
+
+**Step 1: 找到接口说明位置**
+
+运行: `grep -n "拉取行内流水" README.md`
+
+预期输出: 找到行内流水接口的说明位置
+
+**Step 2: 更新接口说明**
+
+在 README.md 中找到行内流水接口的说明，将"模拟无数据场景"相关描述改为：
+
+```markdown
+### 3. 拉取行内流水
+
+返回随机生成的 logId 数组（范围：10000-99999），支持通过 `error_XXXX` 标记触发错误场景。
+```
+
+同时更新成功响应示例（如果有的话）：
+
+```json
+{
+    "code": "200",
+    "data": [19154],
+    "status": "200",
+    "successResponse": true
+}
+```
+
+**Step 3: 验证文档更新**
+
+运行: `grep -A 5 "拉取行内流水" README.md`
+
+预期输出: 显示更新后的说明
+
+**Step 4: 提交文档更新**
+
+```bash
+git add README.md
+git commit -m "docs: update fetch_inner_flow interface description"
+```
+
+---
+
+## Task 7: 更新 CLAUDE.md 文档
+
+**Files:**
+- Modify: `CLAUDE.md` (补充行内流水接口说明)
+
+**Step 1: 找到架构设计部分**
+
+运行: `grep -n "### 服务类职责" CLAUDE.md`
+
+预期输出: 找到服务类职责说明的位置
+
+**Step 2: 更新服务类职责说明**
+
+在 `CLAUDE.md` 的"服务类职责"部分，找到 `FileService` 的说明，补充：
+
+```markdown
+- **FileService**: 管理文件记录、解析状态、支持后台任务
+  - `fetch_inner_flow()`: 返回随机 logId 数组（简化管理，不存储记录）
+```
+
+**Step 3: 添加行内流水接口特殊性说明**
+
+在合适的位置（如"注意事项"部分）添加：
+
+```markdown
+- **行内流水接口特殊性**:
+  - 简化管理：不存储到 file_records
+  - 随机 logId：无需持久化，仅用于返回
+  - 无后续操作：不支持解析状态检查、删除或查询流水
+```
+
+**Step 4: 提交文档更新**
+
+```bash
+git add CLAUDE.md
+git commit -m "docs: update CLAUDE.md with inner flow interface details"
+```
+
+---
+
+## Task 8: 验证 Swagger UI 文档
+
+**Files:**
+- 无文件修改
+
+**Step 1: 启动服务器**
+
+运行: `python main.py` （后台运行或新终端）
+
+预期输出:
+```
+INFO:     Uvicorn running on http://0.0.0.0:8000
+```
+
+**Step 2: 访问 Swagger UI**
+
+打开浏览器访问: `http://localhost:8000/docs`
+
+预期: 看到 `/watson/api/project/getJZFileOrZjrcuFile` 接口
+
+**Step 3: 测试接口**
+
+在 Swagger UI 中:
+1. 点击 `/watson/api/project/getJZFileOrZjrcuFile` 接口
+2. 点击 "Try it out"
+3. 填写测试数据:
+   - groupId: 1001
+   - customerNo: test_customer
+   - dataChannelCode: test_code
+   - requestDateId: 20240101
+   - dataStartDateId: 20240101
+   - dataEndDateId: 20240131
+   - uploadUserId: 902001
+4. 点击 "Execute"
+5. 查看响应
+
+预期响应:
+```json
+{
+  "code": "200",
+  "data": [12345],
+  "status": "200",
+  "successResponse": true
+}
+```
+
+**Step 4: 停止服务器**
+
+运行: `Ctrl+C` 或关闭终端
+
+**Step 5: 无需提交**
+
+---
+
+## Task 9: 最终验收
+
+**Files:**
+- 无文件修改
+
+**Step 1: 运行完整测试套件**
+
+运行: `pytest tests/ -v --cov=. --cov-report=term`
+
+预期输出:
+```
+所有测试 PASSED
+覆盖率报告显示 file_service.py 覆盖率提升
+```
+
+**Step 2: 验证验收标准**
+
+检查以下验收标准是否全部满足：
+
+- [x] 修改后接口返回正确的格式（包含 logId 数组）
+- [x] logId 在指定范围内（10000-99999）
+- [x] 错误模拟功能正常工作
+- [x] 所有测试用例通过
+- [x] 文档已更新
+- [x] 代码通过 pytest 测试
+
+**Step 3: 查看提交历史**
+
+运行: `git log --oneline -5`
+
+预期输出:
+```
+docs: update CLAUDE.md with inner flow interface details
+docs: update fetch_inner_flow interface description
+test: add error scenario test for fetch_inner_flow
+feat: modify fetch_inner_flow to return random logId array
+test: add sample_inner_flow_request fixture
+```
+
+**Step 4: 完成**
+
+实施完成！代码已通过所有测试，文档已更新。
+
+---
+
+## 总结
+
+**修改文件：**
+- `tests/conftest.py` - 添加测试夹具
+- `tests/test_api.py` - 添加 2 个测试用例
+- `services/file_service.py` - 修改 1 个方法
+- `README.md` - 更新接口说明
+- `CLAUDE.md` - 补充架构说明
+
+**测试用例：**
+- `test_fetch_inner_flow_success` - 验证成功场景
+- `test_fetch_inner_flow_error_501014` - 验证错误场景
+
+**提交记录：**
+- 5 个清晰的提交，遵循原子提交原则
+- 提交信息符合约定式提交规范
+
+**实施时间：** 约 30 分钟