# 数据缓冲平台

基于 FastAPI + SQLite + APScheduler 的行情数据缓冲服务。

## 功能

1. **数据采集缓存** - 复用现有采集脚本，自动缓存到 SQLite
2. **批量获取接口** - 指定品种+周期，批量拉取并缓存
3. **定时任务管理** - 创建/启动/停止/删除自动轮询任务
4. **最新数据接口** - 从缓存中快速获取最新数据

## 快速启动

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

# 启动服务（默认端口 8600）
python -m app.main

# 或指定端口
BUFFER_PORT=9000 python -m app.main
```

## API 接口

### 数据接口 `/api/v1/data`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/data/batch-fetch` | 批量获取并缓存（智能缓存） |
| GET | `/data/latest/{symbol}` | 从缓存获取最新数据 |
| GET | `/data/latest/{symbol}/{period}` | 获取指定周期最新数据 |
| GET | `/data/cache-status/{symbol}` | 查看缓存状态 |

### 品种配置接口 `/api/v1/config`

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/config` | 获取当前品种配置 |
| POST | `/config/upload` | 上传品种配置文件（JSON） |
| POST | `/config/batch-fetch-all` | 根据配置批量获取所有品种数据 |
| POST | `/config/batch-tasks` | 根据配置批量创建定时任务 |

### 定时任务接口 `/api/v1/tasks`

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/tasks` | 创建并启动定时任务 |
| GET | `/tasks` | 列出所有任务 |
| POST | `/tasks/{id}/start` | 启动任务 |
| POST | `/tasks/{id}/stop` | 停止任务 |
| POST | `/tasks/{id}/update-interval` | 更新轮询间隔 |
| DELETE | `/tasks/{id}` | 删除任务 |

### UI 页面

| 路径 | 说明 |
|------|------|
| `/ui` | 品种配置管理页面（上传文件、批量获取、批量任务） |
| `/docs` | Swagger API 文档 |

### 使用示例

```bash
# 启动服务（默认端口 8600）
cd buffer_platform
python -m app.main

# 访问 UI 管理页面
open http://localhost:8600/ui

# 上传品种配置文件
curl -X POST http://localhost:8600/api/v1/config/upload \
  -F "file=@symbols_config.json"

# 查看当前配置
curl http://localhost:8600/api/v1/config

# 根据配置批量获取所有品种数据
curl -X POST 'http://localhost:8600/api/v1/config/batch-fetch-all?periods=5min,15min,60min&data_type=futures'

# 根据配置批量创建定时任务（每5分钟自动采集）
curl -X POST 'http://localhost:8600/api/v1/config/batch-tasks?periods=5min,15min,60min&interval_seconds=300&data_type=futures'

# 批量获取（手动指定品种）
curl -X POST http://localhost:8600/api/v1/data/batch-fetch \
  -H "Content-Type: application/json" \
  -d '{"symbols": ["SN2504", "AG2506"], "periods": ["5min", "15min"]}'

# 获取最新缓存
curl http://localhost:8600/api/v1/data/latest/SN2504

# 创建单个定时任务
curl -X POST http://localhost:8600/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{"symbol": "SN2504", "periods": ["5min", "15min", "60min"], "interval_seconds": 300}'
```

## 项目结构

```
buffer_platform/
├── app/
│   ├── main.py              # FastAPI 入口
│   ├── config.py             # 配置
│   ├── database.py           # 数据库连接
│   ├── models.py             # ORM 模型
│   ├── schemas.py            # 请求/响应模型
│   ├── api/
│   │   ├── data.py           # 数据接口
│   │   └── tasks.py          # 任务接口
│   └── services/
│       ├── collector.py      # 采集服务
│       ├── cache.py          # 缓存服务
│       └── scheduler.py      # 调度服务
├── data/                     # SQLite 数据库文件
└── requirements.txt
```