程序架構

Roadsign · Hyperliquid 下單器 — 模組規劃 · Standalone-first · 可分散式自託管

已實作進行中規劃中完整架構規劃文件：docs/ROADSIGN_MASTER_ARCHITECTURE.md
HL
Hyperliquid 接入層
資訊源 · 智能合約下單接口 · HyperCore
已接入
公開 WebSocket（server-side，所有使用者共享）
  • trades feed每筆成交即時推送 → K線聚合來源
  • candle（官方區間）固定區間補充（candleSnapshot REST 歷史回補）
  • allMids全品種中間價訂閱
私有 WebSocket（per-user，帶 master 地址）
  • clearinghouseState倉位 / 保證金 / 帳戶價值（WS 即時推流 + HTTP 備援）
  • orderUpdates委託狀態即時變更（WS 推流）
  • userFills成交回報（WS 即時推流）
  • openOrders當前未成交委託（HTTP 查詢）
  • userFundings資金費率支付
REST info 端點 · POST /info
  • meta / metaAndAssetCtxs品種規格 / 槓桿上限 / 市場資料
  • clearinghouseState帳戶快照（需 master 地址，5s 快取）
  • userFills成交歷史查詢
  • webData2進階帳戶數據
  • recentTrades歷史成交查詢（Feed 啟動時回補）
  • predictedFundings多交易所資金費率預測
下單端點 · POST /exchange（全部需 EIP-712 簽名）
  • orderlimit Gtc + market IoC 委託（testnet 驗證通過）
  • cancel / cancelByCloid取消委託（testnet 驗證通過）
  • modify / batchModify修改委託（testnet 驗證通過）
  • updateLeverage調整槓桿（動態 maxLeverage）
  • twapOrder / twapCancelTWAP 分批執行
  • approveAgent動態 Agent Wallet 授權 + MetaMask EIP-712 簽名
SC
規模架構 / 擴容模型
水平節點擴容 · Sticky Routing · 使用者不 lag
進行中
公開市場資料層（所有使用者共享）
  • 共享 HyperliquidEthFeed一個 feed 服務所有使用者，不重複連 Hyperliquid
  • 自訂區間 K線聚合31 種區間（18 自訂 + 13 傳統），server 端即時計算
  • 磁碟持久化raw trades NDJSON 存檔（K線即時聚合，不存磁碟）
  • SSE Pub/Sub Fanout1 broadcaster per (coin,interval) → N subscriber queues
  • 前端 IndexedDB 快取歷史 bars 存瀏覽器，重複訪問只補差量
  • 帳戶狀態 TTL 快取clearinghouseState 5s 快取，市場資料 30s 快取
  • 市場資料共享快取層多節點共用同一份市場狀態（Redis 或等效）
獨立資料收集器（standalone daemon）
  • 全品種 trades 收集獨立 systemd 服務，最多 400 並發 WS 連線
  • NDJSON 磁碟寫入per-coin per-hour 檔案切割
  • 品種列表自動刷新每 30s 查詢新品種並自動訂閱
私有帳戶層（per-user 隔離）
  • 帳戶 SSE 推流AccountStreamBroadcaster per wallet，WS 訂閱 + 30s HTTP 備援
  • Session 隔離不同使用者的帳戶資料完全隔離
  • workspaceId sticky routing同一 workspaceId 固定路由到同一節點
VM 節點水平擴容（託管版）
  • 用戶多 → 自動新增節點依照並發量自動擴容
  • 用戶少 → 自動縮減節點節省資源，避免閒置
用戶自託管（docker-compose up）
  • 完整版一行啟動docker-compose up → localhost:9120
  • 最小版（只看圖不下單）ROADSIGN_MODE=chart-only 已實作
  • config.yml 設定檔幣種 / 風控上限 / 自訂區間全部可設定
  • 環境變數配置HL_API_URL / HL_AGENT_KEY / ROADSIGN_MODE 等
