# 设计文档：修改拉取行内流水接口返回值

**日期：** 2026-03-04
**状态：** 已批准
**作者：** Claude Code

## 1. 概述和目标

### 目标
修改 `/watson/api/project/getJZFileOrZjrcuFile` 接口的返回格式，从当前的错误格式改为返回 logId 数组。

### 当前实现
```json
{
    "code": "200",
    "data": {"code": "501014", "message": "无行内流水文件"},
    "status": "200",
    "successResponse": true
}
```

### 修改后实现

**成功场景：**
```json
{
    "code": "200",
    "data": [19154],
    "status": "200",
    "successResponse": true
}
```

**错误场景（通过 `error_501014` 标记触发）：**
```json
{
    "code": "501014",
    "message": "无行内流水文件",
    "status": "501014",
    "successResponse": false
}
```

### 关键特性
- logId 通过随机数生成（范围：10000-99999）
- 独立简化管理，不存储到 `file_records`，不支持后续操作
- 保留错误模拟功能（通过 `error_XXXX` 标记触发）

## 2. 技术实现

### 修改文件
- `services/file_service.py` - 修改 `fetch_inner_flow()` 方法

### 具体实现

在 `FileService` 类中修改 `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,
    }
```

### 关键变化
1. 移除原来的"无行内流水文件"硬编码错误响应
2. 使用 `random.randint(10000, 99999)` 生成随机 logId
3. 返回格式改为 `{"code": "200", "data": [log_id], ...}`
4. `import random` 放在方法内部，避免顶层导入（保持简单）

### 无需修改的部分
- `routers/api.py` - 错误检测逻辑保持不变
- `utils/error_simulator.py` - 错误码定义已包含 501014
- `config/settings.py` - 无需新增配置

## 3. 测试计划

### 测试文件
- `tests/test_api.py`

### 新增测试用例

#### 3.1 测试成功场景
```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
```

#### 3.2 测试错误场景
```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
```

### 测试命令
```bash
# 运行所有行内流水相关测试
pytest tests/test_api.py -k "fetch_inner_flow" -v

# 运行单个测试
pytest tests/test_api.py::test_fetch_inner_flow_success -v
pytest tests/test_api.py::test_fetch_inner_flow_error_501014 -v
```

## 4. 文档更新

### 4.1 README.md
更新接口说明部分，将"模拟无数据场景"改为"返回随机logId"。

### 4.2 CLAUDE.md
在架构设计部分补充说明行内流水接口的特殊性：
- 简化管理（不存储到 file_records）
- 随机 logId（无需持久化）
- 无后续操作支持（无需解析状态检查）

## 5. 设计决策

### 为什么选择随机生成 logId？
- **简化管理**：行内流水拉取是独立的简化流程，不需要与文件上传共用复杂的状态管理
- **无需持久化**：logId 仅用于返回，不需要存储或后续查询
- **测试友好**：每次调用返回不同的值，避免固定值导致的测试假阳性

### 为什么不使用配置文件？
- 响应数据需要运行时动态生成（随机 logId）
- 配置文件适合静态或模板化的响应，不适合需要随机值的场景
- 保持代码简单直接，避免过度设计

### 为什么保留错误模拟？
- Mock 服务器的核心功能之一是模拟各种场景
- 501014 错误是真实的业务场景（无行内流水文件）
- 通过 `error_XXXX` 标记触发错误，与项目整体设计一致

## 6. 影响范围

### 直接影响
- `services/file_service.py` - 修改 1 个方法
- `tests/test_api.py` - 新增/修改测试用例

### 间接影响
- API 文档自动更新（FastAPI Swagger UI）
- README.md 需要更新示例

### 无影响
- 其他 6 个接口的返回格式
- 错误模拟机制
- 前端集成（假设前端已按新格式设计）

## 7. 风险和限制

### 风险
- **logId 冲突**：理论上可能生成重复的 logId，但由于不存储，不会造成实际问题
- **前端兼容性**：如果前端已按旧格式实现，需要协调更新

### 限制
- 不支持后续的解析状态检查
- 不支持通过 logId 查询流水数据
- 不支持删除操作

这些限制是设计决策的一部分，符合"简化管理"的目标。

## 8. 验收标准

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

## 9. 时间线

预计实施时间：30 分钟
- 代码修改：10 分钟
- 测试编写和验证：15 分钟
- 文档更新：5 分钟