# Arbitrage Engine API Contracts（前端使用接口契约）

> 本文从“前端页面需要什么数据”的角度，描述各接口的请求参数和响应结构。  
> 后端实现细节和数据库字段说明仍以 `docs/arbitrage-engine-full-spec.md` 为准；如有冲突，以 full-spec 为权威。

约定：

- 所有接口路径均以 `/api` 开头；
- 响应示例使用 TypeScript 风格的类型定义 + 简单字段说明；
- 未特别说明时，时间戳字段单位为毫秒（ms）。

---

## 1. 首页 `/` 仪表盘相关接口

### 1.1 GET /api/rates

用途：  
首页顶部两张资金费率卡片（BTC/ETH）的数据源，用于展示当前资金费率、标记价格、指数价格等。

请求：

- Method: `GET`
- Query: 无

响应示例：

```ts
type RatesResponse = {
  BTC: {
    symbol: "BTCUSDT";
    markPrice: number;       // 标记价格
    indexPrice: number;      // 指数价格
    lastFundingRate: number; // 最新资金费率（例：0.0001 = 0.01%）
    nextFundingTime: number; // 下次资金费率结算时间（毫秒时间戳）
    timestamp: number;       // 当前数据时间（毫秒时间戳）
  };
  ETH: {
    symbol: "ETHUSDT";
    markPrice: number;
    indexPrice: number;
    lastFundingRate: number;
    nextFundingTime: number;
    timestamp: number;
  };
};
```

被使用位置：

- 首页 `/`：`RateCard` 组件。

### 1.2 GET /api/stats

用途：  
首页中部三张“套利统计”卡片（BTC 套利 / ETH 套利 / 50/50 组合）的数据源。

请求：

- Method: `GET`
- Query: 无

响应示例：

```ts
type StatsResponse = {
  BTC: {
    mean7d: number;      // 过去7天平均日收益率（例如 0.0005 = 0.05%/d）
    annualized: number;  // 折算年化收益率（百分数，例如 12.34）
  };
  ETH: {
    mean7d: number;
    annualized: number;
  };
  combo: {
    mean7d: number;
    annualized: number;
  };
};
```

被使用位置：

- 首页 `/`：三张 `StatsCard`。

### 1.3 GET /api/history

用途：  
首页的“历史费率走势（过去7天）”折线图以及“历史费率明细（最近30条）”表格。

请求：

- Method: `GET`
- Query: 可选（full-spec 中定义），前端通常使用默认 7 天窗口。

响应示例（简化版）：

```ts
type HistoryPoint = {
  fundingTime: number; // 资金费率结算时间（秒或毫秒时间戳，详见实现）
  fundingRate: number; // 当前时间点资金费率（小数，例：0.0001 = 0.01%）
  timestamp: string;   // ISO8601 时间字符串，例如 "2026-03-10T15:00:00Z"
};

type HistoryResponse = {
  BTC: HistoryPoint[];
  ETH: HistoryPoint[];
};
```

被使用位置：

- 首页 `/`：
  - 将 BTC/ETH 的 `fundingRate` 转成百分比，绘制 7 天折线图；
  - 截取最近 30 条记录，填充历史明细表（时间 + BTC% + ETH%）。

### 1.4 GET /api/signals/history

用途：  
首页右下角“信号历史”表格，用于展示最近触发的套利机会（满足一定年化阈值）。

请求：

- Method: `GET`
- Query: 可选，例如 `limit`，具体见 full-spec。

响应示例：

```ts
type SignalHistoryItem = {
  id: number;
  symbol: string;          // 币种简称，如 "BTC" / "ETH"
  rate: number;            // 当时资金费率（小数）
  annualized: number;      // 触发时对应的年化收益率（百分数）
  sent_at: string;         // 发送时间（ISO8601 字符串）
  message: string;         // 文本说明，用于展示/推送
};

type SignalsHistoryResponse = {
  items: SignalHistoryItem[];
};
```

被使用位置：

- 首页 `/`：信号历史表，显示时间 / 币种 / 年化。

### 1.5 GET /api/stats/ytd

用途：  
为 `RateCard` 等组件提供 YTD（年初至今）统计，用于资金费率卡片上的补充信息。

请求：

- Method: `GET`
- Query: 无

响应示例（示意）：