分散式節點網路（長期）
  • 任何人的電腦都能成為節點節點對等，369pill.app 無特權
  • P2P 節點發現協議節點互相廣播，維持系統永久存活
  • 開源策略 / 指標插件生態社群可貢獻並分享
URL 路由結構
  • 多語言頁面路由/roadsign/{locale}/swap/{instrument}（zh-hant / en / ja）
  • API 路由/roadsign/api/v1/market/{instrument}/bars|stream
  • workspaceId#workspaceId=...&interval=...&tz=...（hash，client-side）
  • nginx sticky routing依 workspaceId header 導向對應節點
IE
Indicator Engine（共用服務）
技術指標計算引擎 · 純計算函式庫 · 圖表與策略共用同一套
運行中
指標庫（packages/roadsign_indicators/）
  • MA（SMA/EMA/RMA/WMA/VWMA）五種移動平均 · 可選來源欄位與週期
  • RSI相對強弱指標（Wilder's smoothing）
  • MACD快慢線 + 柱狀圖 + 訊號線
  • Stochastic KD隨機指標 %K / %D
  • OBVOn Balance Volume 量能趨勢
  • ZenTrend自研雙時間框架趨勢 · 共振箭頭
前端渲染（主圖疊加 + addPane 子圖）
  • MA 主圖疊加LineSeries 疊在 K線上
  • ZenTrend 主圖疊加雙線 + 填充 + HTF 階梯 + 箭頭標記
  • RSI / KD / MACD / OBV 子圖addPane 獨立面板 · 參考線 · 填充
  • 指標圖例 + 搜尋面板tag 條 / 即時數值 / 參數調整 / 可見度切換
對外 API
  • GET /api/v1/indicators/{coin}/{type}單一指標數值序列（6 種指標）
  • GET /api/v1/indicators/{coin}/multi一次取多個指標
  • pip install roadsign-indicatorspackages/ 已可用，尚未發布 PyPI
AS
Account State Manager（共用服務）
帳戶狀態單一真相 · 即時推流 · 所有需要帳戶資料的模組都從這裡讀
運行中
數據來源（Hyperliquid API）
  • clearinghouseState倉位 / 保證金 / 帳戶價值（5s TTL 快取）
  • frontendOpenOrders當前未成交委託
  • userFills成交回報查詢
  • markets()全品種列表（perp + tradfi，30s 快取）
對外 API
  • GET /api/v1/account/summary總權益 / 可用 / perp 餘額
  • GET /api/v1/account/positions當前倉位列表
  • GET /api/v1/account/orders當前委託列表
  • GET /api/v1/account/fills成交明細（可篩品種）
  • GET /api/v1/account/markets全品種列表（含 24h volume 排序）
  • SSE /api/v1/account/stream帳戶即時推流（WS 訂閱 + HTTP 備援）
安全規則
  • 查詢用 master address透過 HL_MASTER_ADDRESS 環境變數設定
  • per-user session 隔離不同使用者的資料完全隔離
EG
EffectGateway + Signing Layer（共用服務）
唯一下單出口 · EIP-712 簽名 · Agent Wallet nonce 管理
運行中
Agent Wallet 授權模型
  • approveAgent（一次性）動態 Agent Wallet 授權 + MetaMask EIP-712 簽名
  • EIP-712 每筆委託SDK sign_l1_action · testnet 驗證通過
  • nonce 管理毫秒時間戳（SDK get_timestamp_ms）
  • 動態 session 模式per-user gateway 或全域預設 gateway
對外 API（所有模組的唯一下單出口）
  • POST /execution/order限價 Gtc + 市價 IoC
  • POST /execution/cancel取消委託
  • POST /execution/modify修改委託
  • POST /execution/trigger止盈止損觸發單
  • POST /execution/leverage調整槓桿
  • POST /execution/trailing追蹤止損
  • POST /execution/twapTWAP 分批執行
