# iTrader

**Repository Path**: topkernel/iTrader

## Basic Information

- **Project Name**: iTrader
- **Description**: 基于Rust的windows量化程序，完全基于claude code开发，支持高频交易、支持四大交易所、混合策略模式（预制策略和提供策略框架，支持个人定制策略）和机构级风控。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-30
- **Last Updated**: 2026-07-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# iTrader - 智能量化交易平台

[![Rust](https://img.shields.io/badge/Rust-1.75+-orange.svg)](https://www.rust-lang.org/)
[![React](https://img.shields.io/badge/React-18+-blue.svg)](https://reactjs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5+-blue.svg)](https://www.typescriptlang.org/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

iTrader 是一个基于 Rust 和 React 的智能量化交易平台，专注于 A 股和期货市场的技术分析与交易建议生成。

## 目录

- [核心功能](#-核心功能)
- [技术栈](#-技术栈)
- [环境要求](#-环境要求)
- [安装指南](#-安装指南)
- [快速开始](#-快速开始)
- [项目结构](#-项目结构)
- [配置说明](#-配置说明)
- [开发指南](#-开发指南)
- [API 文档](#-api-文档)
- [常见问题](#-常见问题)

## ✨ 核心功能

### 已实现 (第一阶段)

- 📊 **实时行情接入**
  - 东方财富 A 股数据源
  - 新浪财经备用数据源
  - 国内期货交易所数据

- 📈 **技术指标分析**
  - MA (移动平均线)
  - MACD (指数平滑异同移动平均线)
  - RSI (相对强弱指数)
  - KDJ (随机指标)
  - BOLL (布林带)

- 🔍 **K 线形态识别**
  - 早晨之星 / 黄昏之星
  - 锤子线 / 流星线
  - 看涨/看跌吞没形态
  - 红三兵 / 三只乌鸦
  - 十字星形态

- 📝 **智能建议生成**
  - 多维度信号评分 (0-100分)
  - 自动生成买卖建议文章
  - 入场价/目标价/止损价建议

- 🌐 **Web 界面**
  - 仪表盘概览
  - 建议列表与详情
  - 实时行情展示

### 开发中

- 💼 持仓管理
- 📋 策略回测
- 🔔 价格提醒
- 📊 板块分析

## 🛠️ 技术栈

### 后端

| 技术 | 说明 |
|------|------|
| Rust | 系统编程语言 |
| Axum | Web 框架 |
| PostgreSQL | 关系数据库 |
| Redis | 缓存 |

### 前端

| 技术 | 说明 |
|------|------|
| React 18 | UI 框架 |
| TypeScript | 类型安全 |
| Vite | 构建工具 |
| React Router | 路由 |

## 📋 环境要求

| 软件 | 最低版本 | 推荐版本 | 安装方式 |
|------|---------|---------|----------|
| Rust | 1.75+ | 最新稳定版 | [rustup](https://rustup.rs/) |
| Node.js | 18+ | 20+ | [nvm](https://github.com/nvm-sh/nvm) 或 [官网](https://nodejs.org/) |
| Docker | 20+ | 最新版 | [Docker Desktop](https://www.docker.com/products/docker-desktop/) |
| Git | 2.x | 最新版 | 系统包管理器 |

## 📦 安装指南

### 1. 安装 Rust

```bash
# Linux/macOS
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# 验证安装
rustc --version
cargo --version
```

### 2. 安装 Node.js

```bash
# 使用 nvm (推荐)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.nvm/nvm.sh
nvm install 20
nvm use 20

# 验证安装
node --version
npm --version
```

### 3. 安装 Docker

**Windows / macOS:**
1. 下载 [Docker Desktop](https://www.docker.com/products/docker-desktop/)
2. 安装并启动 Docker Desktop
3. 验证: `docker --version`

**Linux:**
```bash
# Ubuntu/Debian
sudo apt update
sudo apt install docker.io docker-compose-plugin
sudo usermod -aG docker $USER
# 重新登录后验证
docker --version
```

### 4. 配置 Docker 镜像加速 (中国大陆用户)

**Docker Desktop 方式:**
1. 打开 Docker Desktop
2. 点击右上角 **Settings** (齿轮图标)
3. 选择 **Docker Engine**
4. 在 JSON 配置中添加镜像加速:

```json
{
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB",
      "enabled": true
    }
  },
  "experimental": false,
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://dockerproxy.com"
  ]
}
```

5. 点击 **Apply & Restart**
6. 等待 Docker 重启完成

**Linux 命令行方式:**
```bash
sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json << 'EOF'
{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://dockerproxy.com"
  ]
}
EOF
sudo systemctl restart docker
```

### 5. 克隆项目

```bash
git clone https://github.com/yourusername/iTrader.git
cd iTrader
```

## 🚀 快速开始

### 一键启动

```bash
# 前台模式启动 (Ctrl+C 停止)
./start.sh

# 后台模式启动
./start.sh --detach
# 或
./start.sh -d
```

启动脚本会自动：
1. ✅ 检查依赖 (Rust, Node.js, Docker)
2. 🐳 启动 Docker 数据库服务 (PostgreSQL, Redis)
3. ⏳ 等待数据库就绪
4. 🔨 编译并运行后端 API 服务
5. 📦 安装前端依赖
6. 🌐 启动前端开发服务器

### 访问服务

启动成功后，访问以下地址：

| 服务 | 地址 | 说明 |
|------|------|------|
| 前端界面 | http://localhost:5173 | React 开发服务器 |
| 后端 API | http://localhost:8080 | Axum REST API |
| 健康检查 | http://localhost:8080/health | API 健康状态 |

### 停止服务

```bash
# 停止所有服务
./stop.sh

# 查看服务状态
./status.sh

# 仅停止后端
./stop.sh --backend

# 仅停止前端
./stop.sh --frontend

# 仅停止数据库
./stop.sh --db
```

## 📁 项目结构

```
iTrader/
├── crates/                    # Rust 后端
│   ├── common/                # 公共类型和工具
│   │   ├── types.rs           # 核心类型定义
│   │   ├── error.rs           # 错误处理
│   │   └── config.rs          # 配置管理
│   │
│   ├── data/                  # 行情数据模块
│   │   ├── source/            # 数据源实现
│   │   │   ├── eastmoney.rs   # 东方财富
│   │   │   ├── sina.rs        # 新浪财经
│   │   │   └── futures.rs     # 期货数据
│   │   └── storage/           # 数据存储
│   │
│   ├── signal/                # 信号分析模块
│   │   ├── indicators/        # 技术指标
│   │   │   ├── ma.rs          # 移动平均线
│   │   │   ├── macd.rs        # MACD
│   │   │   ├── rsi.rs         # RSI
│   │   │   ├── kdj.rs         # KDJ
│   │   │   └── boll.rs        # 布林带
│   │   ├── patterns/          # 形态识别
│   │   └── scorer/            # 评分引擎
│   │
│   ├── suggestion/            # 建议生成模块
│   │   ├── generator.rs       # 建议生成器
│   │   └── templates.rs       # 文章模板
│   │
│   └── api/                   # REST API 服务
│       ├── main.rs            # 服务入口
│       ├── routes/            # API 路由
│       └── websocket.rs       # WebSocket
│
├── web/                       # React 前端
│   ├── src/
│   │   ├── components/        # UI 组件
│   │   ├── pages/             # 页面
│   │   │   ├── Dashboard.tsx  # 仪表盘
│   │   │   ├── Suggestions.tsx# 建议列表
│   │   │   └── Market.tsx     # 行情中心
│   │   ├── hooks/             # React Hooks
│   │   ├── services/          # API 服务
│   │   ├── types/             # TypeScript 类型
│   │   └── utils/             # 工具函数
│   └── package.json
│
├── config/
│   └── default.toml           # 默认配置
│
├── migrations/
│   └── 001_init.sql           # 数据库初始化
│
├── docker-compose.yml         # Docker 配置
├── start.sh                   # 启动脚本
├── stop.sh                    # 停止脚本
├── status.sh                  # 状态检查脚本
└── README.md
```

## ⚙️ 配置说明

### 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `DATABASE_URL` | PostgreSQL 连接 | `postgres://itrader:itrader123@localhost:5432/itrader` |
| `REDIS_URL` | Redis 连接 | `redis://localhost:6379` |
| `RUST_LOG` | 日志级别 | `itrader=debug,sqlx=warn` |

### 配置文件

编辑 `config/default.toml`:

```toml
[server]
host = "0.0.0.0"
port = 8080

[database]
url = "postgres://itrader:itrader123@localhost:5432/itrader"

[redis]
url = "redis://localhost:6379"

[data_source]
primary = "eastmoney"  # 数据源: eastmoney / sina
poll_interval = 3       # 轮询间隔(秒)

[signal]
min_score = 70          # 最低评分阈值
min_confidence = 0.65   # 最低置信度
same_stock_interval_hours = 24  # 同一股票重复推荐间隔

[suggestion]
expire_hours = 24       # 建议有效期(小时)
```

## 🔧 开发指南

### 后端开发

```bash
# 运行测试
cargo test

# 代码检查
cargo clippy

# 格式化代码
cargo fmt

# 构建发布版本
cargo build --release

# 运行单个模块
cargo run -p itrader-api
cargo run -p itrader-signal
```

### 前端开发

```bash
cd web

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建生产版本
npm run build

# 代码检查
npm run lint

# 预览构建结果
npm run preview
```

### 数据库操作

```bash
# 连接数据库
docker exec -it itrader-db psql -U itrader -d itrader

# 查看表结构
\dt

# 查看建议数据
SELECT id, symbol, direction, score, created_at FROM suggestions ORDER BY created_at DESC LIMIT 10;

# 手动执行迁移
psql -U itrader -d itrader -f migrations/001_init.sql
```

## 📊 API 文档

### 行情接口

```bash
# 获取股票列表
GET /api/v1/market/stocks

# 获取单个股票
GET /api/v1/market/stocks/:code

# 获取期货列表
GET /api/v1/market/futures

# 获取实时行情 (多个股票)
GET /api/v1/market/quotes?symbols=sh600000,sz000001

# 获取 K 线数据
GET /api/v1/market/bars/:symbol?period=1d&limit=100
```

### 建议接口

```bash
# 获取建议列表
GET /api/v1/suggestions?limit=20&offset=0&direction=buy&min_score=70

# 获取建议详情
GET /api/v1/suggestions/:id
```

### WebSocket

```javascript
// 连接 WebSocket
const ws = new WebSocket('ws://localhost:8080/ws');

// 订阅行情
ws.send(JSON.stringify({
  type: 'subscribe',
  channels: ['ticker.sh600000', 'ticker.sz000001']
}));

// 接收消息
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};
```

### 健康检查

```bash
# API 健康检查
curl http://localhost:8080/health

# 就绪检查
curl http://localhost:8080/ready
```

## 📝 信号评分系统

评分采用百分制，由以下维度组成：

| 维度 | 分值 | 说明 |
|------|------|------|
| 技术指标 | 0-40 | MACD、RSI、KDJ 等综合评分 |
| 形态识别 | 0-30 | K 线形态分析得分 |
| 量价配合 | 0-20 | 成交量与价格关系评分 |
| 趋势确认 | 0-10 | 均线排列确认得分 |

**信号方向判定：**

| 方向 | 条件 | 颜色 |
|------|------|------|
| 🔴 强烈买入 | 评分 ≥ 80，上涨趋势 | 红色 |
| 🟠 买入 | 评分 ≥ 65，上涨趋势 | 橙色 |
| ⚪ 中性 | 评分 40-65 | 灰色 |
| 🟢 卖出 | 评分 < 40，下跌趋势 | 绿色 |
| 🟢 强烈卖出 | 评分 < 40，强烈下跌 | 深绿色 |

## ❓ 常见问题

### 1. Docker 镜像拉取失败

**问题**: `failed to resolve reference "docker.io/..."`

**解决方案**:
1. 确保已配置镜像加速器 (见 [安装指南](#4-配置-docker-镜像加速-中国大陆用户))
2. 检查网络连接
3. 尝试手动拉取:
   ```bash
   docker pull dockerproxy.com/library/postgres:16-alpine
   docker tag dockerproxy.com/library/postgres:16-alpine postgres:16-alpine
   ```

### 2. 后端编译失败

**问题**: `cargo build` 报错

**解决方案**:
```bash
# 更新 Rust
rustup update

# 清理并重新构建
cargo clean
cargo build
```

### 3. 前端依赖安装失败

**问题**: `npm install` 报错

**解决方案**:
```bash
# 清理缓存
npm cache clean --force

# 删除 node_modules 重新安装
rm -rf web/node_modules web/package-lock.json
cd web && npm install
```

### 4. 数据库连接失败

**问题**: `connection refused` 或 `database "itrader" does not exist`

**解决方案**:
```bash
# 检查 Docker 容器状态
docker ps

# 查看数据库日志
docker logs itrader-db

# 重启数据库
docker-compose restart postgres
```

### 5. 端口被占用

**问题**: `Address already in use`

**解决方案**:
```bash
# 查看端口占用
lsof -i :8080  # 后端
lsof -i :5173  # 前端
lsof -i :5432  # 数据库

# 终止占用进程
kill -9 <PID>
```

### 6. WSL 中 Docker 不工作

**解决方案**:
1. 确保 Docker Desktop 已启动
2. 在 Docker Desktop 设置中启用 WSL 集成
3. Settings -> Resources -> WSL Integration -> 启用你的发行版

## 🐳 Docker 常用命令

```bash
# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f
docker-compose logs -f postgres  # 特定服务

# 停止服务
docker-compose down

# 停止并删除数据卷 (清理所有数据)
docker-compose down -v

# 进入容器
docker exec -it itrader-db bash
docker exec -it itrader-redis redis-cli
```

## 📄 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 📧 联系方式

- 项目主页: https://github.com/yourusername/iTrader
- 问题反馈: https://github.com/yourusername/iTrader/issues

---

**⚠️ 免责声明**: 本项目仅供学习和研究使用，不构成任何投资建议。投资有风险，入市需谨慎。