Hugging Face's logo

Spaces:
misonL
/
QSSS_new
Paused

App Files Community
QSSS_new / docs /nextjs_refactor_plan.md
misonL's picture
misonL
feat: 初始化Next.js项目并添加核心功能
be48fac
preview code
|
Raw
History Blame Contribute Delete
7.51 kB

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