trading-discipline-backend/README.md

Trading Backend 🦀

基于 Rust 的交易数据后端服务，提供A股公司信息、历史行情、实时数据查询接口，支持多数据库和Redis缓存。

🏗️ 架构设计

技术栈

• Web框架: Axum 0.7
• 数据库: SQLite（可切换到 PostgreSQL/MySQL）
• 缓存: Redis（Key = md5(url + 参数)）
• ORM: SQLx + SeaORM（多数据库兼容）
• 异步运行时: Tokio

目录结构

backend/
├── migrations/         # 数据库迁移文件
├── src/
│   ├── main.rs        # 入口文件
│   ├── db/            # 数据库抽象层（支持多数据库）
│   ├── cache/         # Redis 缓存层
│   ├── models/        # 数据模型
│   ├── services/      # 数据服务（可扩展多数据源）
│   ├── routes/        # API 路由
│   └── utils/         # 工具函数
├── data/              # SQLite 数据文件（运行时创建）
├── Cargo.toml
├── .env               # 环境变量
└── .env.example       # 环境变量模板

核心特性

1. 多数据库兼容

   • 当前使用 SQLite（无配置开箱即用）
   • 通过修改环境变量 DB_TYPE 可切换到 PostgreSQL/MySQL
   • 使用 trait 抽象数据库接口，未来可平滑迁移

2. Redis 缓存

   • 缓存 Key 格式：td:cache:{md5(url+参数)}
   • 默认 TTL: 5 分钟
   • 支持缓存查询结果，减少外部 API 调用

3. 数据源可扩展

   • 实现 DataService trait
   • 当前提供 MockService（测试）和 TushareService（生产）
   • 可轻松接入其他数据源（东方财富、同花顺等）

📊 数据库设计

表结构

companies - 公司基本信息

- id: 主键
- code: 股票代码
- name: 公司名称
- market: 市场（SH/SZ/BJ）
- industry: 行业
- list_date: 上市日期
- ...

stock_daily - 日线行情

- id: 主键
- stock_id: 关联公司ID
- trade_date: 交易日期
- open/high/low/close: OHLC
- volume/amount: 成交量/额
- adj_close: 前复权价
- ...

dividends - 分红送转

- id: 主键
- stock_id: 关联公司ID
- div_date: 除权日
- dividend_cash: 每股现金分红
- ...

🚀 快速开始

前置要求

• Rust 1.70+
• Redis（可选，用于缓存）
• SQLite（已内置）

安装运行

cd backend

# 安装依赖
cargo build

# 复制配置文件
cp .env.example .env

# 启动服务
./start.sh
# 或直接运行
cargo run

服务默认运行在 http://localhost:8080

环境变量配置

编辑 .env 文件：

# 服务器配置
RUST_LOG=info
SERVER_HOST=0.0.0.0
SERVER_PORT=8080

# 数据库配置
DB_TYPE=sqlite
SQLITE_PATH=./data/trading.db

# Redis 配置（可选）
REDIS_URL=redis://127.0.0.1:6379
REDIS_CACHE_TTL=300

# Tushare Token（如需使用真实数据源）
TUSHARE_TOKEN=your_token_here

📡 API 接口

公开 API

方法	路径	说明
GET	/health	健康检查
GET	/api/companies	获取公司列表（分页）
GET	/api/companies/:code	获取公司详情
GET	/api/companies/search	搜索公司
GET	/api/stocks/daily	获取日线行情
GET	/api/stocks/latest	获取最新行情

示例请求

# 获取公司列表
curl http://localhost:8080/api/companies?page=1&page_size=20

# 获取公司详情
curl http://localhost:8080/api/companies/000100

# 搜索公司
curl "http://localhost:8080/api/companies/search?keyword=科技"

# 获取日线行情
curl "http://localhost:8080/api/stocks/daily?code=000100&start=2024-01-01&end=2024-12-31"

# 获取最新行情
curl "http://localhost:8080/api/stocks/latest?codes=000100,600036"

响应格式

{
  "code": 200,
  "message": "success",
  "data": { ... }
}

🔐 内部 API（管理后台）

方法	路径	说明
POST	/api/internal/sync/companies	同步公司列表
POST	/api/internal/sync/daily	同步历史行情

🧪 测试

# 运行所有测试
cargo test

# 运行特定测试
cargo test test_generate_key

📦 构建生产版本

# 构建 Release
cargo build --release

# 运行
./target/release/trading-backend

🔄 切换数据库

切换到 PostgreSQL

DB_TYPE=postgres
POSTGRES_URL=postgresql://user:password@localhost/trading

切换到 MySQL

DB_TYPE=mysql
MYSQL_URL=mysql://user:password@localhost/trading

🔧 开发指南

添加新的数据源

1. 实现 DataService trait
2. 在 main.rs 中注册服务
3. 重启服务

添加新的 API

1. 在 routes/ 中创建处理器
2. 在 main.rs 中注册路由
3. 添加单元测试

📝 待办事项

• 完善数据库同步逻辑
• 实现前复权价格计算
• 添加更多技术指标（MA/MACD/KDJ）
• 实现实时行情推送（WebSocket）
• 添加认证和授权
• 性能优化和监控

📄 License

MIT