b41eaf8b99
Major architectural shift from Next.js to a lightweight Vite + React SPA model ("Puppet Architecture") to better support real-time workflow visualization and strict type safety.
Key Changes:
1. **Architecture & Build**:
- Initialized Vite + React + TypeScript project.
- Configured Tailwind CSS v4 and Shadcn UI.
- Archived legacy Next.js frontend to 'frontend/archive/v2_nextjs'.
2. **Core Features**:
- **Dashboard**: Implemented startup page with Symbol, Market, and Template selection.
- **Report Page**:
- **Workflow Visualization**: Integrated ReactFlow to show dynamic DAG of analysis tasks.
- **Real-time Status**: Implemented Mock SSE logic to simulate task progress, logs, and status changes.
- **Multi-Tab Interface**: Dynamic tabs for 'Overview', 'Fundamental Data', and analysis modules.
- **Streaming Markdown**: Enabled typewriter-style streaming rendering for analysis reports using 'react-markdown'.
- **Config Page**: Implemented settings for AI Providers, Data Sources, and Templates using TanStack Query.
3. **Documentation**:
- Created v2.0 User Guide ('docs/1_requirements/20251122_[Active]_user-guide_v2.md').
- Implemented 'DocsPage' in frontend to render the user guide directly within the app.
4. **Backend Alignment**:
- Created 'docs/frontend/backend_todos.md' outlining necessary backend adaptations (OpenAPI, Progress tracking).
This commit establishes the full frontend 'shell' ready for backend integration.
76 lines
3.2 KiB
Markdown
76 lines
3.2 KiB
Markdown
# 后端改造需求清单 (配合前端重构)
|
||
日期: 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` (已实现)，以处理前端重连场景。
|
||
|