amazing-data-service/docs/API.md

# AmazingData 金融数据服务平台 - API接口文档

## 基础信息

- **Base URL**: `http://localhost:8000/api/v1`
- **Content-Type**: `application/json`
- **认证方式**: JWT Bearer Token

## 认证相关

### 1. 用户登录
```http
POST /auth/login
Content-Type: application/json

{
    "username": "admin",
    "password": "admin123"
}
```

**响应**: 
```json
{
    "code": 200,
    "message": "success",
    "data": {
        "access_token": "eyJhbGciOiJIUzI1NiIs...",
        "token_type": "bearer",
        "expires_in": 86400
    }
}
```

### 2. 获取当前用户
```http
GET /auth/me
Authorization: Bearer {token}
```

## 配置管理

### 3. 获取SDK配置列表
```http
GET /configs/sdk
Authorization: Bearer {token}
```

### 4. 创建SDK配置
```http
POST /configs/sdk
Authorization: Bearer {token}
Content-Type: application/json

{
    "name": "银河证券生产环境",
    "username": "your_username",
    "password": "your_password",
    "host": "xxx.xxx.xxx.xxx",
    "port": 8080,
    "local_path": "./amazing_data_cache/",
    "is_default": true
}
```

### 5. 测试SDK连接
```http
POST /configs/sdk/{id}/test
Authorization: Bearer {token}
```

## 基础数据

### 6. 获取代码列表
```http
GET /base/codes?security_type=EXTRA_STOCK_A
Authorization: Bearer {token}
```

**参数**:
- `security_type`: 证券类型
  - `EXTRA_STOCK_A` - 沪深A股
  - `EXTRA_FUTURE` - 期货
  - `EXTRA_ETF` - ETF
  - `EXTRA_INDEX_A` - 指数

### 7. 获取证券信息
```http
GET /base/codes/{code}/info
Authorization: Bearer {token}
```

### 8. 获取交易日历
```http
GET /base/calendar?market=SH&start_date=20240101&end_date=20241231
Authorization: Bearer {token}
```

## 股票数据

### 9. 获取股票K线数据
```http
GET /stock/kline?codes=000001.SZ&start_date=20240101&end_date=20241231&period=daily
Authorization: Bearer {token}
```

**参数**:
- `codes`: 股票代码，多个用逗号分隔
- `start_date`: 开始日期 (YYYYMMDD)
- `end_date`: 结束日期 (YYYYMMDD)
- `period`: 周期 (daily, min1, min5, min15, min30, min60)

**响应**:
```json
{
    "code": 200,
    "message": "success",
    "data": {
        "000001.SZ": [
            {
                "trade_date": "2024-01-02",
                "open": 10.50,
                "high": 10.80,
                "low": 10.40,
                "close": 10.65,
                "volume": 1234567,
                "amount": 12845678.90
            }
        ]
    }
}
```

### 10. 获取股票K线图数据
```http
GET /stock/kline/{code}/chart?start_date=20240101&end_date=20241231&period=daily
Authorization: Bearer {token}
```

**响应** (ECharts格式):
```json
{
    "code": 200,
    "message": "success",
    "data": {
        "categoryData": ["2024-01-02", "2024-01-03", ...],
        "values": [
            [10.50, 10.80, 10.40, 10.65, 1234567],
            [10.65, 10.70, 10.50, 10.60, 987654],
            ...
        ],
        "volumes": [
            [0, 1234567, 1],
            [1, 987654, -1],
            ...
        ]
    }
}
```

### 11. 批量获取股票K线
```http
POST /stock/kline/batch
Authorization: Bearer {token}
Content-Type: application/json

{
    "codes": ["000001.SZ", "600000.SH"],
    "start_date": "20240101",
    "end_date": "20241231",
    "period": "daily"
}
```

## 期货数据

### 12. 获取期货K线数据
```http
GET /future/kline?codes=IF2501.CFE&start_date=20240101&end_date=20241231&period=daily
Authorization: Bearer {token}
```

### 13. 获取期货K线图数据
```http
GET /future/kline/{code}/chart?start_date=20240101&end_date=20241231&period=daily
Authorization: Bearer {token}
```

## 实时数据

### 14. 获取最新快照
```http
GET /realtime/snapshot?codes=000001.SZ,600000.SH
Authorization: Bearer {token}
```

