# quant-finance

**Repository Path**: github-26497262/quant-finance

## Basic Information

- **Project Name**: quant-finance
- **Description**: 量化投资分析平台
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-28
- **Last Updated**: 2026-05-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Quant Finance - 量化投资分析平台

一个基于 **双均线策略（金叉/死叉）** 的量化投资回测分析平台 MVP。

## 项目架构

```
┌──────────────────────────────────────────────────┐
│                   Frontend                        │
│  React + TypeScript + Ant Design + ECharts       │
│  http://localhost:5173                            │
└──────────────────────┬───────────────────────────┘
                       │  HTTP API (Axios)
                       │  Vite Proxy → /api/*
                       ▼
┌──────────────────────────────────────────────────┐
│                   Backend                         │
│  Python + FastAPI + AKShare + pandas             │
│  http://localhost:9527                            │
└──────────────────────┬───────────────────────────┘
                       │
                       ▼
                ┌──────────────┐
                │  AKShare     │  ← 免费 A 股数据源
                │  (网络请求)   │
                └──────────────┘
```

## 技术栈总览

| 层级 | 技术 | 版本 |
|------|------|------|
| 后端语言 | Python | 3.14 |
| Web 框架 | FastAPI | 0.136 |
| 数据源 | AKShare | 1.18 |
| 数据处理 | pandas / numpy | - |
| 前端框架 | React | 18 |
| 开发语言 | TypeScript | 5.5 |
| 构建工具 | Vite | 5.4 |
| UI 组件库 | Ant Design | 5.20 |
| 图表引擎 | ECharts | 5.5 |
| HTTP 客户端 | Axios | 1.7 |

## 环境要求

| 工具 | 版本 | 说明 |
|------|------|------|
| Python | >= 3.14 | 后端语言 |
| Node.js | >= 18 | 前端构建工具 |
| Git | >= 2 | 版本控制 |

## 快速启动

### 方式一：一键初始化（推荐）

**macOS / Linux:**
```bash
./scripts/setup.sh
```

**Windows:**
```cmd
scripts\setup.bat
```

### 方式二：手动安装

> **注意**: 以下所有命令请在项目根目录下执行。

#### 第一步：启动后端服务

```bash
# 1. 进入后端目录
cd backend

# 2. (推荐) 创建并激活虚拟环境
python -m venv .venv

# Windows:
.venv\Scripts\activate

# macOS / Linux:
source .venv/bin/activate

# 3. 安装依赖
pip install -r requirements.txt

# 4. 启动后端服务（开发模式，自动热重载）
python main.py
```

验证后端是否启动成功：

```bash
# 访问 API 文档（浏览器打开）
http://localhost:9527/docs

# 或命令行测试
curl http://localhost:9527/api/stock/000001?start=20250101
```

### 第二步：启动前端服务

```bash
# 新开一个终端，进入前端目录
cd frontend

# 1. 安装依赖
npm install

# 2. 启动开发服务器（默认 http://localhost:5173）
npm run dev
```

验证前端是否启动成功：浏览器打开 **http://localhost:5173**。

### 第三步：使用平台

1. 在股票选择下拉框中选择一只股票（如 000001 平安银行）
2. 调整均线参数（短期默认 5 日，长期默认 20 日）
3. 选择回测时间范围（默认最近一年）
4. 点击 **"运行回测"** 按钮
5. 查看回测结果：核心指标卡片、净值曲线、K 线图及交易信号

## 项目目录结构

```
quant-finance/
├── README.md                  # 项目总览（本文件）
├── .gitignore                 # Git 忽略规则
├── .env.example               # 环境变量示例
│
├── scripts/                   # 辅助脚本
│   ├── setup.sh               # macOS/Linux 一键初始化
│   └── setup.bat              # Windows 一键初始化
│
├── backend/                   # Python 后端服务
│   ├── README.md              # 后端详细说明
│   ├── requirements.txt       # Python 依赖
│   ├── main.py                # FastAPI 应用入口
│   ├── data_fetcher.py        # AKShare 数据获取
│   ├── backtest.py            # 双均线策略回测引擎
│   └── models.py              # 数据模型定义
│
└── frontend/                  # React 前端应用
    ├── README.md              # 前端详细说明
    ├── package.json           # 前端依赖
    ├── vite.config.ts         # Vite 配置（API 代理）
    ├── tsconfig.json          # TypeScript 配置
    ├── index.html             # HTML 入口
    └── src/
        ├── main.tsx           # React 入口
        ├── App.tsx            # 根组件
        ├── api/
        │   └── index.ts       # API 对接层
        ├── pages/
        │   └── Dashboard.tsx  # 主看板
        └── components/
            ├── KLineChart.tsx       # K 线图组件
            └── EquityCurveChart.tsx  # 净值曲线组件
```

## 策略说明

当前实现了 **双均线交叉策略**：

- **金叉（买入信号）**: 短期均线上穿长期均线 → 买入
- **死叉（卖出信号）**: 短期均线下穿长期均线 → 卖出
- **基准**: 同期买入持有（Buy & Hold）

### 回测指标含义

| 指标 | 说明 |
|------|------|
| 总收益率 | 策略在整个回测期间的总收益百分比 |
| 年化收益 | 将总收益折算为年化收益率 |
| 夏普比率 | 衡量风险调整后收益，>1 表示优秀 |
| 最大回撤 | 策略从最高点到最低点的最大跌幅 |
| 胜率 | 盈利交易次数 / 总交易次数 |

## Git 工作流

```bash
# 克隆仓库
git clone <你的 Gitee 仓库地址>
cd finance

# 查看状态
git status

# 添加修改
git add .

# 提交修改
git commit -m "提交说明"

# 推送到 Gitee
git push origin main
```

## License

MIT