```ts
type YtdStats = {
  mean: number;        // 年初至今平均日收益率
  annualized: number;  // 折算年化
  days: number;        // 统计天数
};

type YtdStatsResponse = {
  BTC: YtdStats;
  ETH: YtdStats;
};
```

被使用位置：

- 首页 `/`：`RateCard` 内部展示 YTD 指标。

### 1.6 GET /api/kline

用途：  
首页 K 线卡片，用于绘制资金费率 K 线和标记价格 K 线。

请求：

- Method: `GET`
- Query：

```ts
{
  symbol: "BTC" | "ETH";     // 前端传 BTC/ETH，无 USDT
  interval: string;          // "1m" | "5m" | "30m" | "1h" | "4h" | "8h" | "1d" | "1w" | "1M"
  limit?: number;            // 可选，K 线数量
}
```

响应示例：

```ts
type KBar = {
  time: number;        // K 线起始时间（秒级时间戳或 ms，前端按 full-spec 与实现处理）
  open: number;
  high: number;
  low: number;
  close: number;
  price_open: number;  // 标记价格的 OHLC
  price_high: number;
  price_low: number;
  price_close: number;
};

type KlineResponse = {
  symbol: string;      // "BTC"
  interval: string;    // 请求时的 interval
  count: number;       // 实际返回的 bar 数量
  data: KBar[];
};
```

被使用位置：

- 首页 `/`：`MiniKChart` 组件两次使用：
  - mode="rate"：使用 `open/high/low/close` 作为资金费率蜡烛；
  - mode="price"：使用 `price_*` 作为价格蜡烛。

---

## 2. /trades 成交流页面接口

### 2.1 GET /api/trades/latest

用途：  
`/trades` 页面左侧“实时成交”表格的数据源，拉取最近若干条逐笔成交。

请求：

- Method: `GET`
- Query：

```ts
{
  symbol: "BTC" | "ETH" | "XRP" | "SOL";  // 币种简称
  limit?: number;                         // 返回条数，默认 20
}
```

响应示例：

```ts
type LatestTradesResponse = {
  data: Array<{
    agg_id: number;        // Binance aggTrade ID
    price: number;         // 成交价格
    qty: number;           // 成交量（合约单位）
    time_ms: number;       // 成交时间（毫秒）
    is_buyer_maker: 0 | 1; // 0=主动买(多方), 1=主动卖(空方)
  }>;
};
```

被使用位置：

- `/trades`：`LiveTrades` 组件。

### 2.2 GET /api/trades/summary

用途：  
`/trades` 页面右侧“成交流分析”图表的数据源，按时间窗口聚合买/卖量、Delta、VWAP 等信息。

请求：

- Method: `GET`
- Query：

```ts
{
  symbol: "BTC" | "ETH" | "XRP" | "SOL";
  start_ms: number;       // 统计窗口起始时间（毫秒）
  end_ms: number;         // 统计窗口结束时间（毫秒）
  interval: "1m" | "5m" | "15m" | "1h";  // 聚合粒度
}
```

响应示例：

```ts
type TradeSummaryBar = {
  time_ms: number;    // 时间段起始时间（毫秒）
  buy_vol: number;    // 该段主动买入量
  sell_vol: number;   // 该段主动卖出量
  delta: number;      // buy_vol - sell_vol
  total_vol: number;  // 总成交量
  trade_count: number;// 成交笔数
  vwap: number;       // 成交量加权平均价
  max_qty: number;    // 单笔最大成交量
};

type TradeSummaryResponse = {
  data: TradeSummaryBar[];
};
```

被使用位置：

- `/trades`：`FlowAnalysis` 组件，绘制 Delta + 价格双轴图和“主动买 vs 主动卖”面积图，并算总买卖量、买方占比等摘要。

---

## 3. /live 实盘交易页面接口

> 本节仅列出被 `/live` 页面使用的接口，详细业务规则参考 full-spec。

### 3.1 GET /api/live/risk-status

用途：  
L0 风险条和 L6 风控状态，用于展示日内 R 使用情况、熔断状态、规则是否触发等。

请求：

- Method: `GET`
- Query: 无

响应字段示意：

```ts
type LiveRiskStatus = {
  status: "normal" | "warning" | "circuit_break" | string; // 当前风险状态
  today_realized_r: number;    // 今日已实现收益R
  today_unrealized_r: number;  // 今日未实现收益R
  today_total_r: number;       // 今日总 R（含未实现）
  consecutive_losses: number;  // 连续亏损笔数
  block_new_entries: boolean;  // 是否禁止新开仓
  reduce_only: boolean;        // 是否只减仓
  circuit_break_reason?: string | null; // 熔断原因（如有）
  auto_resume_time?: number | null;     // 预计自动恢复时间（秒或毫秒时间戳，详见实现）
};
```

