market-data-service/docs/admin-api-quick-reference.md

# 管理后台 API 速查表

**基础URL**: `http://localhost:8080`

**认证方式**: `X-Admin-Token` Header（当前版本暂未强制验证）

---

## 系统管理

### 获取系统状态
```http
GET /v1/admin/system/status
```

### 热加载配置
```http
POST /v1/admin/system/reload
Content-Type: application/json

{
  "config_type": "source"  // server|database|redis|source
}
```

### 重启服务
```http
POST /v1/admin/system/restart
Content-Type: application/json

{
  "force": false
}
```

---

## 配置管理

### 获取配置列表
```http
GET /v1/admin/config?type={config_type}

# 示例
GET /v1/admin/config?type=server
GET /v1/admin/config?type=database
GET /v1/admin/config?type=redis
GET /v1/admin/config?type=source
```

### 更新配置
```http
PUT /v1/admin/config
Content-Type: application/json

# 服务器配置
{
  "type": "server",
  "items": {
    "port": 8080,
    "mode": "release",
    "api_key": "new-key"
  }
}

# 数据库配置
{
  "type": "database",
  "items": {
    "host": "localhost",
    "port": 5432,
    "user": "postgres",
    "password": "password",
    "database": "marketdata"
  }
}

# 数据源配置
{
  "type": "source",
  "items": {
    "stock_active": "tushare",
    "futures_active": "tushare"
  }
}
```

---

## 适配器管理

### 获取适配器列表
```http
GET /v1/admin/adapters
```

### 启用/禁用适配器
```http
POST /v1/admin/adapters/toggle
Content-Type: application/json

{
  "name": "tushare",
  "enable": true
}
```

### 更新适配器配置
```http
PUT /v1/admin/adapters/config
Content-Type: application/json

{
  "name": "tushare",
  "config": {
    "token": "your-new-token",
    "base_url": "https://api.tushare.pro"
  }
}
```

---

## 接口测试

### 获取API测试列表
```http
GET /v1/admin/tests/api
```

**测试用例ID列表**:
| ID | 名称 | 说明 |
|----|------|------|
| `stock_klines` | 查询股票K线 | GET /v1/stock/klines/{symbol} |
| `stock_symbols` | 查询股票列表 | GET /v1/stock/symbols |
| `stock_batch` | 批量查询股票K线 | POST /v1/stock/klines/batch |
| `stock_calendar` | 查询交易日历 | GET /v1/stock/trading-dates |
| `futures_klines` | 查询期货K线 | GET /v1/futures/klines/{symbol} |
| `futures_symbols` | 查询期货列表 | GET /v1/futures/symbols |
| `futures_batch` | 批量查询期货K线 | POST /v1/futures/klines/batch |
| `futures_contracts` | 查询合约列表 | GET /v1/futures/contracts |
| `futures_calendar` | 查询期货交易日历 | GET /v1/futures/trading-dates |
| `admin_health` | 健康检查 | GET /v1/admin/health |
| `admin_source_status` | 数据源状态 | GET /v1/admin/source/status |

### 执行API测试
```http
POST /v1/admin/tests/api/run
Content-Type: application/json

{
  "id": "stock_klines",
  "params": {
    "symbol": "000001.SZ",
    "start": "20260201",
    "end": "20260307",
    "freq": "1d"
  }
}
```

### 获取WebSocket测试列表
```http
GET /v1/admin/tests/ws
```

**测试用例ID列表**:
| ID | 名称 | 说明 |
|----|------|------|
| `ws_subscribe_stock` | 订阅股票行情 | subscribe [000001.SZ] |
| `ws_subscribe_futures` | 订阅期货行情 | subscribe [CU2504.SHFE] |
| `ws_subscribe_multi` | 批量订阅 | subscribe 多标的 |
| `ws_unsubscribe` | 取消订阅 | unsubscribe [000001.SZ] |

### 执行WebSocket测试
```http
POST /v1/admin/tests/ws/run
Content-Type: application/json

{
  "id": "ws_subscribe_stock",
  "symbols": ["000001.SZ", "000002.SZ"]
}
```

### 获取测试历史
```http
GET /v1/admin/tests/history?type={type}&limit={limit}

# 示例
GET /v1/admin/tests/history              # 全部历史
GET /v1/admin/tests/history?type=api     # API测试历史
GET /v1/admin/tests/history?type=ws      # WebSocket测试历史
GET /v1/admin/tests/history?limit=50     # 最近50条
```

---

## 响应格式

### 成功响应
```json
{
  "code": 0,
  "message": "success",
  "data": { ... }
}
```

### 错误响应
```json
{
  "code": 500,
  "message": "错误描述",
  "detail": "详细错误信息"
}
```

---

## 使用示例

### cURL 示例

```bash
# 获取系统状态
curl "http://localhost:8080/v1/admin/system/status"

# 热加载配置
curl -X POST "http://localhost:8080/v1/admin/system/reload" \
  -H "Content-Type: application/json" \
  -d '{"config_type": "source"}'

# 获取适配器列表
curl "http://localhost:8080/v1/admin/adapters"

# 启用适配器
curl -X POST "http://localhost:8080/v1/admin/adapters/toggle" \
  -H "Content-Type: application/json" \
  -d '{"name": "tushare", "enable": true}'

# 执行API测试
curl -X POST "http://localhost:8080/v1/admin/tests/api/run" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "stock_klines",
    "params": {"symbol": "000001.SZ", "start": "20260201", "end": "20260307"}
  }'
```

---

## 管理后台页面

直接访问：`http://localhost:8080/admin`

页面功能：
- 系统概览：实时状态监控
- 配置管理：可视化配置编辑
- 数据源适配：适配器管理
- 接口测试：一键测试所有接口