From 8cab4702310f7d7dc48db9ec93f1db32a0e8d546 Mon Sep 17 00:00:00 2001
From: root <root@s52867.vps.hosting>
Date: Sat, 7 Mar 2026 06:15:05 +0000
Subject: [PATCH] docs: strategy-plaza data contract v1.0

---
 .../strategy-plaza-data-contract.md           | 203 ++++++++++++++++++
 1 file changed, 203 insertions(+)
 create mode 100644 docs/arbitrage-engine/strategy-plaza-data-contract.md

diff --git a/docs/arbitrage-engine/strategy-plaza-data-contract.md b/docs/arbitrage-engine/strategy-plaza-data-contract.md
new file mode 100644
index 0000000..f77f5f9
--- /dev/null
+++ b/docs/arbitrage-engine/strategy-plaza-data-contract.md
@@ -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 | 初版，露露起草 + 小范审阅 |