Fundamental_Analysis/docs/frontend/backend_todos.md

后端改造需求清单 (配合前端重构)

日期: 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> 字段。

  #[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 字段的事件。