README.md

metadata

title: Paper Trading
emoji: 📈
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false

StockReplay-A: A股模拟交易复盘系统

一款基于 Web 的轻量级 A 股历史行情回放与模拟交易应用，提供"盲盒式"选股训练。

功能特性

• 盲盒式选股: 随机选择上市满3年的股票，隐藏股票名称，训练交易直觉
• K线回放: 基于 Lightweight Charts 的高性能K线展示，逐根推进模拟实盘
• 模拟交易: 纯前端计算买卖逻辑，实时展示收益率
• 零成本部署: 支持 Hugging Face Spaces 部署，数据持久化到 HF Datasets

技术栈

模块	技术
后端	Python 3.11 + FastAPI + DuckDB
数据源	AkShare (A股开源数据接口)
前端	Next.js 14 + TypeScript + Tailwind CSS
图表	Lightweight Charts (TradingView)
状态管理	Zustand
部署	Docker 多阶段构建

项目结构

Paper_Trading/
├── backend/                    # Python 后端
│   ├── app/
│   │   ├── main.py            # FastAPI 入口
│   │   ├── api.py             # 路由定义
│   │   ├── core.py            # 核心业务逻辑
│   │   └── database.py        # DuckDB 管理
│   ├── scripts/
│   │   └── sync_data.py       # 数据同步脚本
│   └── requirements.txt
├── frontend/                   # Next.js 前端
│   ├── src/
│   │   ├── app/               # App Router 页面
│   │   ├── components/        # UI 组件
│   │   ├── store/             # Zustand Store
│   │   └── lib/               # API 客户端
│   └── package.json
├── Dockerfile                  # Docker 部署配置
└── .env.example               # 环境变量示例

快速开始

本地开发

1. 后端启动

cd backend
pip install -r requirements.txt
python -m app.main

2. 前端启动

cd frontend
npm install
npm run dev

3. 数据同步 (首次运行)

cd backend
python scripts/sync_data.py

Docker 部署

# 构建镜像
docker build -t stock-replay-a .

# 运行容器
docker run -p 7860:7860 \
  -e HF_TOKEN=your_token \
  -e DATASET_REPO_ID=your_username/stock-db \
  stock-replay-a

Hugging Face Spaces 部署

1. 创建新的 Space (Docker 类型)
2. 设置环境变量:
   • HF_TOKEN: 你的 Hugging Face Token (需要 Write 权限)
   • DATASET_REPO_ID: 存储数据库的 Dataset ID
   • ADMIN_SECRET: 管理员密钥

API 接口

方法	路径	描述
GET	/api/health	健康检查
GET	/api/game/start	开始游戏，获取盲盒数据
GET	/api/kline?code=600519	获取指定股票K线
POST	/api/admin/sync	触发数据同步 (需认证)

环境变量

变量	描述	默认值
HF_TOKEN	Hugging Face Token	-
DATASET_REPO_ID	Dataset 仓库 ID	-
ADMIN_SECRET	管理员密钥	your-secret-key
DUCKDB_PATH	数据库路径	/tmp/stock_data.duckdb
PORT	服务端口	7860

开发计划

详细的开发计划请参阅 DEVELOPMENT_PLAN.md

License

MIT