| # 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 并可访问。 |
