# 期货股票数据统一平台 - 后端服务

## 技术栈

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

## 目录结构

```
backend/
├── app/
│   ├── api/
│   │   └── v1/
│   │       ├── auth.py        # 认证 API
│   │       ├── kline.py       # K 线数据 API
│   │       ├── realtime.py    # 实时行情 API
│   │       ├── alert.py       # 告警管理 API
│   │       ├── subscription.py # 数据订阅 API
│   │       └── user.py        # 用户管理 API
│   ├── db/
│   │   └── init_db.py         # 数据库初始化
│   ├── middleware/
│   │   ├── auth.py            # 认证中间件
│   │   └── rate_limit.py      # 限流中间件
│   ├── models/
│   │   └── __init__.py        # SQLAlchemy 模型
│   ├── schemas/
│   │   └── __init__.py        # Pydantic 数据验证
│   ├── services/
│   │   ├── auth_service.py    # 认证服务
│   │   ├── kline_service.py   # K 线数据服务
│   │   ├── realtime_service.py # 实时行情服务
│   │   ├── alert_service.py   # 告警服务
│   │   └── subscription_service.py # 订阅服务
│   ├── config.py              # 配置文件
│   └── main.py                # 应用入口
├── tests/
│   └── test_api.py            # API 测试
├── requirements.txt           # Python 依赖
└── Dockerfile                 # Docker 构建
```

## API 接口

### 认证接口
- `POST /api/v1/auth/login` - 用户登录
- `POST /api/v1/auth/refresh` - 刷新令牌
- `GET /api/v1/auth/me` - 获取当前用户信息
- `POST /api/v1/auth/api-key` - 创建 API Key
- `GET /api/v1/auth/api-keys` - 获取 API Key 列表
- `DELETE /api/v1/auth/api-key/{id}` - 撤销 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` - 获取最新行情
- `GET /api/v1/realtime/quotes` - 获取多个行情

### 告警管理接口
- `POST /api/v1/alert` - 创建告警
- `GET /api/v1/alert` - 获取告警列表
- `GET /api/v1/alert/{id}` - 获取告警详情
- `PUT /api/v1/alert/{id}` - 更新告警
- `DELETE /api/v1/alert/{id}` - 删除告警

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

## 本地开发

### 安装依赖

```bash
pip install -r requirements.txt
```

### 配置环境变量

创建 `.env` 文件：

```env
SECRET_KEY=your-secret-key
TIMESCALE_DB_URL=postgresql://postgres:postgres@localhost:5432/kline_data
SQLITE_DB_PATH=./data/config.db
REDIS_URL=redis://localhost:6379/0
```

### 启动服务

```bash
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

### 访问 API 文档

- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

## 运行测试

```bash
pytest tests/ -v --cov=app
```

## Docker 部署

```bash
# 构建镜像
docker build -t kline-backend .

# 运行容器
docker run -d -p 8000:8000 --name kline-backend kline-backend
```