docs: strategy-plaza data contract v1.0
This commit is contained in:
root
parent
2d64a5524e
commit
8cab470231
203
docs/arbitrage-engine/strategy-plaza-data-contract.md
Normal file
203
docs/arbitrage-engine/strategy-plaza-data-contract.md
Normal file
@ -0,0 +1,203 @@
|
||||
# 策略广场 数据合约文档
|
||||
|
||||
> 版本：v1.0
|
||||
> 日期：2026-03-07
|
||||
> 状态：待范总确认 ✅
|
||||
> 作者：露露 + 小范
|
||||
> 分支：`feature/strategy-plaza`
|
||||
|
||||
---
|
||||
|
||||
## 1. 功能概述
|
||||
|
||||
**策略广场**（Strategy Plaza）将现有的 signals-v53 / paper-v53 / signals-v53fast 等分散页面整合为统一入口：
|
||||
|
||||
- 总览页：策略卡片列表，展示每个策略的核心指标，30 秒自动刷新
|
||||
- 详情页：点击卡片进入，顶部 Tab 切换「信号引擎」和「模拟盘」视图
|
||||
|
||||
---
|
||||
|
||||
## 2. 前端路由
|
||||
|
||||
| 路由 | 说明 |
|
||||
|------|------|
|
||||
| `/strategy-plaza` | 策略广场总览（卡片列表） |
|
||||
| `/strategy-plaza/[id]` | 策略详情页，默认「信号引擎」tab |
|
||||
| `/strategy-plaza/[id]?tab=paper` | 策略详情页「模拟盘」tab |
|
||||
|
||||
**侧边栏变更：**
|
||||
- 新增「策略广场」单一入口
|
||||
- 原 `signals-v53` / `paper-v53` / `signals-v53fast` / `paper-v53fast` / `signals-v53middle` / `paper-v53middle` 页面：**保留但从侧边栏隐藏**（路由仍可访问）
|
||||
|
||||
---
|
||||
|
||||
## 3. API 设计
|
||||
|
||||
### 3.1 `GET /api/strategy-plaza`
|
||||
|
||||
返回所有策略的卡片摘要数据。
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"strategies": [
|
||||
{
|
||||
"id": "v53",
|
||||
"display_name": "V5.3 标准版",
|
||||
"status": "running",
|
||||
"started_at": 1741234567000,
|
||||
"initial_balance": 10000,
|
||||
"current_balance": 8693,
|
||||
"net_usdt": -1307,
|
||||
"net_r": -6.535,
|
||||
"trade_count": 63,
|
||||
"win_rate": 49.2,
|
||||
"avg_win_r": 0.533,
|
||||
"avg_loss_r": -0.721,
|
||||
"open_positions": 0,
|
||||
"pnl_usdt_24h": -320,
|
||||
"pnl_r_24h": -1.6,
|
||||
"std_r": 0.9,
|
||||
"last_trade_at": 1741367890000
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**字段说明：**
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `id` | string | 策略唯一标识，与 DB strategy 字段一致 |
|
||||
| `display_name` | string | 展示名称 |
|
||||
| `status` | string | `running` / `paused` / `error` |
|
||||
| `started_at` | number (ms) | 策略启动时间（暂用 paper_trades 第一条 entry_ts，后续补 strategy_meta 表） |
|
||||
| `initial_balance` | number | 初始余额 USDT，固定 10000 |
|
||||
| `current_balance` | number | 当前余额 = initial_balance + net_usdt |
|
||||
| `net_usdt` | number | 累计盈亏 USDT = SUM(pnl_r) × 200 |
|
||||
| `net_r` | number | 累计净 R |
|
||||
| `trade_count` | number | 已出场交易数 |
|
||||
| `win_rate` | number | 胜率 % |
|
||||
| `avg_win_r` | number | 平均赢单 R |
|
||||
| `avg_loss_r` | number | 平均亏单 R（负数） |
|
||||
| `open_positions` | number | 当前活跃持仓数（exit_ts IS NULL） |
|
||||
| `pnl_usdt_24h` | number | 最近 24h 盈亏 USDT |
|
||||
| `pnl_r_24h` | number | 最近 24h 净 R |
|
||||
| `std_r` | number | 所有已出场交易的 pnl_r 标准差（风险感知） |
|
||||
| `last_trade_at` | number (ms) | 最近一笔成交的 exit_ts |
|
||||
|
||||
**status 判断逻辑：**
|
||||
- `running`：paper_config 中 enabled=true 且最近 signal_indicators 记录 < 5 分钟
|
||||
- `paused`：paper_config 中 enabled=false
|
||||
- `error`：paper_config 中 enabled=true 但 signal_indicators 最新记录 > 5 分钟
|
||||
|
||||
---
|
||||
|
||||
### 3.2 `GET /api/strategy-plaza/[id]/summary`
|
||||
|
||||
返回单个策略的完整摘要，包含卡片字段 + 详情字段。
|
||||
|
||||
**Response（在 3.1 基础上增加）:**
|
||||
```json
|
||||
{
|
||||
"id": "v53",
|
||||
"display_name": "V5.3 标准版",
|
||||
"cvd_windows": "30m / 4h",
|
||||
"description": "标准版：30分钟+4小时CVD双轨，适配1小时信号周期",
|
||||
"symbols": ["BTCUSDT", "ETHUSDT", "SOLUSDT", "XRPUSDT"],
|
||||
"weights": {
|
||||
"direction": 55,
|
||||
"crowding": 25,
|
||||
"environment": 15,
|
||||
"auxiliary": 5
|
||||
},
|
||||
"thresholds": {
|
||||
"signal_threshold": 75,
|
||||
"flip_threshold": 85
|
||||
},
|
||||
"...所有 3.1 字段..."
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3.3 `GET /api/strategy-plaza/[id]/signals`
|
||||
|
||||
复用现有 `/api/signals` 逻辑，增加 `strategy` 过滤。接口参数和返回格式与现有保持一致。
|
||||
|
||||
---
|
||||
|
||||
### 3.4 `GET /api/strategy-plaza/[id]/trades`
|
||||
|
||||
复用现有 `/api/paper-trades` 逻辑，增加 `strategy` 过滤。接口参数和返回格式与现有保持一致。
|
||||
|
||||
---
|
||||
|
||||
## 4. 数据来源映射
|
||||
|
||||
| 字段 | 数据来源 |
|
||||
|------|---------|
|
||||
| `net_usdt`, `net_r`, `trade_count`, `win_rate`, `avg_win_r`, `avg_loss_r` | `paper_trades` WHERE strategy=id AND exit_ts IS NOT NULL |
|
||||
| `open_positions` | `paper_trades` WHERE strategy=id AND exit_ts IS NULL |
|
||||
| `pnl_usdt_24h`, `pnl_r_24h` | `paper_trades` WHERE strategy=id AND exit_ts > NOW()-24h |
|
||||
| `std_r` | STDDEV(pnl_r) FROM paper_trades WHERE strategy=id AND exit_ts IS NOT NULL |
|
||||
| `started_at` | MIN(entry_ts) FROM paper_trades WHERE strategy=id |
|
||||
| `last_trade_at` | MAX(exit_ts) FROM paper_trades WHERE strategy=id AND exit_ts IS NOT NULL |
|
||||
| `status` | paper_config.json + signal_indicators 最新记录时间 |
|
||||
| `cvd_windows`, `weights`, `thresholds` | backend/strategies/[id].json |
|
||||
|
||||
---
|
||||
|
||||
## 5. 前端组件规划
|
||||
|
||||
### 5.1 总览页组件
|
||||
|
||||
```
|
||||
StrategyPlaza
|
||||
└── StrategyCardGrid
|
||||
└── StrategyCard (×N)
|
||||
├── 策略名 + status badge (running/paused/error)
|
||||
├── 运行时长 (now - started_at)
|
||||
├── 当前余额 / 初始余额
|
||||
├── 净盈亏 USDT + 净R（带颜色）
|
||||
├── 胜率
|
||||
├── 最近24h盈亏（小字）
|
||||
└── 点击 → /strategy-plaza/[id]
|
||||
```
|
||||
|
||||
### 5.2 详情页组件
|
||||
|
||||
```
|
||||
StrategyDetail
|
||||
├── 顶部：策略名 + status + 运行时长
|
||||
├── Tab 切换：[信号引擎] [模拟盘]
|
||||
│
|
||||
├── Tab: 信号引擎
|
||||
│ └── 复用 SignalsV53Page 内容
|
||||
│
|
||||
└── Tab: 模拟盘
|
||||
└── 复用 PaperV53Page 内容
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 实现计划
|
||||
|
||||
| 阶段 | 内容 | 负责 |
|
||||
|------|------|------|
|
||||
| P0 | 后端 API `/api/strategy-plaza` | 露露 |
|
||||
| P1 | 后端 API `/api/strategy-plaza/[id]/summary` | 露露 |
|
||||
| P2 | 前端总览页（StrategyCard × 3） | 露露 |
|
||||
| P3 | 前端详情页（Tab + 复用现有组件） | 露露 |
|
||||
| P4 | 侧边栏整合（新增入口，隐藏旧页面） | 露露 |
|
||||
| Review | 代码审阅 + 逻辑验证 | 小范 |
|
||||
|
||||
> 开发前等范总确认数据结构，不提前动代码。
|
||||
|
||||
---
|
||||
|
||||
## 7. 变更记录
|
||||
|
||||
| 版本 | 日期 | 内容 |
|
||||
|------|------|------|
|
||||
| v1.0 | 2026-03-07 | 初版，露露起草 + 小范审阅 |
|
||||
Loading…
Reference in New Issue
Block a user