fin_data_unify_plat/README.md

# 期货股票数据统一平台

> 基于 FastAPI + Vue 3 + TimescaleDB 的专业 K 线数据与实时行情服务平台

## 项目简介

本项目是一个统一的期货、股票数据服务平台，提供：

- 📊 **K 线数据查询** - 支持多周期历史 K 线数据
- 📈 **实时行情推送** - WebSocket 实时数据推送
- 🔔 **价格告警** - 灵活的价格条件告警
- 📱 **数据订阅** - 个性化数据订阅管理
- 🔐 **用户认证** - JWT 令牌认证 + API Key

## 技术栈

### 后端
- **框架**: FastAPI 0.109+
- **数据库**: TimescaleDB (时序数据) + SQLite (配置数据)
- **缓存**: Redis 7.2+
- **认证**: JWT (PyJWT)
- **异步**: asyncio + uvicorn

### 前端
- **框架**: Vue 3 + Vite
- **UI 组件**: Element Plus
- **图表**: ECharts 5.4+
- **状态管理**: Pinia
- **路由**: Vue Router 4

### 部署
- **容器化**: Docker + Docker Compose
- **反向代理**: Nginx

## 快速开始

### 1. 克隆项目

```bash
cd 20260330_kline_system
```

### 2. 配置环境变量

```bash
cp .env.example .env
# 编辑 .env 文件，修改必要配置
```

### 3. 一键部署

```bash
# 初始化数据库并启动所有服务
chmod +x deploy/init_db.sh
./deploy/init_db.sh
```

### 4. 访问系统

- **前端页面**: http://localhost
- **API 文档**: http://localhost:8000/docs
- **健康检查**: http://localhost:8000/health

**默认管理员账号**:
- 用户名：`admin`
- 密码：`admin123` (首次登录请修改)

## 项目结构

```
20260330_kline_system/
├── backend/                 # 后端服务
│   ├── app/
│   │   ├── api/v1/         # API 路由
│   │   ├── db/             # 数据库配置
│   │   ├── middleware/     # 中间件
│   │   ├── models/         # 数据模型
│   │   ├── schemas/        # 数据验证
│   │   ├── services/       # 业务服务
│   │   ├── config.py       # 配置文件
│   │   └── main.py         # 应用入口
│   ├── tests/              # 测试代码
│   ├── requirements.txt    # Python 依赖
│   └── Dockerfile
├── frontend/               # 前端服务
│   ├── src/
│   │   ├── api/           # API 封装
│   │   ├── layouts/       # 布局组件
│   │   ├── router/        # 路由配置
│   │   ├── stores/        # 状态管理
│   │   ├── views/         # 页面组件
│   │   ├── App.vue
│   │   └── main.js
│   ├── package.json
│   └── Dockerfile
├── deploy/                 # 部署脚本
│   ├── init_db.sh         # 数据库初始化
│   └── nginx.conf         # Nginx 配置
├── docker-compose.yml      # Docker 编排
└── .env.example           # 环境变量示例
```

## API 接口

### 认证接口
- `POST /api/v1/auth/login` - 用户登录
- `POST /api/v1/auth/refresh` - 刷新令牌
- `GET /api/v1/auth/me` - 获取当前用户
- `POST /api/v1/auth/api-key` - 创建 API Key

### K 线数据
- `GET /api/v1/kline/data` - 获取 K 线数据
- `GET /api/v1/kline/latest` - 获取最新 K 线
- `GET /api/v1/kline/symbols` - 获取品种列表
- `GET /api/v1/kline/periods` - 获取周期列表

### 实时行情
- `WS /api/v1/realtime/ws` - WebSocket 实时推送
- `GET /api/v1/realtime/quote` - 获取最新行情

### 告警管理
- `POST /api/v1/alert` - 创建告警
- `GET /api/v1/alert` - 获取告警列表
- `DELETE /api/v1/alert/{id}` - 删除告警

### 数据订阅
- `POST /api/v1/subscription` - 创建订阅
- `GET /api/v1/subscription` - 获取订阅列表
- `DELETE /api/v1/subscription/{id}` - 取消订阅

## 开发指南

### 后端开发

```bash
cd backend

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

# 本地运行
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 运行测试
pytest tests/ -v
```

### 前端开发

```bash
cd frontend

# 安装依赖
npm install

# 开发模式
npm run dev

# 构建生产版本
npm run build
```

## 运维命令

```bash
# 查看所有服务状态
docker-compose ps

# 查看服务日志
docker-compose logs -f backend
docker-compose logs -f frontend

# 重启服务
docker-compose restart backend

# 停止所有服务
docker-compose down

# 停止并删除数据卷
docker-compose down -v
```

## 系统要求

- Docker 24+
- Docker Compose 2.0+
- 内存：至少 4GB
- 磁盘：至少 10GB

## 安全建议

1. **修改默认密钥**: 生产环境务必修改 `SECRET_KEY`
2. **修改默认密码**: 首次登录后立即修改管理员密码
3. **启用 HTTPS**: 生产环境使用 HTTPS 加密传输
4. **限制 API 访问**: 配置防火墙规则，限制外部访问
5. **定期备份**: 定期备份数据库数据

## 性能优化

1. **数据库索引**: 已为常用查询字段创建索引
2. **数据压缩**: TimescaleDB 自动压缩历史数据
3. **缓存策略**: Redis 缓存热点数据
4. **限流保护**: API 限流防止恶意请求

## 故障排查

### 后端无法启动
```bash
# 查看后端日志
docker-compose logs backend

# 检查数据库连接
docker exec kline_timescaledb psql -U postgres -d kline_data -c "SELECT 1"
```

### 前端无法访问
```bash
# 查看前端日志
docker-compose logs frontend

# 检查 Nginx 配置
docker exec kline_nginx nginx -t
```

### 数据库连接失败
```bash
# 重启数据库
docker-compose restart timescaledb

# 等待数据库就绪
sleep 10
```

## 许可证

MIT License

## 联系方式

如有问题或建议，请提交 Issue 或联系开发团队。

---

**版本**: v1.0.0  
**更新日期**: 2026-04-02