# 后端改造需求清单 (配合前端重构)
日期: 2025-11-22
状态: **已完成**

为了支持新的 "Puppet Architecture" 前端设计，后端已完成以下适配性改造。

## 1. API 规范与类型生成 (Service Kit 集成) - [已完成]

**目标**: 利用项目现有的 `service_kit` 库，实现前端通过脚本自动从后端生成 TypeScript 类型定义 (Zod Schemas)，确保前后端类型严格一致。

**实施情况**:
*   **Contract 层改造**:
    *   在 `common-contracts` 中，核心 Struct/Enum (如 `WorkflowEvent`, `TaskStatus`) 已全面使用 `#[api_dto]` 宏标注。
    *   `#[api_dto]` 自动注入了 `utoipa::ToSchema`，确保了 Schema 的正确导出。

*   **API Gateway 改造 (混合模式)**:
    *   引入了 `utoipa` 和 `utoipa-swagger-ui` 依赖。
    *   创建了 `services/api-gateway/src/openapi/mod.rs`，定义了 `ApiDoc` 结构体。
    *   在 `services/api-gateway/src/api.rs` 中，手动为 Handler 添加了 `#[utoipa::path(...)]` 标注。
    *   在 Router 中挂载了 `/swagger-ui` 和 `/api-docs/openapi.json`。

## 2. 动态数据源 Schema 接口 - [已完成]

**目标**: 实现数据源的插件化和动态发现。

**实施情况**:
*   在 `api-gateway` 中新增了接口 `GET /v1/configs/data_sources/schema`。
*   定义了 `DataSourceSchemaResponse` 和 `DataSourceProviderSchema` DTOs。
*   接口返回了 Tushare, Finnhub, AlphaVantage, Yfinance 的配置 Schema。

## 3. 任务进度 (Progress) 字段支持 - [已完成]

**目标**: 支持在 UI 上展示细粒度的任务进度条。

**实施情况**:
*   **修改 Contract**: 在 `common-contracts` 的 `WorkflowEvent::TaskStateChanged` 中增加了 `progress: Option<u8>` 字段。
    ```rust
    #[api_dto]
    pub struct TaskStateChanged {
        // ... existing fields
        pub progress: Option<u8>, // 0-100
    }
    ```

## 4. 下一步计划

*   **前端对接**: 前端可以尝试访问 `http://localhost:4000/api-docs/openapi.json` 来生成类型定义。
*   **集成测试**: 验证 `GET /v1/workflow/events/:id` 是否能正确返回带有 `progress` 字段的事件。