被使用位置：

- `/live`：`L0_RiskBar`、`L6_RiskStatus`。

### 3.2 GET /api/live/reconciliation

用途：  
对账与清算距离计算，确保本地持仓与交易所真实持仓一致。

请求：

- Method: `GET`

响应字段示意：

```ts
type ReconPositionLocal = {
  id: number;
  symbol: string;       // 如 "BTCUSDT"
  direction: "LONG"|"SHORT";
  entry_price: number;
};

type ReconPositionExchange = {
  symbol: string;
  direction: "LONG"|"SHORT";
  amount: number;
  mark_price: number;
  liquidation_price: number;
};

type ReconDiff = {
  symbol: string;
  severity: "warn" | "critical" | string;
  detail: string;
};

type ReconciliationStatus = {
  status: "ok" | "mismatch" | string;
  local_positions: ReconPositionLocal[];
  exchange_positions: ReconPositionExchange[];
  local_orders: number;
  exchange_orders: number;
  diffs: ReconDiff[];
};
```

被使用位置：

- `/live`：`L0_RiskBar`（对账状态）、`L3_Positions`（清算距离）、`L5_Reconciliation`。

### 3.3 GET /api/live/account

用途：  
实盘账户整体情况，包括权益、保证金使用、今日 PnL 等。

请求：

- Method: `GET`

响应字段示意：

```ts
type LiveAccount = {
  equity: number;             // 总账户权益
  available_margin: number;   // 可用保证金
  used_margin: number;        // 已用保证金
  effective_leverage: number; // 有效杠杆
  today_realized_r: number;
  today_realized_usdt: number;
  // 其它字段按实现扩展
};
```

被使用位置：

- `/live`：`L0_RiskBar`、`L2_AccountOverview`。

### 3.4 GET /api/live/config

用途：  
读取实盘配置，用于 L1.5 实盘配置面板与 L3 用于计算 1R 对应 USD。

请求：

- Method: `GET`

响应示例：

```ts
type LiveConfigField = {
  label: string; // 展示名，如 "每笔风险(USDT)"
  value: string; // 配置值，统一为字符串表示
};

type LiveConfigResponse = {
  risk_per_trade_usd: LiveConfigField; // 每笔风险金额
  initial_capital: LiveConfigField;
  risk_pct: LiveConfigField;
  max_positions: LiveConfigField;
  leverage: LiveConfigField;
  enabled_strategies: LiveConfigField;
  trade_env: LiveConfigField;
};
```

被使用位置：

- `/live`：`L15_LiveConfig`、`L3_Positions`（读取 risk_per_trade_usd）。

### 3.5 PUT /api/live/config

用途：  
更新实盘配置，来自 L1.5 配置面板的保存操作。

请求：

- Method: `PUT`
- Body（JSON）：

```ts
type LiveConfigUpdate = {
  risk_per_trade_usd?: string;
  initial_capital?: string;
  risk_pct?: string;
  max_positions?: string;
  leverage?: string;
  enabled_strategies?: string;
  trade_env?: string;
};
```

响应：

- 通常返回更新后的配置或简单的 `{ ok: true }`，以实际实现为准。

被使用位置：

- `/live`：`L15_LiveConfig`。

### 3.6 实盘控制操作接口

用途：  
L1 一键止血面板使用的控制接口。

#### POST /api/live/emergency-close

- 功能：立即平掉所有实盘持仓；
- 请求：无 body；
- 响应：包含执行结果信息，例如：

```ts
{ ok: boolean; message?: string; error?: string }
```

#### POST /api/live/block-new

- 功能：阻止新开仓（维持只减仓模式）；
- 请求/响应结构同上。

#### POST /api/live/resume

- 功能：恢复正常交易（允许新开仓）；
- 请求/响应结构同上。

被使用位置：

- `/live`：`L1_EmergencyPanel`。

### 3.7 其他 /live 页面接口

下面补充 `/live` 页面中其他接口的前端契约（只列出前端实际使用到的字段）。

#### 3.7.1 GET /api/live/summary?strategy=