### 15. 开始实时订阅
```http
POST /realtime/subscribe
Authorization: Bearer {token}
Content-Type: application/json

{
    "codes": ["000001.SZ", "600000.SH"],
    "types": ["snapshot"],
    "callback_url": "ws://localhost:8000/api/v1/realtime/stream"
}
```

### 16. WebSocket实时数据流
```
WS /realtime/stream?codes=000001.SZ,600000.SH&types=snapshot
Authorization: Bearer {token}
```

**消息格式**:
```json
{
    "type": "snapshot",
    "code": "000001.SZ",
    "data": {
        "trade_time": "2025-01-15T10:30:00",
        "last": 10.50,
        "open": 10.30,
        "high": 10.60,
        "low": 10.20,
        "volume": 1234567,
        "amount": 12845678.90
    }
}
```

## 财务数据

### 17. 获取资产负债表
```http
GET /finance/balance-sheet?codes=000001.SZ&start_date=20240930&end_date=20240930
Authorization: Bearer {token}
```

**响应**:
```json
{
    "code": 200,
    "message": "success",
    "data": {
        "000001.SZ": [
            {
                "report_date": "2024-09-30",
                "total_assets": 123456789012.34,
                "total_cur_assets": 98765432109.87,
                "total_liab": 87654321098.76,
                "tot_share_equity": 35802467913.58
            }
        ]
    }
}
```

### 18. 获取现金流量表
```http
GET /finance/cash-flow?codes=000001.SZ&start_date=20240930&end_date=20240930
Authorization: Bearer {token}
```

### 19. 获取利润表
```http
GET /finance/income?codes=000001.SZ&start_date=20240930&end_date=20240930
Authorization: Bearer {token}
```

### 20. 获取业绩快报
```http
GET /finance/profit-express?codes=000001.SZ&start_date=20240930&end_date=20240930
Authorization: Bearer {token}
```

### 21. 获取业绩预告
```http
GET /finance/profit-notice?codes=000001.SZ&start_date=20240930&end_date=20240930
Authorization: Bearer {token}
```

## 股东数据

### 22. 获取十大股东
```http
GET /shareholder/top10?codes=000001.SZ&start_date=20240930&end_date=20240930
Authorization: Bearer {token}
```

### 23. 获取股东户数
```http
GET /shareholder/count?codes=000001.SZ&start_date=20240930&end_date=20240930
Authorization: Bearer {token}
```

### 24. 获取股本结构
```http
GET /shareholder/equity?codes=000001.SZ&start_date=20240930&end_date=20240930
Authorization: Bearer {token}
```

## 融资融券

### 25. 获取融资融券汇总
```http
GET /margin/summary?start_date=20240101&end_date=20241231
Authorization: Bearer {token}
```

### 26. 获取融资融券明细
```http
GET /margin/detail?codes=000001.SZ&start_date=20240101&end_date=20241231
Authorization: Bearer {token}
```

## 指数数据

### 27. 获取指数成分股
```http
GET /index/constituents?codes=000300.SH
Authorization: Bearer {token}
```

### 28. 获取指数权重
```http
GET /index/weights?codes=000300.SH&start_date=20240101&end_date=20241231
Authorization: Bearer {token}
```

## ETF数据

### 29. 获取ETF申赎数据
```http
GET /etf/pcf?codes=510050.SH
Authorization: Bearer {token}
```

### 30. 获取ETF份额
```http
GET /etf/share?codes=510050.SH&start_date=20240101&end_date=20241231
Authorization: Bearer {token}
```

## 可转债数据

### 31. 获取可转债发行数据
```http
GET /kzz/issuance?codes=128XXX.SZ
Authorization: Bearer {token}
```

## 缓存管理

### 32. 检测缺失数据
```http
POST /cache/detect-missing
Authorization: Bearer {token}
Content-Type: application/json

{
    "security_type": "stock",
    "period_type": "daily",
    "start_date": "20240101",
    "end_date": "20241231",
    "code_list": ["000001.SZ", "600000.SH"]
}
```

**响应**:
```json
{
    "code": 200,
    "message": "success",
    "data": {
        "task_id": 1,
        "total_codes": 2,
        "missing_codes": [
            {
                "code": "000001.SZ",
                "missing_dates": [
                    {
                        "date": "2024-06-01",
                        "expected": 1,
                        "actual": 0,
                        "missing_ratio": 1.0
                    }
                ]
            }
        ]
    }
}
```

