Lv, Qi b41eaf8b99 Refactor frontend to Vite+React SPA and update docs

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.

2025-11-22 19:37:36 +08:00

3.2 KiB

Raw Blame History

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

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

响应结构示例:

{
  "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 字段。
```
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 (已实现)，以处理前端重连场景。

3.2 KiB Raw Blame History Unescape Escape