# 期货股票数据统一平台 - 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 ``` --- ## 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 ``` **响应**: ```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 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 ``` **查询参数**: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | 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 ``` **查询参数**: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | symbol | string | 是 | 品种代码 | | period | string | 是 | 周期 | #### 2.3 获取品种列表 ```http GET /api/v1/kline/symbols Authorization: Bearer ``` **响应**: ```json { "code": 0, "message": "success", "data": ["IF2406", "IC2406", "IH2406", "SH0001"] } ``` #### 2.4 获取周期列表 ```http GET /api/v1/kline/periods Authorization: Bearer ``` **响应**: ```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 ``` **查询参数**: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | symbol | string | 是 | 品种代码 | #### 3.3 获取多个行情 ```http GET /api/v1/realtime/quotes Authorization: Bearer ``` **查询参数**: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | symbols | string | 是 | 品种代码列表 (逗号分隔) | --- ### 4. 告警管理模块 (Alert) #### 4.1 创建告警 ```http POST /api/v1/alert Authorization: Bearer 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 ``` **查询参数**: | 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | status | string | 否 | 状态 (active, triggered, disabled) | | page | int | 否 | 页码 (默认 1) | | page_size | int | 否 | 每页数量 (默认 10) | #### 4.3 更新告警 ```http PUT /api/v1/alert/{alert_id} Authorization: Bearer Content-Type: application/json ``` #### 4.4 删除告警 ```http DELETE /api/v1/alert/{alert_id} Authorization: Bearer ``` #### 4.5 禁用告警 ```http POST /api/v1/alert/{alert_id}/disable Authorization: Bearer ``` --- ### 5. 数据订阅模块 (Subscription) #### 5.1 创建订阅 ```http POST /api/v1/subscription Authorization: Bearer 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 ``` #### 5.3 取消订阅 ```http DELETE /api/v1/subscription/{subscription_id} Authorization: Bearer ``` --- ### 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 ``` #### 6.3 更新用户信息 ```http PUT /api/v1/user/{user_id} Authorization: Bearer Content-Type: application/json ``` #### 6.4 修改密码 ```http POST /api/v1/user/{user_id}/password Authorization: Bearer Content-Type: application/json ``` **请求体**: ```json { "old_password": "oldpass123", "new_password": "newpass123" } ``` --- ## 错误码说明 | 错误码 | 说明 | |--------|------| | 0 | 成功 | | 400 | 请求参数错误 | | 401 | 未授权/令牌过期 | | 403 | 权限不足 | | 404 | 资源不存在 | | 500 | 服务器内部错误 | ## 限流说明 - 默认限流：60 次/分钟 - 健康检查端点不限流 - 认证端点单独限流 ## 完整 API 文档 启动服务后访问：http://localhost:8000/docs