用途：  
L2 账户概览中策略层面的汇总统计（总净 R、总净 USDT、费用、资金费率贡献、胜率等）。

请求：

- Method: `GET`
- Query：

```ts
{
  strategy: string; // 策略标识，例如 "v52_8signals" 或某个 strategy_id 映射
}
```

响应示例（仅包含前端用到字段）：

```ts
type LiveSummary = {
  total_pnl_r: number;        // 总净 R（含历史所有平仓）
  total_pnl_usdt: number;     // 总净 USDT
  total_fee_usdt: number;     // 手续费总额（USDT）
  total_funding_usdt: number; // 资金费率贡献（USDT，可为正/负）
  win_rate: number;           // 胜率（百分数）
  profit_factor: number;      // 盈亏比（Gross 赢 / Gross 亏）
  // 可以包含更多分解字段（按 symbol、按方向等），前端当前未使用
};
```

被使用位置：

- `/live`：`L2_AccountOverview`。

#### 3.7.2 GET /api/live/positions?strategy=

用途：  
L3 当前持仓列表，用于展示实盘持仓、TP/SL、水位、执行质量指标等。

请求：

- Method: `GET`
- Query：

```ts
{
  strategy: string; // 当前关注策略，如 "v52_8signals"
}
```

响应示例（前端用到字段）：

```ts
type LivePosition = {
  id: number;
  symbol: string;           // 如 "BTCUSDT"
  direction: "LONG"|"SHORT";
  tier: "light"|"standard"|"heavy";

  entry_price: number;
  fill_price?: number | null;
  current_price?: number | null;
  entry_ts: number;         // 入场时间（毫秒）
  hold_time_min?: number;   // 持仓分钟数（可选，前端如不存在则按 now-entry_ts 计算）

  score: number;            // 开仓评分
  risk_distance: number;    // 1R 对应的价格距离

  tp1_price: number;
  tp2_price: number;
  sl_price: number;
  tp1_hit: boolean;

  // 执行质量指标（以 R 或 ms 为单位）
  slippage_bps?: number;        // 滑点（基点）
  protection_gap_ms?: number;   // 裸奔时间（毫秒）
  signal_to_order_ms?: number;  // 信号触发到下单的延迟
  order_to_fill_ms?: number;    // 下单到成交的延迟
  binance_order_id?: string | null;
};

type LivePositionsResponse = {
  data: LivePosition[];
};
```

被使用位置：

- `/live`：`L3_Positions`。

#### 3.7.3 GET /api/live/execution-quality

用途：  
L4 执行质量面板，总体和按币种统计滑点、延迟、裸奔时间。

请求：

- Method: `GET`
- Query: 无

响应示例（简化为前端用到字段）：

```ts
type MetricStats = {
  avg: number;
  p50: number;
  p95: number;
};

type ExecutionQualityResponse = {
  total_trades: number;
  overall: {
    slippage_bps: MetricStats;
    signal_to_order_ms: MetricStats;
    order_to_fill_ms: MetricStats;
    protection_gap_ms: MetricStats;
  };
  by_symbol?: Record<string, {
    count: number;
    slippage_bps?: MetricStats;
    protection_gap_ms?: MetricStats;
  }>;
  error?: string; // 如存在错误则 overall/by_symbol 可能为空
};
```

被使用位置：

- `/live`：`L4_ExecutionQuality`。

#### 3.7.4 GET /api/live/events?limit=&level=

用途：  
L7 实时事件流，用于查看交易、风险、系统、对账等事件日志。

请求：

- Method: `GET`
- Query：

```ts
{
  limit?: number;                 // 默认约 30
  level?: "all"|"critical"|"warn"|"info";
}
```

响应示例：

```ts
type LiveEvent = {
  id: number;
  ts: number | string;           // 事件时间（秒/毫秒时间戳或 ISO 字符串）
  level: "info"|"warn"|"error"|"critical"|string;
  category?: "trade"|"risk"|"system"|"reconciliation"|string;
  symbol?: string | null;        // 如 "BTCUSDT"
  message: string;
};

type LiveEventsResponse = {
  data: LiveEvent[];
};
```

被使用位置：

- `/live`：`L7_EventStream`。

#### 3.7.5 GET /api/live/paper-comparison?limit=

用途：  
L8 实盘 vs 模拟盘对比，比较同一信号在实盘与模拟盘的入场/收益差异。

请求：

