ccdi/lsfx-mock-server/docs/plans/2026-03-04-inner-flow-response.md

修改拉取行内流水接口返回值 - 实施计划

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 文件末尾添加：

@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: 提交

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 文件末尾添加：

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 方法替换为：

    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: 提交实现

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 后添加：

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: 提交测试

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 中找到行内流水接口的说明，将"模拟无数据场景"相关描述改为：

### 3. 拉取行内流水

返回随机生成的 logId 数组（范围：10000-99999），支持通过 `error_XXXX` 标记触发错误场景。

同时更新成功响应示例（如果有的话）：

{
    "code": "200",
    "data": [19154],
    "status": "200",
    "successResponse": true
}

Step 3: 验证文档更新

运行: grep -A 5 "拉取行内流水" README.md

预期输出: 显示更新后的说明

Step 4: 提交文档更新

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 的说明，补充：

- **FileService**: 管理文件记录、解析状态、支持后台任务
  - `fetch_inner_flow()`: 返回随机 logId 数组（简化管理，不存储记录）

Step 3: 添加行内流水接口特殊性说明

在合适的位置（如"注意事项"部分）添加：

- **行内流水接口特殊性**:
  - 简化管理：不存储到 file_records
  - 随机 logId：无需持久化，仅用于返回
  - 无后续操作：不支持解析状态检查、删除或查询流水

Step 4: 提交文档更新

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. 查看响应

预期响应:

{
  "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: 验证验收标准

检查以下验收标准是否全部满足：

• 修改后接口返回正确的格式（包含 logId 数组）
• logId 在指定范围内（10000-99999）
• 错误模拟功能正常工作
• 所有测试用例通过
• 文档已更新
• 代码通过 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 分钟