Action Whitelist（強制安全邊界）
  • 交易操作order / cancel / modify / batchModify / updateLeverage
  • 進階操作updateIsolatedMargin / approveAgent / twapOrder / twapCancel
  • 資金操作封鎖withdraw3 / usdSend / spotSend 等資金移轉全部禁止
01
圖表系統
LightweightCharts v5 · 自訂區間 · 繪圖工具 · 指標疊加
運行中
K線圖表
  • 自訂區間 K線31 種區間（18 自訂 + 13 傳統）
  • SSE 即時更新bar 推流 + 變化偵測 + 心跳
  • 歷史分頁載入向左滾動自動補載 + IndexedDB 快取
  • 多品種切換310 品種動態列表 + 幣種選擇器
  • 圖表類型Candlestick / Heikin Ashi / Line
  • Chart Health 自修復自動偵測並恢復異常圖表狀態
繪圖工具（6 種 · LC Line Tools Plugin）
  • HorizontalLine / HorizontalRay水平線 · 射線 · OHLC 磁吸
  • TrendLine / Ray趨勢線 · 射線 · 磁吸對齊
  • FibRetracement費波那契回撤（11 級 · 可自訂係數）
  • PriceRange區間標注 · 漲跌幅 · HTML overlay
  • Object Tree SSOTlocalStorage 持久化 · 跨圖同步
  • Undo / Redo50 層撤銷堆疊
繪圖互動
  • Magnet 磁吸三模式（off / weak / strong）· OHLC snap
  • Quick Toolbar選取工具後浮動工具列（顏色/線寬/鎖定/刪除）
  • Color PickerHSV 色盤 + 透明度 + Hex 輸入 + 色票
  • 右鍵選單 / 雙擊設定統一物件互動層
  • 連續繪製模式繪完一個自動開始下一個
價格線系統
  • 支撐 / 阻力 / 警示線localStorage 持久化 · LC createPriceLine
  • 警示觸發價格穿越時狀態變為 hit
  • 持倉 / 委託疊加線即時更新持倉均價線 + 掛單線
02
下單系統
roadsign Order Module
運行中
委託類型
  • 限價委託Gtc 指定價格
  • 市價委託IoC 即時最優價
  • 止盈止損Trigger 條件觸發委託
  • 追蹤止損動態回撤跟隨 · 回撤百分比 · 激活價格
  • TWAP前端分批送出 · 自訂切片數 / 間隔
保證金 / 槓桿
  • 逐倉 / 全倉切換下拉選單切換 · 從倉位同步當前模式
  • 槓桿倍數動態 maxLeverage + 從倉位同步當前值
  • 可用保證金計算perp_value − total_margin_used
下單面板 UI
  • 價格自動帶入跟隨最新成交價 / 十字游標點擊帶入
  • 百分比快捷鍵25/50/75/100% · 自訂編輯 · localStorage 存取
  • 數量單位切換coin ↔ USDC 自動換算
  • 三模式 Tab手動 / 半自動 / 全自動
  • 手續費預估Maker 0.01% / Taker 0.035% 即時計算
  • SSE 帳戶即時更新餘額 / 倉位不靠輪詢
簽名層（Agent Wallet 模式）
  • approveAgent（一次性）動態 Agent Wallet + MetaMask 簽名授權
  • EIP-712 每筆簽名agent 簽，不需 MetaMask 彈窗
  • Action WhitelistAgent 禁止 withdraw / usdSend 等資金操作
  • 重試邏輯網路異常自動重試（3 次）
03
訂單報表系統
roadsign Positions & Orders Module
運行中
即時面板（SSE 即時推流 + HTTP 備援）
  • 當前委託品種 / 方向 / 數量 / 委託價 / 取消按鈕
  • 當前倉位持倉量 / 均價 / 標記價 / 強平價 / 浮動收益 / 平倉按鈕
  • 成交明細逐筆成交 / 手續費 / 已實現收益 · 品種篩選
  • 資產摘要總權益 / 可用 / 已用保證金 / 浮動收益
