# Dashboard Design ## 1. 目录结构 ``` exchange-monitor-go/ ├── main.go # 入口：启动 engine + web server ├── config.go # 配置加载（不变） ├── types.go # 公共类型（不变） │ ├── engine/ # 核心交易引擎（从 main.go 拆分） │ ├── engine.go # Engine 结构体：组合所有模块 │ ├── scanner.go # 价差扫描（从 scanner.go 移入） │ ├── trader.go # 交易执行（从 trader.go 移入） │ ├── notifier.go # Telegram 通知（从 notifier.go 移入） │ └── portfolio.go # 资金管理 + PnL 聚合 │ ├── exchange/ # 交易所连接（不变） │ └── ... │ ├── db/ # SQLite 持久化层（新增） │ ├── db.go # DB 初始化、迁移 │ ├── trade_repo.go # 交易记录 CRUD │ ├── order_repo.go # 订单明细 CRUD │ └── config_repo.go # 配置快照 │ ├── web/ # Web 仪表盘（新增） │ ├── server.go # HTTP 服务器 + 路由 │ ├── handler_dashboard.go # 页面渲染 │ ├── handler_api.go # REST API │ ├── handler_sse.go # SSE 实时推送 │ ├── static/ # 前端静态资源（go:embed） │ │ ├── index.html │ │ ├── app.js │ │ └── style.css │ └── ws_monitor.go # WS 状态监控 │ ├── risk/ # 风控层（新增） │ └── risk.go # 风控规则引擎 │ ├── persistence.md # 本设计文档 └── ... ``` ## 2. 数据模型 (SQLite) ``` ┌─────────────────────────────────────────────────────┐ │ trades │ ├──────────────┬──────────┬───────────────────────────┤ │ id │ INTEGER │ PRIMARY KEY AUTOINCREMENT │ │ coin │ TEXT │ NOT NULL │ │ direction │ TEXT │ BG->HL / HL->BG │ │ status │ TEXT │ open / closed │ │ entry_spread │ REAL │ 进场价差 % │ │ exit_spread │ REAL │ 出场价差 % │ │ long_ex │ TEXT │ 多腿交易所 │ │ short_ex │ TEXT │ 空腿交易所 │ │ long_entry │ REAL │ 多腿进场价 │ │ long_exit │ REAL │ 多腿出场价 │ │ short_entry │ REAL │ 空腿进场价 │ │ short_exit │ REAL │ 空腿出场价 │ │ long_pnl │ REAL │ 多腿 PnL % │ │ short_pnl │ REAL │ 空腿 PnL % │ │ fee_entry │ REAL │ 开仓手续费 % │ │ fee_exit │ REAL │ 平仓手续费 % │ │ net_pnl │ REAL │ 净利 % │ │ amount_usd │ REAL │ 总金额 $ │ │ scale_count │ INTEGER │ 加仓次数 │ │ exit_reason │ TEXT │ 止盈/止损/超时 │ │ convergence │ TEXT │ 收敛/发散/持平 │ │ opened_at │ DATETIME │ │ │ closed_at │ DATETIME │ │ └──────────────┴──────────┴───────────────────────────┘ ┌─────────────────────────────────────────────────────┐ │ orders (每腿一条) │ ├──────────────┬──────────┬───────────────────────────┤ │ id │ INTEGER │ │ │ trade_id │ INTEGER │ FK → trades.id │ │ leg │ TEXT │ long / short │ │ type │ TEXT │ entry / exit / scale │ │ exchange │ TEXT │ │ │ side │ TEXT │ buy / sell │ │ price │ REAL │ 成交价 │ │ size │ REAL │ 数量 │ │ fee │ REAL │ 手续费 │ │ order_id │ TEXT │ 交易所订单 ID │ │ status │ TEXT │ filled / cancelled │ │ created_at │ DATETIME │ │ └──────────────┴──────────┴───────────────────────────┘ ┌─────────────────────────────────────────────────────┐ │ price_snapshots │ ├──────────────┬──────────┬───────────────────────────┤ │ id │ INTEGER │ │ │ coin │ TEXT │ │ │ exchange │ TEXT │ │ │ price │ REAL │ │ │ bid │ REAL │ │ │ ask │ REAL │ │ │ spread_basis │ REAL │ bid-ask spread % │ │ recorded_at │ DATETIME │ │ └──────────────┴──────────┴───────────────────────────┘ ┌─────────────────────────────────────────────────────┐ │ config_snapshots │ ├──────────────┬──────────┬───────────────────────────┤ │ id │ INTEGER │ │ │ key │ TEXT │ 参数名 │ │ value │ TEXT │ 参数值 │ │ changed_at │ DATETIME │ │ │ changed_by │ TEXT │ web / cli │ └──────────────┴──────────┴───────────────────────────┘ ``` ## 3. REST API ``` Base URL: http://localhost:8080/api/v1 ┌────────┬────────────────────────┬────────────────────────────┐ │ Method │ Path │ 说明 │ ├────────┼────────────────────────┼────────────────────────────┤ │ GET │ /api/v1/stats/summary │ 总览指标 │ │ GET │ /api/v1/stats/coins │ 各币种明细 │ │ GET │ /api/v1/stats/pnl │ PnL 曲线（按天/时） │ │ GET │ /api/v1/stats/daily │ 每日统计 │ ├────────┼────────────────────────┼────────────────────────────┤ │ GET │ /api/v1/trades │ 交易列表（分页） │ │ GET │ /api/v1/trades/:id │ 单笔交易详情 + 订单明细 │ │ GET │ /api/v1/trades/active │ 当前持仓 │ ├────────┼────────────────────────┼────────────────────────────┤ │ GET │ /api/v1/exchanges │ 交易所连接状态 │ │ GET │ /api/v1/prices │ 所有币种实时价差 │ ├────────┼────────────────────────┼────────────────────────────┤ │ GET │ /api/v1/config │ 当前配置 │ │ PUT │ /api/v1/config │ 更新配置 │ ├────────┼────────────────────────┼────────────────────────────┤ │ GET │ /api/v1/status │ 系统运行状态（uptime等） │ │ POST │ /api/v1/action/restart │ 重启扫描器 │ └────────┴────────────────────────┴────────────────────────────┘ GET /api/v1/stats/summary 响应: { "total_trades": 387, "total_pnl_pct": 4.27, "total_pnl_usd": 0.85, "win_rate": 56.5, "avg_pnl_pct": 0.011, "max_drawdown": -2.1, "active_positions": 3, "running_time": "13h 22m", "exchanges_connected": 4, "mode": "simulation" } GET /api/v1/stats/coins 响应: [ { "coin": "ONDO", "trades": 115, "pnl_pct": 3.11, "win_rate": 56.5, "avg_pnl": 0.027, "best_trade": 0.18, "worst_trade": -0.05, "long_pct": 94, "short_pct": 6, "active": true }, ... ] GET /api/v1/trades?page=1&limit=20&coin=ONDO 响应: { "trades": [ { "id": 1, "coin": "ONDO", "direction": "BG->HL", "entry_spread": 0.17, "exit_spread": 0.01, "net_pnl": 0.10, "duration": "52s", "opened_at": "2026-05-03T15:42:00+08:00", "scale_count": 0 } ], "total": 115, "page": 1 } ``` ## 4. SSE (Server-Sent Events) 实时推送 ``` Endpoint: GET /api/v1/stream ────────────── 连接建立 ──────────────→ ←── event: snapshot ── 全量数据推送 ── { prices: {...}, positions: [...], summary: {...} } ←── event: price_update ── 价差变化 ── (每 500ms) { coin: "ONDO", spread: 0.15, bg: 0.28, hl: 0.2815 } ←── event: trade_opened ── 新开仓 ── { id: 42, coin: "ONDO", direction: "BG->HL", spread: 0.17, ... } ←── event: trade_closed ── 平仓 ── { id: 42, net_pnl: 0.10, exit_spread: 0.01, ... } ←── event: exchange_status ── WS 状态变化 ── { exchange: "Bitget", connected: true, latency_ms: 120 } ←── event: alert ── 系统告警 ── { level: "warn", message: "WS reconnected", ... } ``` ## 5. 前端页面布局 ``` ┌──────────────────────────────────────────────────────┐ │ [logo] 套利机器人仪表盘 [模拟/实盘] [设置] │ ├──────────────────────────────────────────────────────┤ │ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌────────┐ │ │ │总交易 │ │总净利 │ │胜率 │ │当前持仓│ │运行时间 │ │ │ │ 387 │ │+4.27% │ │56.5% │ │ 3 │ │ 13h22m │ │ │ └───────┘ └───────┘ └───────┘ └───────┘ └────────┘ │ ├──────────────────────────────────────────────────────┤ │ Tab: [📈 概览] [📋 交易记录] [⚙️ 配置] [🔌 连接] │ ├──────────────────────────────────────────────────────┤ │ │ │ Tab: 概览 │ │ ┌──────────────────────────────────────────────────┐ │ │ │ 价差实时折线图（可切换币种） │ │ │ │ ╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲ │ │ │ │ ──── 0.1% 阈值线 ──── │ │ │ │ ╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱╲╱ │ │ │ │ [ONDO] [WIF] [OP] [DOGE] [ARB] [LINK] │ │ │ └──────────────────────────────────────────────────┘ │ │ │ │ ┌────┬──────┬──────┬──────┬──────┬──────┬───────┐ │ │ │币种 │方向 │持仓$ │价差% │已持 │浮动% │ P&L$ │ │ │ ├────┼──────┼──────┼──────┼──────┼──────┼───────┤ │ │ │ONDO│BG→HL │$5 │0.15 │12s │+0.10 │+0.005 │ │ │ │WIF │BG→HL │$10 │0.08 │2m30s │+0.22 │+0.022 │ │ │ │OP │HL→BG │$5 │0.22 │1m │+0.05 │+0.003 │ │ │ └────┴──────┴──────┴──────┴──────┴──────┴───────┘ │ │ │ │ 最近成交 │ │ 15:42:23 ONDO BG→HL 入场0.17% 出场0.01% +0.10% │ │ 15:41:55 WIF BG→HL 入场0.15% 出场0.02% +0.08% │ │ 15:41:30 OP HL→BG 入场0.22% 出场0.01% +0.15% │ │ │ │ Tab: 交易记录 │ │ ┌────┬──────┬──────┬──────┬──────┬──────┬──────┬───┐ │ │ │时间│币种 │方向 │入场 │出场 │净利% │持仓 │详情│ │ │ ├────┼──────┼──────┼──────┼──────┼──────┼──────┼───┤ │ │ │... │ │ │ │ │ │ │ >│ │ │ └────┴──────┴──────┴──────┴──────┴──────┴──────┴───┘ │ │ [上一页] [1/23] [下一页] │ │ │ │ Tab: 配置 │ │ 阈值: [0.1% ] 每腿金额: [$5 ] 模式: ○模拟 │ │ 冷却时间: [30000]ms 最大持仓: [3 ] ●实盘 │ │ [保存配置] │ │ │ │ Tab: 连接 │ │ ┌──────────┬──────────┬───────┬──────────┐ │ │ │交易所 │状态 │延迟 │最后更新 │ │ │ ├──────────┼──────────┼───────┼──────────┤ │ │ │Bitget │● 已连接 │120ms │15:42:23 │ │ │ │HL │● 已连接 │85ms │15:42:23 │ │ │ │Binance │● 已连接 │90ms │15:42:22 │ │ │ │dYdX │⚠ 重连中 │-- │15:41:48 │ │ │ └──────────┴──────────┴───────┴──────────┘ │ └──────────────────────────────────────────────────────┘ ``` ## 6. 前端技术选型 ``` 框架: 无框架，纯 HTML + CSS + vanilla JS 原因：零构建步骤，单文件嵌入 图表: Chart.js (CDN https://cdn.jsdelivr.net/npm/chart.js) 原因：轻量、灵活、CDN 无需 npm 实时通: EventSource (浏览器原生 SSE) 原因：比 WebSocket 简单，自动重连 UI: 纯 CSS Grid + Flexbox 深色主题（适合交易屏长时间看） 体积: < 300KB 总大小（含 Chart.js CDN） ``` ## 7. Web Server 设计 (Go) ``` // web/server.go package web type Server struct { engine *engine.Engine db *db.DB mux *http.ServeMux sse *SSEHub // SSE 连接管理器 } // SSEHub 管理所有 SSE 客户端连接 type SSEHub struct { clients map[chan SSEEvent]struct{} register chan chan SSEEvent unregister chan chan SSEEvent broadcast chan SSEEvent } // 从 Engine 接收事件并广播 func (h *SSEHub) Broadcast(eventType string, data interface{}) ``` ## 8. 数据流 ### 三层数据分层 ``` ┌──────────────────────────────────────────────┐ │ HOT (内存 only, 500ms) │ │ PriceStore: 6币×4所 实时价 │ │ Trader.positions: 当前持仓 │ │ Scanner: 扫描结果 │ │ 不落盘，重启丢失，但重连 WS 秒恢复 │ ├──────────────────────────────────────────────┤ │ WARM (SQLite, 事件驱动) │ │ 平仓 → INSERT trades │ │ 每腿成交 → INSERT orders │ │ 配置修改 → INSERT/UPSERT config_snapshots │ │ WS 重连 → INSERT exchange_events(可选) │ │ 写入频率: < 1次/秒 │ ├──────────────────────────────────────────────┤ │ COLD (时序方案待定, 未来) │ │ 价格存档：每分钟采样 × 6币 × 4所 │ │ 日产量: ~34,560行 → 可存 SQLite 也可用 │ │ TimescaleDB / InfluxDB (如果要做回测平台) │ └──────────────────────────────────────────────┘ ``` ### 实时数据 → 网页 ``` WS 数据流 (500ms): ┌─────────┐ price ┌──────────┐ SSE push ┌─────────┐ │ Exchange│──────────►│ Engine │─────────────►│ Browser │ │ WS │ │ (HOT层) │ │(实时更新)│ └─────────┘ └────┬─────┘ └─────────┘ │ 仅事件写入 ┌─────▼──────┐ │ SQLite │ │ (WARM层) │ └────────────┘ API 请求 (读 WARM 层): ┌─────────┐ GET /api/... ┌──────────┐ SQL ┌────────┐ │ Browser │────────────────►│ Server │──────────►│ SQLite │ │ (页面) │◄────────────────│(REST API)│◄──────────┘ │ └─────────┘ JSON └──────────┘ ``` ## 9. 实现顺序 ``` Phase 1 — 基础设施 1. db/ 包：SQLite 初始化 + schema 迁移 2. 程序启动时保存交易记录到 SQLite 3. 重启时从 SQLite 恢复历史数据 Phase 2 — Web Server 1. web/server.go：路由 + SSE Hub 2. REST API：summary, trades, prices, config 3. 前端 index.html：概览页（指标卡片 + 当前持仓 + 最近成交） Phase 3 — 实时 1. SSE stream：价格、持仓、交易实时推送 2. Chart.js 实时价差折线图 Phase 4 — 完善 1. 交易记录页（分页、筛选、详情弹窗） 2. 配置页（在线修改参数） 3. 连接状态页 4. PnL 曲线图 ```