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

```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 分钟