- Method: `GET`
- Query：

```ts
{
  limit?: number; // 默认约 20
}
```

响应示例：

```ts
type PaperComparisonRow = {
  symbol: string;           // 如 "BTCUSDT"
  direction: "LONG"|"SHORT";

  live_entry?: number | null;   // 实盘入场价
  paper_entry?: number | null;  // 模拟盘入场价
  entry_diff_bps?: number | null; // 入场价差（基点）

  live_pnl?: number | null;     // 实盘 R 或 USDT（前端仅格式化）
  paper_pnl?: number | null;    // 模拟盘 R 或 USDT
  pnl_diff_r?: number | null;   // 实盘 vs 模拟盘的 R 差
};

type PaperComparisonResponse = {
  avg_pnl_diff_r: number;   // 平均 R 差
  data: PaperComparisonRow[];
};
```

被使用位置：

- `/live`：`L8_PaperComparison`。

#### 3.7.6 GET /api/live/equity-curve?strategy=

用途：  
L9 权益曲线 + 回撤图，按时间展示累计 R 和回撤。

请求：

- Method: `GET`
- Query：

```ts
{
  strategy: string; // 如 "v52_8signals" 或相关策略 ID 映射
}
```

响应示例：

```ts
type EquityPoint = {
  ts: number;   // 时间戳（毫秒），前端按北京时间格式化展示
  pnl: number;  // 截至当前的累计 R
};

type EquityCurveResponse = {
  data: EquityPoint[];
};
```

前端会基于 `pnl` 计算回撤 `dd` 字段，并绘制两条 area 曲线（累计PnL 和 回撤），因此响应中无需直接提供回撤值。

被使用位置：

- `/live`：`L9_EquityCurve`。

#### 3.7.7 GET /api/live/trades?symbol=&result=&strategy=&limit=

用途：  
L10 历史交易表，用于按币种和结果（盈/亏）筛选实盘历史交易。

请求：

- Method: `GET`
- Query：

```ts
{
  symbol?: "all"|"BTC"|"ETH"|"XRP"|"SOL";
  result?: "all"|"win"|"loss";
  strategy: string; // 当前策略标识，如 "v52_8signals"
  limit?: number;   // 默认约 50
}
```

响应示例（前端用到字段）：

```ts
type LiveTrade = {
  id: number;
  symbol: string;           // 如 "BTCUSDT"
  direction: "LONG"|"SHORT";
  entry_price: number;
  exit_price?: number | null;
  entry_ts: number;         // 入场时间（毫秒）
  exit_ts?: number | null;  // 出场时间（毫秒）

  gross_pnl_r?: number;     // 毛收益 R
  fee_r?: number;           // 手续费 R
  funding_r?: number;       // 资金费率 R
  slippage_r?: number;      // 滑点 R
  net_pnl_r?: number;       // 净 R（优先使用）
  pnl_r?: number;           // 兼容字段，net_pnl_r 不存在时退回使用

  status: string;           // "tp" | "sl" | "sl_be" | 其他（前端映射为 止盈/止损/保本/原样展示）
};

type LiveTradesResponse = {
  data: LiveTrade[];
};
```

被使用位置：

- `/live`：`L10_TradeHistory`。

#### 3.7.8 GET /api/live/health

用途：  
L11 系统健康，用于展示运行进程状态和数据新鲜度（行情等）。

请求：

- Method: `GET`

响应示例（前端使用到字段）：

```ts
type LiveHealthResponse = {
  processes?: Record<string, {
    status: string;     // 如 "online" / "stopped" 等
    memory_mb: number;
    restarts: number;
    // 可包含更多信息（CPU 等），前端当前未使用
  }>;
  data_freshness?: {
    market_data?: {
      age_sec: number;  // 距离最新行情数据的秒数
      status: "green"|"yellow"|"red"|string; // 绿=正常, 黄/红=延迟或异常
    };
    // 其它数据源可在此扩展
  };
};
```

被使用位置：

- `/live`：`L11_SystemHealth`。

---

## 4. /strategy-plaza 策略广场接口

### 4.1 GET /api/strategies

用途：  
`/strategy-plaza` 页面策略卡片列表的数据源；账号/其他页面也可使用该接口获取策略列表。

请求：

- Method: `GET`
- Query：

```ts
{
  include_deprecated?: "true" | "false"; // 为 "true" 时包含废弃策略
}
```

