fin_data_unify_plat/API.md

# 期货股票数据统一平台 - API 文档

## 基础信息

- **Base URL**: `/api/v1`
- **认证方式**: JWT Bearer Token
- **数据格式**: JSON

## 认证

### 获取令牌

大多数 API 端点需要认证。首先通过登录接口获取访问令牌：

```bash
POST /api/v1/auth/login
Content-Type: application/x-www-form-urlencoded

username=admin&password=admin123
```

响应：
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "Bearer",
    "expires_in": 3600
  }
}
```

### 使用令牌

在请求头中添加 Authorization：

```bash
Authorization: Bearer <access_token>
```

---

## API 端点

### 1. 认证模块 (Auth)

#### 1.1 用户登录
```http
POST /api/v1/auth/login
Content-Type: application/x-www-form-urlencoded
```

**请求参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| username | string | 是 | 用户名 |
| password | string | 是 | 密码 |

**响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "access_token": "string",
    "refresh_token": "string",
    "token_type": "Bearer",
    "expires_in": 3600
  }
}
```

#### 1.2 刷新令牌
```http
POST /api/v1/auth/refresh
Content-Type: application/json
```

**请求体**:
```json
{
  "refresh_token": "string"
}
```

#### 1.3 获取当前用户
```http
GET /api/v1/auth/me
Authorization: Bearer <token>
```

**响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "role": "admin"
  }
}
```

#### 1.4 创建 API Key
```http
POST /api/v1/auth/api-key
Authorization: Bearer <token>
Content-Type: application/json
```

**请求体**:
```json
{
  "name": "My API Key",
  "expires_days": 30
}
```

---

### 2. K 线数据模块 (Kline)

#### 2.1 获取 K 线数据
```http
GET /api/v1/kline/data
Authorization: Bearer <token>
```

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| symbol | string | 是 | 品种代码 (如 IF2406) |
| period | string | 是 | 周期 (1m, 5m, 1h, 1d) |
| start | datetime | 是 | 开始时间 (ISO 8601) |
| end | datetime | 是 | 结束时间 (ISO 8601) |

**响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": [
    {
      "time": "2024-01-01T10:00:00Z",
      "open": 4000.0,
      "high": 4050.0,
      "low": 3980.0,
      "close": 4020.0,
      "volume": 1000,
      "amount": 4000000.0,
      "open_interest": 500
    }
  ]
}
```

#### 2.2 获取最新 K 线
```http
GET /api/v1/kline/latest
Authorization: Bearer <token>
```

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| symbol | string | 是 | 品种代码 |
| period | string | 是 | 周期 |

#### 2.3 获取品种列表
```http
GET /api/v1/kline/symbols
Authorization: Bearer <token>
```

**响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": ["IF2406", "IC2406", "IH2406", "SH0001"]
}
```

#### 2.4 获取周期列表
```http
GET /api/v1/kline/periods
Authorization: Bearer <token>
```

**响应**:
```json
{
  "code": 0,
  "message": "success",
  "data": ["1m", "5m", "15m", "30m", "1h", "4h", "1d", "1w"]
}
```

---

### 3. 实时行情模块 (Realtime)

#### 3.1 WebSocket 连接
```
ws://localhost:8000/api/v1/realtime/ws
```

**连接后发送订阅消息**:
```json
{
  "action": "subscribe",
  "symbols": ["IF2406", "IC2406"]
}
```

**取消订阅**:
```json
{
  "action": "unsubscribe",
  "symbols": ["IF2406"]
}
```

**接收行情数据**:
```json
{
  "symbol": "IF2406",
  "price": 4020.5,
  "change": 0.5,
  "change_percent": 0.012,
  "volume": 1000,
  "timestamp": "2024-01-01T10:00:00Z"
}
```

#### 3.2 获取实时行情
```http
GET /api/v1/realtime/quote
Authorization: Bearer <token>
```

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| symbol | string | 是 | 品种代码 |

#### 3.3 获取多个行情
```http
GET /api/v1/realtime/quotes
Authorization: Bearer <token>
```

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| symbols | string | 是 | 品种代码列表 (逗号分隔) |

---

### 4. 告警管理模块 (Alert)

#### 4.1 创建告警
```http
POST /api/v1/alert
Authorization: Bearer <token>
Content-Type: application/json
```

**请求体**:
```json
{
  "symbol": "IF2406",
  "condition_type": "greater_than",
  "condition_value": 4000.0,
  "alert_type": "price"
}
```

**condition_type 可选值**:
- `greater_than`: 大于
- `less_than`: 小于
- `equals`: 等于

**alert_type 可选值**:
- `price`: 价格告警
- `percent_change`: 涨跌幅告警

#### 4.2 获取告警列表
```http
GET /api/v1/alert
Authorization: Bearer <token>
```

**查询参数**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| status | string | 否 | 状态 (active, triggered, disabled) |
| page | int | 否 | 页码 (默认 1) |
| page_size | int | 否 | 每页数量 (默认 10) |

#### 4.3 更新告警
```http
PUT /api/v1/alert/{alert_id}
Authorization: Bearer <token>
Content-Type: application/json
```

#### 4.4 删除告警
```http
DELETE /api/v1/alert/{alert_id}
Authorization: Bearer <token>
```

#### 4.5 禁用告警
```http
POST /api/v1/alert/{alert_id}/disable
Authorization: Bearer <token>
```

---

### 5. 数据订阅模块 (Subscription)

#### 5.1 创建订阅
```http
POST /api/v1/subscription
Authorization: Bearer <token>
Content-Type: application/json
```

**请求体**:
```json
{
  "symbol": "IF2406",
  "period": "5m",
  "subscription_type": "kline"
}
```

**subscription_type 可选值**:
- `kline`: K 线数据订阅
- `realtime`: 实时行情订阅

#### 5.2 获取订阅列表
```http
GET /api/v1/subscription
Authorization: Bearer <token>
```

#### 5.3 取消订阅
```http
DELETE /api/v1/subscription/{subscription_id}
Authorization: Bearer <token>
```

---

### 6. 用户管理模块 (User)

#### 6.1 创建用户
```http
POST /api/v1/user
Content-Type: application/json
```

**请求体**:
```json
{
  "username": "newuser",
  "password": "password123",
  "email": "user@example.com"
}
```

#### 6.2 获取用户列表 (仅管理员)
```http
GET /api/v1/user
Authorization: Bearer <token>
```

#### 6.3 更新用户信息
```http
PUT /api/v1/user/{user_id}
Authorization: Bearer <token>
Content-Type: application/json
```

#### 6.4 修改密码
```http
POST /api/v1/user/{user_id}/password
Authorization: Bearer <token>
Content-Type: application/json
```

**请求体**:
```json
{
  "old_password": "oldpass123",
  "new_password": "newpass123"
}
```

---

## 错误码说明

| 错误码 | 说明 |
|--------|------|
| 0 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权/令牌过期 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

## 限流说明

- 默认限流：60 次/分钟
- 健康检查端点不限流
- 认证端点单独限流

## 完整 API 文档

启动服务后访问：http://localhost:8000/docs