70b1a27978
- contracts: Add #[api_dto] macros to core structs for OpenAPI support - api-gateway: Integrate utoipa for Swagger UI and OpenAPI spec generation - config: Implement dynamic configuration APIs for DataSources and LLM Providers - tests: Refactor E2E tests to support dynamic provider configuration and fix timeouts - docs: Update backend status in backend_todos.md
49 lines
2.1 KiB
Markdown
49 lines
2.1 KiB
Markdown
# 后端改造需求清单 (配合前端重构)
|
|
日期: 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` 字段的事件。
|