---
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. **后端启动**
```bash
cd backend
pip install -r requirements.txt
python -m app.main
```

2. **前端启动**
```bash
cd frontend
npm install
npm run dev
```

3. **数据同步** (首次运行)
```bash
cd backend
python scripts/sync_data.py
```

### Docker 部署

```bash
# 构建镜像
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](./DEVELOPMENT_PLAN.md)

## License

MIT