# Next.js 重构计划

## 1. 后端功能评估

根据代码库，后端提供以下核心功能：
- **策略管理**：创建/更新/删除量化策略 (`/api/v1/strategies`)
- **股票数据**：获取股票基本信息 (`/api/v1/stocks`)
- **回测功能**：运行策略回测 (`/api/v1/backtest`)
- **选股功能**：执行选股策略 (`/api/v1/stock-selection`)
- **投资组合**：管理虚拟投资组合 (`/api/v1/portfolios`)

## 2. Next.js 重构计划

### 项目结构
```
qsss-web/
├── app/
│   ├── dashboard/         # 首页仪表盘
│   ├── strategies/        # 策略管理
│   ├── backtest/          # 回测分析
│   ├── selection/         # 选股结果
│   └── api/               # API路由
├── components/            # 共享组件
├── lib/                   # 工具函数
├── types/                 # TypeScript类型定义
└── public/                # 静态资源
```

### 核心功能设计

1.  **仪表盘页面** (`/dashboard`)
    *   **数据源**: 后端 API (`/api/v1/market-data`, `/api/v1/strategies/summary`, `/api/v1/portfolios/summary`)
    *   **组件**:
        *   `MarketIndicators.tsx`: 展示上证、深证、创业板、北交所指数，使用 `recharts` 或 `nivo` 进行趋势图可视化。
        *   `HotNewsFeed.tsx`: 抓取外部财经新闻（通过后端代理或直接抓取），提供可点击的外部链接。
        *   `StrategyPerformanceSummary.tsx`: 展示热门策略的简要表现，链接到策略详情页。
        *   `PortfolioOverview.tsx`: 用户投资组合的简要概览。
    *   **交互**: 指数卡片点击可查看详情，新闻点击跳转外部链接，策略卡片点击跳转策略详情。

2.  **策略管理** (`/strategies`)
    *   **数据源**: 后端 API (`/api/v1/strategies`, `/api/v1/strategy-instances`)
    *   **组件**:
        *   `StrategyList.tsx`: 展示所有策略，支持搜索、过滤、排序、分页。
        *   `StrategyForm.tsx`: 创建/编辑策略的表单，包含参数配置（JSON Schema 动态生成表单）。
        *   `StrategyInstanceList.tsx`: 展示策略实例（运行中的策略）。
    *   **交互**: 策略列表项点击进入详情，创建/编辑策略，启动/停止策略实例。

3.  **回测分析** (`/backtest`)
    *   **数据源**: 后端 API (`/api/v1/backtest`, `/api/v1/backtest-results`)
    *   **组件**:
        *   `BacktestForm.tsx`: 设置回测参数（策略ID、股票池、时间范围、初始资金等）。
        *   `EquityCurveChart.tsx`: 使用 `recharts` 或 `nivo` 绘制资金曲线。
        *   `BacktestMetricsTable.tsx`: 展示回测关键指标（夏普比率、最大回撤等）。
        *   `TradeList.tsx`: 展示回测期间的交易详情。
    *   **交互**: 提交回测任务，查看回测进度，分析回测结果。

4.  **选股结果** (`/selection`)
    *   **数据源**: 后端 API (`/api/v1/stock-selection`, `/api/v1/stocks`)
    *   **组件**:
        *   `StockSelectionForm.tsx`: 设置选股条件（基于策略或自定义条件）。
        *   `SelectedStockTable.tsx`: 展示选股结果，支持排序、过滤。
        *   `StockDetailModal.tsx`: 股票详细信息弹窗。
    *   **交互**: 提交选股任务，查看选股结果，点击股票查看详情。

### 技术栈选择
-   **框架**: Next.js 14 (App Router) - 强调 Server Components 和 Client Components 的合理划分。
-   **UI库**: Shadcn UI + Tailwind CSS - 提供可定制的、无障碍的组件。
-   **状态管理**: Zustand - 用于客户端的轻量级全局状态管理。
-   **数据获取**: React Query (TanStack Query) - 用于客户端数据缓存、同步和更新。
-   **API层**: Next.js API Routes (或 Server Actions) 作为后端 API 的代理层，处理认证和数据转换。
-   **可视化**: Recharts (或 Nivo) - 用于图表绘制。
-   **表单处理**: React Hook Form + Zod - 用于表单验证和提交。
-   **类型安全**: TypeScript - 全面类型检查。