圖表疊加（Chart Overlay）
  • 持倉 overlay持倉均價線 + HTML 標籤（大小 / 即時 PnL / 平倉鈕）
  • 委託 overlay掛單價線 + HTML 標籤 · 支援拖拽改價
  • 快捷操作圖表上直接取消委託 / 修改價格 / 設定 TP/SL
倉位操作
  • 平倉彈窗市價 / 限價 · 百分比滑桿 · 即時 PnL 預估
  • 修改委託彈窗調整價格 / 數量
  • 追蹤止損彈窗回撤百分比 / 激活價格設定
  • TP/SL 彈窗止盈止損設定 · 即時標記價更新
  • 一鍵全部平倉市價平倉所有持倉
歷史查詢
  • 成交歷史篩選品種篩選 UI
  • 歷史委託篩選日期 / 品種 / 方向
  • 資金費率歷史userFunding REST
04
管理者後台系統
roadsign Admin Module
進行中
健康監控（/roadsign/admin）
  • 系統健康 APIGET /api/v1/admin/health · uptime / feed / memory
  • 管理後台頁面即時監控面板 · 3s 自動刷新
  • Feed 健康WS 連線狀態 / 延遲 / 斷線次數
前端狀態列
  • 串流健康指示燈SSE 連線狀態 + 延遲顯示
  • K線倒數計時距離下一根 bar 的秒數
  • OHLC 圖例十字游標 / 最新 bar 的 OHLCV 數值
未來擴展
  • 用戶管理帳號審核 / 權限分級
  • API 響應監控端點延遲 / 錯誤率
  • 節點負載各 VM 節點 CPU / 記憶體
05
會員 / 推薦系統
roadsign Member + Referral Module
進行中
錢包連線（MetaMask）
  • MetaMask 連線eth_requestAccounts + 地址顯示
  • Agent Wallet 授權EIP-712 簽名彈窗 + 動態 session
  • 自動重連頁面載入時從 localStorage 恢復
  • Session 持久化wallet_sessions.json 磁碟存檔
推薦系統
  • 生成推薦碼RS-XXXXXXXX（per-wallet 唯一）
  • 套用推薦碼新用戶綁定推薦人（防自推 / 防重複）
  • 推薦統計查詢被推薦人數量
  • 推薦碼查詢反查推薦碼歸屬
Workspace 偏好
  • 時區 / 週期 / 佈局hash 參數已實作（#workspaceId=...）
  • 個人盈虧統計日 / 週 / 月 績效分析
  • 勝率 / 盈虧比品種分佈分析
06
自動交易託管系統
roadsign AutoTrader Module
進行中
訊號接入
  • REST Webhook外部策略訊號 → 自動下單
  • 內建策略引擎BaseStrategy 插件介面 + 策略輪詢迴路
  • MACD DivergenceMACD 柱狀圖零交叉策略
  • Webhook Relay外部訊號透通策略（TradingView 等）
風控（RiskGuard）
  • 最大倉位上限RiskConfig 限制單品種 / 總倉位
  • 每日虧損熔斷超限自動停止
  • 最小 / 最大委託量min_order_size_usd / max_order_size_usd
  • Action 安全過濾FORBIDDEN_ACTIONS 封鎖資金移轉
API
  • POST /autotrader/start啟動策略 · 指定幣種 / 週期 / 參數
  • POST /autotrader/stop停止策略
  • GET /autotrader/status策略狀態（total_signals / total_orders / rejected）
  • POST /autotrader/webhookWebhook 訊號即時執行
執行引擎
  • HTTP loopback透過自身 API 取得 bars / indicators / 提交委託
  • TP/SL 自動下單策略訊號包含 tp / sl 自動提交觸發單
  • 策略績效Sharpe / Alpha / 執行日誌