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

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

@@ -0,0 +1,221 @@
+# 设计文档：修改拉取行内流水接口返回值
+
+**日期：** 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 分钟