响应示例（部分字段）：

```ts
type StrategyItem = {
  strategy_id: string;   // UUID
  display_name: string;  // 展示名
  symbol: string;        // 交易对，如 "BTCUSDT"
  status: "running" | "paused" | "deprecated" | "error";
  started_at: number;    // 启动时间（毫秒）

  initial_balance: number;
  current_balance: number;

  net_usdt: number;      // 累计盈亏（USDT）
  net_r: number;         // 累计 R
  trade_count: number;
  win_rate: number;      // 胜率（百分数）
  avg_win_r: number;
  avg_loss_r: number;

  open_positions: number;
  pnl_usdt_24h: number;  // 24 小时净收益（USDT）
  pnl_r_24h: number;     // 24 小时净 R
  std_r: number;         // 收益波动（标准差），如有
  last_trade_at: number | null; // 最近一笔交易时间（毫秒）
};

type StrategiesResponse = {
  strategies: StrategyItem[];
};
```

被使用位置：

- `/strategy-plaza`：展示 running/paused 策略卡片；
- `/strategy-plaza/deprecated`：配合过滤，仅展示 `status="deprecated"`。

### 4.2 POST /api/strategies/{sid}/add-balance

用途：  
为指定策略追加模拟资金，调整初始余额与当前余额。

请求：

- Method: `POST`
- Path 参数：

```ts
{ sid: string } // strategy_id
```

- Body（JSON）：

```ts
{ amount: number } // 追加金额（USDT）
```

响应：

- 典型形式：`{ ok: true }` 或返回更新后的策略；具体以实现为准。

被使用位置：

- `/strategy-plaza`：`AddBalanceModal`。

### 4.3 POST /api/strategies/{sid}/deprecate

用途：  
将策略状态标记为 `deprecated`，停止其运行但保留所有历史数据。

请求：

- Method: `POST`
- Body（JSON）：

```ts
{ confirm: true }
```

响应：

- 通常为 `{ ok: true }`；错误时返回错误说明。

被使用位置：

- `/strategy-plaza`：卡片右侧垃圾桶按钮，带浏览器 confirm。

### 4.4 POST /api/strategies/{sid}/restore

用途：  
恢复废弃策略到运行状态（`status=running`），继续使用原有余额与历史记录。

请求：

- Method: `POST`

响应：

- 类似 `{ ok: true }`。

被使用位置：

- `/strategy-plaza/deprecated`：每张废弃策略卡片底部的“重新启用”按钮。

> 单策略详情、策略创建/编辑等接口（`/api/strategies/{sid}`、`/api/strategies` POST/PATCH 等）主要被 `/strategy-plaza/[id]` 和 `/strategy-plaza/create` 等页面使用，可在需要时进一步补充契约说明。

---

## 5. /server 服务器监控接口

### 5.1 GET /api/server/status

用途：  
为 `/server` 页面提供服务器与 PM2/数据库状态。

请求：

- Method: `GET`

响应示意：

```ts
type ServerStatus = {
  timestamp: number; // 采集时间（毫秒）

  cpu: {
    percent: number;
    cores: number;
  };
  memory: {
    total_gb: number;
    used_gb: number;
    percent: number;
    swap_percent: number;
  };
  disk: {
    total_gb: number;
    used_gb: number;
    free_gb: number;
    percent: number;
  };
  load: {
    load1: number;
    load5: number;
    load15: number;
  };
  uptime_hours: number;
  network: {
    bytes_sent_gb: number;
    bytes_recv_gb: number;
  };

  pm2: Array<{
    name: string;
    status: string;     // "online" 等
    cpu: number;        // CPU 使用率
    memory_mb: number;  // 内存 MB
    restarts: number;
    uptime_ms: number;
    pid: number;
  }>;

  postgres: {
    db_size_mb: number;
    agg_trades_count: number;
    rate_snapshots_count: number;
    symbols: Record<string, {
      latest_ms: number;
      earliest_ms: number;
      span_hours: number;
    }>;
  };

  backfill_running: boolean;
};
```

被使用位置：

- `/server`：系统概览卡片、PM2 进程表、PostgreSQL 概览和回补状态。

---

## 6. 认证与账号接口

### 6.1 POST /api/auth/login

用途：  
用户登录，获取 JWT 并在前端存储。

请求：

- Method: `POST`
- Body：

```ts
{ email: string; password: string }
```

响应：

