# 后端改造需求清单 (配合前端重构)
日期: 2025-11-22
状态: 待执行

为了支持新的 "Puppet Architecture" 前端设计，后端需要进行以下适配性改造。

## 1. API 规范与类型生成 (OpenAPI)

**目标**: 支持前端通过脚本自动从后端生成 TypeScript 类型定义 (Zod Schemas)，确保前后端类型严格一致，实现 "Single Source of Truth"。

*   **任务**: 在 `api-gateway` 中集成 `utoipa` 及 `utoipa-swagger-ui`。
*   **要求**:
    *   暴露 `GET /api-docs/openapi.json` 路由。
    *   确保所有核心 Struct (特别是 `WorkflowEvent`, `TaskStatus`, `LlmProvider`, `AnalysisTemplateSet`) 都在 Schema 中正确导出。
    *   对于 Enum 类型，确保导出为带 `type` 字段的 Discriminated Union 格式（如果可能），或者前端通过 generator 处理。

## 2. 动态数据源 Schema 接口

**目标**: 实现数据源的插件化和动态发现。前端不应硬编码支持哪些数据源，也不应知道每个数据源需要哪些配置字段。

*   **背景**: 未来数据源将作为微服务动态插拔。
*   **任务**: 新增接口 `GET /v1/configs/data_sources/schema`。
*   **响应结构示例**:
    ```json
    {
      "providers": [
        {
          "id": "tushare",
          "name": "Tushare Pro",
          "description": "Official Tushare Data Provider",
          "fields": [
            {
              "key": "api_token",
              "label": "API Token",
              "type": "password", // text, password, select, boolean
              "required": true,
              "placeholder": "Enter your token...",
              "description": "Get it from https://tushare.pro"
            },
            {
              "key": "api_url",
              "label": "API Endpoint",
              "type": "text",
              "default": "http://api.tushare.pro",
              "required": false
            }
          ]
        }
      ]
    }
    ```
*   **逻辑**: 该接口应聚合当前注册的所有 Data Provider 服务的配置元数据。

## 3. 任务进度 (Progress) 字段支持

**目标**: 支持在 UI 上展示细粒度的任务进度条 (0-100%)，而不仅仅是状态切换。

*   **背景**: Data Provider 抓取大量数据或 Deep Research 分析时，需要反馈进度。
*   **任务**:
    1.  **修改 Contract**: 在 `common-contracts` 的 `WorkflowEvent::TaskStateChanged` 中增加 `progress` 字段。
        ```rust
        pub struct TaskStateChanged {
            // ... existing fields
            pub progress: Option<u8>, // 0-100
        }
        ```
    2.  **Orchestrator 适配**: 在处理任务更新时，支持透传进度值。
    3.  **Provider 适配**: 长耗时任务（如 `fetch_history`）应定期发送带有进度的状态更新。
    4.  **兼容性**: 对于不支持进度的瞬时任务，开始时为 0，完成时为 100。

## 4. 确认项 (无需代码变更，仅作备忘)

*   **Logs 处理**: `TaskStateChanged` 中的 `message` 字段将被视为增量日志。前端收到事件时，会将非空的 `message` 追加 (Append) 到该任务的日志列表中。
*   **SSE 稳定性**: 确保 `workflow_events_stream` 在连接建立时立即发送 `WorkflowStateSnapshot` (已实现)，以处理前端重连场景。