DataSync API

模块: data-sync

本模块包含 DataSyncService 相关的 API 端点，用于管理实时数据同步服务。

概述

DataSyncService 是一个常驻服务，负责：

• 引用计数订阅管理
• 自动补全历史数据
• 跨日自动结算
• 运行时轮询补漏
• WebSocket 日志推送

端点列表

• 🔍 GET /api/v1/data-sync/status - 获取服务状态
• ➕ POST /api/v1/data-sync/start - 启动服务
• 🛑 POST /api/v1/data-sync/stop - 停止服务
• ➕ POST /api/v1/data-sync/{symbol}/start - 启动标的同步
• 🛑 POST /api/v1/data-sync/{symbol}/stop - 停止标的同步
• ⚙️ PUT /api/v1/data-sync/config/lookback-days - 更新回看天数
• 📡 WebSocket /api/v1/data-sync/logs - 实时日志流

---

详细说明

🔍 Get Data Sync Status

获取 DataSyncService 当前状态

请求方式: GET /api/v1/data-sync/status

响应:

{
  "sync_state": "ready",
  "subscribed_symbols": ["AAPL.US", "TSLA.US"],
  "lookback_days": 30,
  "last_sync_time": "2025-09-16T12:00:00",
  "subscription_counts": {
    "AAPL.US": 2,
    "TSLA.US": 1
  }
}

响应字段:

字段	类型	说明
sync_state	string	同步状态: stopped/initializing/syncing/ready
subscribed_symbols	array	已订阅的股票代码列表
lookback_days	integer	历史数据回看天数
last_sync_time	string	最后同步时间 (ISO格式)
subscription_counts	object	各标的订阅计数

---

➕ Start Data Sync Service

启动 DataSyncService

请求方式: POST /api/v1/data-sync/start

认证: 需要登录

响应:

{
  "success": true,
  "message": "DataSyncService 启动成功",
  "sync_state": "ready"
}

说明:

• 如果服务已在运行中，返回当前状态
• 启动时自动执行：结算 fetching 状态、补全历史数据

---

🛑 Stop Data Sync Service

停止 DataSyncService

请求方式: POST /api/v1/data-sync/stop

响应:

{
  "success": true,
  "message": "DataSyncService 已停止"
}

---

➕ Start Symbol Sync

启动指定标的的数据同步

请求方式: POST /api/v1/data-sync/{symbol}/start

路径参数:

• symbol (string) - 必填 - 股票代码 (如: AAPL.US)

请求体:

{
  "symbols": ["AAPL.US"],
  "session_id": "session-123"
}

请求体参数:

字段	类型	必填	说明
symbols	array	否	要订阅的股票代码列表
session_id	string	是	会话 ID (用于引用计数)

认证: 需要登录

响应:

{
  "success": true,
  "message": "已订阅 AAPL.US",
  "sync_state": "ready"
}

说明:

• 如果服务未启动，会自动启动服务
• 使用引用计数管理订阅，同一 symbol 可被多个 session 订阅

---

🛑 Stop Symbol Sync

停止指定标的的数据同步

请求方式: POST /api/v1/data-sync/{symbol}/stop

路径参数:

• symbol (string) - 必填 - 股票代码 (如: AAPL.US)

请求体:

{
  "session_id": "session-123"
}

响应:

{
  "success": true,
  "message": "已取消订阅 AAPL.US，剩余 1 个订阅"
}

说明:

• 使用引用计数管理，只有当订阅计数为 0 时才真正取消订阅
• 单个 session 取消订阅不影响其他 session 的订阅

---

⚙️ Update Lookback Days

更新历史数据回看天数配置

请求方式: PUT /api/v1/data-sync/config/lookback-days

查询参数:

• days (integer) - 必填 - 新的回看天数 (1-365)

认证: 需要登录

响应:

{
  "success": true,
  "message": "回看天数已更新为 30 天",
  "lookback_days": 30
}

错误响应:

• 400: 回看天数必须在 1-365 之间

---

📡 WebSocket Data Sync Logs

DataSyncService 实时日志 WebSocket 端点

连接方式: WebSocket /api/v1/data-sync/logs?symbol=AAPL.US

查询参数:

• symbol (string) - 必填 - 股票代码

消息格式:

{
  "type": "log",
  "message": "检查最近 30 天数据完整性...",
  "timestamp": "2025-09-16T12:00:00.000Z",
  "sequence": 1
}

消息类型:

type	说明
log	一般日志
status	状态变更
error	错误信息
success	成功消息

说明:

• 连接后只推送增量日志，不推送历史日志
• 使用引用计数管理，断开连接不会立即停止日志推送

---

状态机

DataSyncService 的状态转换：

stateDiagram-v2
    [*] --> stopped
    stopped --> initializing: start()
    initializing --> ready: 初始化完成
    initializing --> stopped: 初始化失败
    ready --> syncing: 轮询补漏
    syncing --> ready: 同步完成
    ready --> stopped: stop()

状态	说明
stopped	服务已停止
initializing	初始化中（结算日历、补全数据）
syncing	同步中（实时订阅、定时轮询）
ready	就绪（可接收数据请求）

---

使用示例

启动同步并订阅标的

# 1. 订阅标的（会自动启动服务）
curl -X POST "http://localhost:8000/api/v1/data-sync/AAPL.US/start" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "my-session-1"}'

# 2. 查看状态
curl "http://localhost:8000/api/v1/data-sync/status"

# 3. 取消订阅
curl -X POST "http://localhost:8000/api/v1/data-sync/AAPL.US/stop" \
  -H "Content-Type: application/json" \
  -d '{"session_id": "my-session-1"}'

WebSocket 日志监听

const ws = new WebSocket('ws://localhost:8000/api/v1/data-sync/logs?symbol=AAPL.US');

ws.onmessage = (event) => {
  const log = JSON.parse(event.data);
  console.log(`[${log.type}] ${log.message}`);
};