- 一般形式：`{ access_token: string, token_type: "bearer", user: {...} }`；具体字段以 full-spec 与 auth 模块实现为准。

被使用位置：

- `/login`：通过 `useAuth().login()` 封装调用。

### 6.2 POST /api/auth/register

用途：  
邀请码注册新账号。

请求：

- Method: `POST`
- Body：

```ts
{ email: string; password: string; invite_code: string }
```

响应：

- 一般为新用户信息 + token 或简单成功标记，具体以实现为准。

被使用位置：

- `/register`：通过 `useAuth().register()` 封装调用。

### 6.3 GET /api/auth/me

用途：  
获取当前登录用户信息和订阅状态。

请求：

- Method: `GET`
- 需带 Authorization: Bearer token

响应示意：

```ts
type AuthMeResponse = {
  id: number;
  email: string;
  discord_id: string | null;
  subscription?: {
    tier: string;        // "free" | "pro" | "premium" ...
    expires_at: string | null; // ISO 时间字符串
  };
};
```

被使用位置：

- `/dashboard`："我的账户" 页面。

### 6.4 POST /api/user/bind-discord

用途：  
绑定或更新当前用户的 Discord 用户 ID。

请求：

- Method: `POST`
- Body：

```ts
{ discord_id: string }
```

响应：

- 成功：`{ ok: true, ... }` 或包含简单 message；
- 失败：返回带有 `detail` 字段的错误响应，前端直接展示。

被使用位置：

- `/dashboard`：Discord 信号推送卡片的“绑定”按钮。

---

## 7. /signals 信号接口

> 这些接口为 `/signals`、`/signals-v52`、`/signals-v53` 等信号页面，以及 `/paper` 中的“最新信号”区域提供数据。

### 7.1 GET /api/signals/latest?strategy=

用途：  
返回指定策略下各币种（BTC/ETH/XRP/SOL）的最新指标快照与评分结果，用于信号页顶部“实时指标卡片”。

请求：

- Method: `GET`
- Query：

```ts
{
  strategy: string; // 如 "v51_baseline" | "v52_8signals" | "v53" 等
}
```

响应示例（基础字段 + 可选 factors）：

```ts
type SignalTier = "light" | "standard" | "heavy";

type LayerInfo = {
  score?: number;
  max?: number;
  // 各版本策略可能包含额外字段，如 cvd_resonance/p99_flow 等
  [key: string]: unknown;
};

type LatestIndicatorFactors = {
  // 通用层
  direction?: LayerInfo & { cvd_resonance?: number; p99_flow?: number; accel_bonus?: number };
  crowding?: LayerInfo & { lsr_contrarian?: number; top_trader_position?: number };
  environment?: LayerInfo;
  confirmation?: LayerInfo;
  auxiliary?: LayerInfo & { coinbase_premium?: number };

  // V5.2 新增层
  funding_rate?: LayerInfo & { value?: number };
  liquidation?: LayerInfo & { long_usd?: number; short_usd?: number };

  // Gate 控制相关（V5.3/BTC 轨）
  gate_passed?: boolean;
  block_reason?: string | null; // BTC 轨使用
  gate_block?: string | null;   // ALT 轨使用

  // 市场结构细节
  obi_raw?: number;        // 订单簿不平衡
  spot_perp_div?: number;  // 期现价差
  whale_cvd_ratio?: number;
  atr_pct_price?: number;  // ATR/price
  alt_score_ref?: number;  // 替代参考分
  track?: string;          // 当前轨道标记（BTC/ALT）
};

type LatestIndicator = {
  ts: number;           // 时间戳（毫秒）
  cvd_fast: number;     // 快 CVD（例如 30m）
  cvd_mid: number;      // 中 CVD（例如 4h）
  cvd_day: number;      // 日 CVD
  cvd_fast_slope: number;
  atr_5m: number;
  atr_percentile: number;
  vwap_30m: number;
  price: number;
  p95_qty: number;
  p99_qty: number;

  score: number;              // 综合评分（0~100）
  display_score?: number;     // V5.3 BTC 轨参考分
  signal: "LONG" | "SHORT" | null;
  tier?: SignalTier | null;   // "light" | "standard" | "heavy" 或无
  gate_passed?: boolean;      // V5.3 顶层 gate 结果

  factors?: LatestIndicatorFactors | null;
};

type LatestSignalsResponse = {
  BTC?: LatestIndicator | null;
  ETH?: LatestIndicator | null;
  XRP?: LatestIndicator | null;
  SOL?: LatestIndicator | null;
};
```