### 33. 批量缓存数据
```http
POST /cache/batch-cache
Authorization: Bearer {token}
Content-Type: application/json

{
    "security_type": "stock",
    "period_type": "daily",
    "start_date": "20240101",
    "end_date": "20241231",
    "code_list": ["000001.SZ", "600000.SH"]
}
```

### 34. 获取缓存任务列表
```http
GET /cache/tasks?page=1&page_size=20
Authorization: Bearer {token}
```

### 35. 获取缓存任务详情
```http
GET /cache/tasks/{task_id}
Authorization: Bearer {token}
```

### 36. 取消缓存任务
```http
DELETE /cache/tasks/{task_id}
Authorization: Bearer {token}
```

### 37. 获取代码缓存状态
```http
GET /cache/status/{code}?security_type=stock&period_type=daily
Authorization: Bearer {token}
```

**响应**:
```json
{
    "code": 200,
    "message": "success",
    "data": {
        "code": "000001.SZ",
        "security_type": "stock",
        "period_type": "daily",
        "record_count": 242,
        "min_date": "2024-01-02",
        "max_date": "2024-12-31",
        "missing_ratio": 0.0
    }
}
```

## 测试中心

### 38. 获取测试分类
```http
GET /test/categories
Authorization: Bearer {token}
```

**响应**:
```json
{
    "code": 200,
    "message": "success",
    "data": [
        {"key": "base_data", "name": "基础数据"},
        {"key": "stock", "name": "股票数据"},
        {"key": "future", "name": "期货数据"},
        {"key": "realtime", "name": "实时数据"},
        {"key": "finance", "name": "财务数据"},
        {"key": "shareholder", "name": "股东数据"},
        {"key": "margin", "name": "融资融券"},
        {"key": "index", "name": "指数数据"},
        {"key": "etf", "name": "ETF数据"},
        {"key": "kzz", "name": "可转债数据"}
    ]
}
```

### 39. 获取接口列表
```http
GET /test/endpoints?category=stock
Authorization: Bearer {token}
```

### 40. 执行单个接口测试
```http
POST /test/run
Authorization: Bearer {token}
Content-Type: application/json

{
    "endpoint": "/api/v1/stock/kline",
    "method": "GET",
    "params": {
        "codes": "000001.SZ",
        "start_date": "20240101",
        "end_date": "20241231",
        "period": "daily"
    }
}
```

### 41. 执行全部接口测试
```http
POST /test/run-all
Authorization: Bearer {token}
Content-Type: application/json

{
    "categories": ["stock", "future", "finance"]
}
```

### 42. 获取测试历史
```http
GET /test/history?page=1&page_size=20
Authorization: Bearer {token}
```

## 错误码

| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 参数错误 |
| 401 | 未授权 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
| 1001 | SDK连接失败 |
| 1002 | 数据不存在 |
| 1003 | 任务执行失败 |

## 数据类型说明

### K线数据结构

| 字段 | 类型 | 说明 |
|------|------|------|
| trade_date | string | 交易日期 (YYYY-MM-DD) |
| trade_datetime | string | 交易时间 (YYYY-MM-DD HH:MM:SS) |
| open | number | 开盘价 |
| high | number | 最高价 |
| low | number | 最低价 |
| close | number | 收盘价 |
| volume | number | 成交量 |
| amount | number | 成交金额 |

### 期货K线额外字段

| 字段 | 类型 | 说明 |
|------|------|------|
| settle | number | 结算价 |
| open_interest | number | 持仓量 |

### 快照数据结构

| 字段 | 类型 | 说明 |
|------|------|------|
| code | string | 证券代码 |
| trade_time | string | 交易时间 |
| last | number | 最新价 |
| open | number | 开盘价 |
| high | number | 最高价 |
| low | number | 最低价 |
| volume | number | 成交量 |
| amount | number | 成交金额 |
| ask_price1-5 | number | 卖1-5价格 |
| ask_volume1-5 | number | 卖1-5数量 |
| bid_price1-5 | number | 买1-5价格 |
| bid_volume1-5 | number | 买1-5数量 |

---

**文档版本**: 1.0
**更新日期**: 2025年