feat: user auth and payment gateway

.codebuddy/plans/Paper_Trading_项目初始化与开发_57815873.md

@@ -0,0 +1,219 @@
+---
+name: Paper_Trading 项目初始化与开发
+overview: 根据 DEVELOPMENT_PLAN.md 文档，初始化并开发一个基于 Web 的A股历史行情回放与模拟交易应用，包含后端（FastAPI + DuckDB）和前端（Next.js + Lightweight Charts）的完整功能。
+design:
+  architecture:
+    framework: react
+    component: tdesign
+  styleKeywords:
+    - Dark Theme
+    - Financial Tech
+    - Data Visualization
+    - Professional Trading
+  fontSystem:
+    fontFamily: Roboto
+    heading:
+      size: 24px
+      weight: 600
+    subheading:
+      size: 16px
+      weight: 500
+    body:
+      size: 14px
+      weight: 400
+  colorSystem:
+    primary:
+      - "#1E88E5"
+      - "#42A5F5"
+    background:
+      - "#0D1421"
+      - "#1A2332"
+      - "#242F3D"
+    text:
+      - "#FFFFFF"
+      - "#B0BEC5"
+      - "#78909C"
+    functional:
+      - "#4CAF50"
+      - "#EF5350"
+      - "#FFC107"
+todos:
+  - id: init-project
+    content: 创建项目目录结构，编写 requirements.txt 和 frontend/package.json
+    status: completed
+  - id: database-module
+    content: 实现 backend/app/database.py，包含 init_db、upload_db 和单例连接
+    status: completed
+    dependencies:
+      - init-project
+  - id: sync-script
+    content: 编写 backend/scripts/sync_data.py，实现 AkShare 数据获取和入库逻辑
+    status: completed
+    dependencies:
+      - database-module
+  - id: backend-api
+    content: 开发 backend/app/main.py、api.py、core.py，实现盲盒选股和 K 线查询 API
+    status: completed
+    dependencies:
+      - sync-script
+  - id: frontend-setup
+    content: 初始化 Next.js 项目，配置 TypeScript、Tailwind CSS 和 next.config.mjs
+    status: completed
+    dependencies:
+      - init-project
+  - id: frontend-components
+    content: 开发 Chart 组件、TradePanel 组件和 Zustand Store
+    status: completed
+    dependencies:
+      - frontend-setup
+  - id: integration-deploy
+    content: 编写 Dockerfile，本地 Docker 构建测试
+    status: completed
+    dependencies:
+      - backend-api
+      - frontend-components
+---
+
+## 产品概述
+
+StockReplay-A 是一款基于 Web 的 A 股历史行情回放与模拟交易应用，提供"盲盒式"选股训练，帮助用户在随机历史行情中验证交易策略，部署到 Hugging Face Spaces 实现零成本运行。
+
+## 核心功能
+
+- **盲盒式选股**：随机选择上市满3年的股票，随机起点，保证至少250个交易日数据，脱敏隐藏股票代码直到游戏结束
+- **K线回放**：使用 Lightweight Charts 展示K线图，前端逐根推进，模拟实盘体验
+- **模拟交易**：纯前端计算买卖逻辑，支持买入/卖出/下一根K线操作，记录交易历史和收益率
+- **数据持久化**：DuckDB 嵌入式存储 + Hugging Face Datasets 同步，解决 HF Space 重启数据丢失问题
+
+## 技术栈选型
+
+### 后端技术
+
+- **Python 3.11**：高性能异步支持
+- **FastAPI**：异步 API 框架
+- **DuckDB**：嵌入式 OLAP 数据库，单文件存储
+- **AkShare**：A股开源数据接口
+- **huggingface_hub**：Dataset 同步 SDK
+
+### 前端技术
+
+- **Next.js 14**：App Router 模式
+- **TypeScript**：严格类型检查
+- **Tailwind CSS**：Utility-first CSS
+- **Lightweight Charts**：TradingView 出品的 Canvas 渲染图表库
+- **Zustand**：轻量级状态管理
+
+### 部署架构
+
+- **Docker**：多阶段构建，前端构建静态资源后由 FastAPI 托管
+- **Hugging Face Spaces**：免费容器运行环境
+
+## 实现方案
+
+### 系统架构
+
+采用前后端分离的单体应用架构，通过 Docker 多阶段构建打包：
+
+1. Stage 1：构建 Next.js 静态资源（output: 'export'）
+2. Stage 2：FastAPI 后端 + 托管前端静态文件
+
+### 数据流设计
+
+```
+启动时 → hf_hub_download 下载 DuckDB 文件
+运行时 → FastAPI 读取 DuckDB 返回 K 线数据
+定时任务 → AkShare 增量更新 → upload_file 推送到 Dataset
+```
+
+### 盲盒选股算法
+
+1. 从 stock_list 筛选 list_date 早于3年前的股票
+2. 随机选取一只股票
+3. 随机选择起始点（确保剩余 >= 250 天）
+4. 返回后续 500 条 K 线数据（脱敏处理）
+
+### 模拟交易引擎
+
+纯前端 Zustand Store 管理：
+
+- 买入：计算成本均价、扣减现金、增加持仓
+- 卖出：按当前价结算、增加现金、清空持仓
+- 收益率：(现金 + 持仓市值 - 初始资金) / 初始资金
+
+## 目录结构
+
+```
+c:/python_project/Paper_Trading/
+├── backend/                          # Python 后端
+│   ├── app/
+│   │   ├── main.py                   # [NEW] FastAPI 入口，配置静态文件托管、CORS、生命周期事件
+│   │   ├── api.py                    # [NEW] 路由定义，实现 /api/health、/api/game/start、/api/kline、/api/admin/sync
+│   │   ├── core.py                   # [NEW] 核心业务逻辑，实现盲盒选股算法、K线数据查询
+│   │   └── database.py               # [NEW] DuckDB 管理模块，实现 init_db、upload_db、单例连接池
+│   ├── scripts/
+│   │   └── sync_data.py              # [NEW] 数据同步脚本，AkShare 获取 A 股列表和日线数据
+│   └── requirements.txt              # [NEW] Python 依赖：fastapi, uvicorn, duckdb, pandas, akshare, huggingface_hub
+├── frontend/                         # Next.js 前端
+│   ├── src/
+│   │   ├── app/
+│   │   │   ├── layout.tsx            # [NEW] 根布局，配置 Tailwind 和全局样式
+│   │   │   ├── page.tsx              # [NEW] 主页面，整合 Chart 和 TradePanel
+│   │   │   └── globals.css           # [NEW] 全局 CSS 样式
+│   │   ├── components/
+│   │   │   ├── Chart.tsx             # [NEW] Lightweight Charts 封装，支持 ResizeObserver
+│   │   │   └── TradePanel.tsx        # [NEW] 交易面板组件，买入/卖出/下一根K线交互
+│   │   ├── hooks/
+│   │   │   └── useGame.ts            # [NEW] 游戏逻辑 Hook，封装 startGame、nextCandle 等方法
+│   │   ├── store/
+│   │   │   └── gameStore.ts          # [NEW] Zustand Store，管理 cash、holdings、avgPrice、history 状态
+│   │   └── lib/
+│   │       └── api.ts                # [NEW] API 客户端，封装 fetch 请求
+│   ├── package.json                  # [NEW] 前端依赖配置
+│   ├── tsconfig.json                 # [NEW] TypeScript 配置
+│   ├── tailwind.config.ts            # [NEW] Tailwind CSS 配置
+│   ├── next.config.mjs               # [NEW] Next.js 配置，output: 'export'
+│   └── postcss.config.mjs            # [NEW] PostCSS 配置
+├── Dockerfile                        # [NEW] 多阶段构建配置
+└── README.md                         # [MODIFY] 项目说明文档
+```
+
+## 实现要点
+
+### 数据库持久化
+
+- 启动时检查 `/tmp/stock_data.duckdb` 是否存在，不存在则从 HF Dataset 下载
+- 数据更新后立即调用 `upload_file` 推送到 Dataset Repo
+- 使用环境变量 `HF_TOKEN`、`DATASET_REPO_ID` 配置认证
+
+### 性能优化
+
+- DuckDB 使用列式存储，索引优化查询速度
+- 前端使用 Canvas 渲染（Lightweight Charts），避免 DOM 重绘开销
+- K 线数据分批加载，避免一次性传输大量数据
+
+### 错误处理
+
+- API 返回标准错误格式 `{ "error": "message" }`
+- 前端全局错误边界捕获渲染错误
+- 数据同步失败时记录日志但不中断服务
+
+## 设计风格
+
+采用现代金融科技风格，深色主题为主，强调数据可视化和专业交易体验。使用 React + TypeScript + Tailwind CSS + TDesign 组件库构建。
+
+## 页面规划
+
+### 主页面（游戏页面）
+
+分为四个核心区块：
+
+1. **顶部导航栏**：Logo、游戏状态、收益率显示
+2. **K线图表区**：Lightweight Charts 全屏展示，支持缩放和十字光标
+3. **交易面板区**：资金余额、持仓信息、买入/卖出按钮、数量输入框
+4. **底部控制栏**：下一根K线、重新开始、揭示答案按钮
+
+## 交互设计
+
+- K线推进时有平滑动画效果
+- 交易按钮点击有即时反馈
+- 持仓变化时数字有高亮闪烁效果