## 3. 实施路线图

### 阶段1：项目初始化与基础架构 (1-2天)
1.  创建 Next.js 项目 (`npx create-next-app@latest qsss-web --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"`)。
2.  配置 `tailwind.config.ts` 和 `globals.css`。
3.  集成 Shadcn UI (`npx shadcn-ui@latest init` & `npx shadcn-ui@latest add button card form input label table ...`)。
4.  设置 `lib/api.ts` (Axios 实例) 和 `app/api/proxy/route.ts` (Next.js API Route 作为后端代理)。
5.  创建 `components/shared/Layout.tsx` (包含侧边栏导航和顶部Header)。
6.  定义 `types/` 目录下的核心数据模型类型。

### 阶段2：核心功能开发 (5-7天)
1.  **仪表盘页面** (`app/dashboard/page.tsx`)
    *   实现 `MarketIndicators.tsx` (模拟数据，后期集成实时API)。
    *   实现 `HotNewsFeed.tsx` (模拟数据，后期集成外部API)。
    *   集成后端 API 获取策略和投资组合摘要数据。
2.  **策略管理页面** (`app/strategies/page.tsx` & `app/strategies/[id]/page.tsx`)
    *   实现 `StrategyList.tsx`，通过 React Query 获取策略列表。
    *   实现 `StrategyForm.tsx`，使用 React Hook Form 和 Zod 进行表单验证和提交。
    *   实现策略的创建、编辑、删除功能。
3.  **回测分析页面** (`app/backtest/page.tsx`)
    *   实现 `BacktestForm.tsx`。
    *   集成后端 API 触发回测任务。
    *   实现 `EquityCurveChart.tsx` 和 `BacktestMetricsTable.tsx`。
4.  **选股结果页面** (`app/selection/page.tsx`)
    *   实现 `StockSelectionForm.tsx`。
    *   集成后端 API 获取选股结果。
    *   实现 `SelectedStockTable.tsx`。

### 阶段3：高级功能与优化 (3-5天)
1.  **认证集成**: 如果后端有认证，集成 NextAuth.js 或手动实现认证流程。
2.  **实时数据**: 探索 WebSocket 或 Server-Sent Events (SSE) 实现实时数据更新。
3.  **性能优化**:
    *   使用 Next.js 的 Image 组件优化图片。
    *   代码分割和懒加载。
    *   Server Components 的合理使用。
4.  **错误处理与加载状态**: 全局错误边界，友好的加载和错误提示。
5.  **用户体验优化**: 动画、微交互。

### 阶段4：测试与部署 (1-2天)
1.  **单元测试**: 使用 Jest/React Testing Library 对组件进行单元测试。
2.  **端到端测试**: 使用 Playwright 或 Cypress 进行端到端测试。
3.  **Docker容器化**: 为 Next.js 应用创建 Dockerfile，优化镜像大小。
4.  **Hugging Face Space部署**: 调整 `Dockerfile` 和 `app.py` (如果需要) 以适应 Hugging Face Space 的部署环境，确保路由和静态文件服务正确。

## 风险与挑战
-   **Hugging Face Space 路由限制**: 之前遇到的首页问题可能需要通过 Next.js 的 `basePath` 或自定义服务器配置来解决，这在免费层可能有限制。
-   **后端 API 性能**: 如果后端 API 响应慢，会直接影响前端体验。
-   **数据量**: 大量股票数据和回测结果可能导致前端渲染性能问题，需要虚拟化列表等优化。
-   **TA-Lib 兼容性**: 确保后端环境中的 TA-Lib 库与 Python 版本兼容。

## 评估标准
-   所有核心功能在 Next.js 前端正常工作。
-   页面加载速度快，用户体验流畅。
-   代码结构清晰，易于维护和扩展。
-   成功部署到 Hugging Face Space 并可访问。