被使用位置：

- `/signals`：V5.1 信号页顶部指标卡片（strategy=v51_baseline）；
- `/signals-v52`：V5.2 信号页（strategy=v52_8signals）；
- `/signals-v53`：V5.3 信号页（strategy=v53）；
- 其它变体页（fast/middle）仅改变 strategy 参数。

### 7.2 GET /api/signals/indicators?symbol=&minutes=&strategy=

用途：  
返回某币种在指定时间窗口内的指标时间序列，用于绘制 “CVD 三轨 + 币价” 图表。

请求：

- Method: `GET`
- Query：

```ts
{
  symbol: "BTC" | "ETH" | "XRP" | "SOL"; // 部分页面传 "BTCUSDT" 形式，由后端兼容
  minutes: number;                       // 统计窗口长度（例如 60/240/720/1440）
  strategy?: string;                     // V5.3 页面会传入 strategy=v53
}
```

响应示例：

```ts
type IndicatorRow = {
  ts: number;         // 时间戳（毫秒）
  cvd_fast: number;
  cvd_mid: number;
  cvd_day: number;
  atr_5m: number;
  vwap_30m: number;
  price: number;
  score: number;
  signal: string | null; // "LONG"|"SHORT"|null
};

type IndicatorsResponse = {
  data: IndicatorRow[];
};
```

被使用位置：

- `/signals`、`/signals-v52`、`/signals-v53`：CVD+价格图。

### 7.3 GET /api/signals/market-indicators

用途：  
为信号页中的“Market Indicators”卡片提供多空比、大户持仓、OI、Coinbase Premium 等市场指标。

请求：

- Method: `GET`
- Query: 无

响应示例（按 symbol 分组）：

```ts
type MarketIndicatorValue = {
  value: unknown | string; // 原始 JSON 对象或 JSON 字符串
  ts: number;              // 指标数据时间戳（毫秒）
};

type MarketIndicatorSet = {
  long_short_ratio?: MarketIndicatorValue;  // 多空比
  top_trader_position?: MarketIndicatorValue; // 大户持仓
  open_interest_hist?: MarketIndicatorValue; // OI 历史
  coinbase_premium?: MarketIndicatorValue;   // Coinbase Premium
};

type MarketIndicatorsResponse = {
  BTC?: MarketIndicatorSet;
  ETH?: MarketIndicatorSet;
  XRP?: MarketIndicatorSet;
  SOL?: MarketIndicatorSet;
};
```

前端会对 `value` 做二次解析，将其视为对象并读取：

- `long_short_ratio.value.longAccount/shortAccount`；
- `top_trader_position.value.longAccount/shortAccount`；
- `open_interest_hist.value.sumOpenInterestValue`；
- `coinbase_premium.value.premium_pct`。

被使用位置：

- `/signals`、`/signals-v52`：`MarketIndicatorsCards` 组件。

### 7.4 GET /api/signals/signal-history?symbol=&limit=&strategy=

用途：  
为各版本信号页中的“最近信号”列表，以及 `/paper` 页的“最新信号”区提供数据。

请求：

- Method: `GET`
- Query：

```ts
{
  symbol: string;        // 如 "BTC" | "ETH" 或 "BTCUSDT"
  limit?: number;        // 条数，默认约 20
  strategy: string;      // 如 "v51_baseline" | "v52_8signals" | "v53"
}
```

响应示例（简化）：

```ts
type SignalHistoryRow = {
  ts: number;           // 时间戳（毫秒）
  score: number;        // 当时评分
  signal: "LONG"|"SHORT"|string; // 方向或其他标记
  factors?: LatestIndicatorFactors; // 可选：各层分数快照，用于链路说明
};

type SignalHistoryResponse = {
  data: SignalHistoryRow[];
};
```

被使用位置：

- `/signals`：最近信号（strategy=v51_baseline）；  
- `/signals-v52`、`/signals-v53`：对应策略最近信号；  
- `/paper`：`LatestSignals` 组件（从各 symbol 取最新一条，显示 score + 分层 factors 摘要）。

---

## 8. /paper 模拟盘接口

> 这些接口为 `/paper`、`/paper-v52`、`/paper-v53*` 等模拟盘页面，以及部分策略详情页提供数据。