1365 lines
30 KiB
Markdown
1365 lines
30 KiB
Markdown
# 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*` 等模拟盘页面，以及部分策略详情页提供数据。
|