QUANTSAAS · v0.1Phase 13 / 13 · 全天候智能量化管理工具

將華爾街級風控狀態機與遺傳演算法
降維為一鍵託管的 SaaS 財富水庫

系統定位為三端解耦的量化交易管理工具：SaaS 雲端 負責決策、LocalAgent 負責執行、Lab 算力面 負責進化。 策略模組（Step()）為純函數無狀態轉換器，回測與實盤共用同一實作，由 GA 自動搜尋最優參數， 人工 Promote 後驅動實盤。

三端物理部署形態

System Topology
☁️SaaS 雲端
app_role: saas · 決策大腦
開放能力
  • 策略模板管理
  • 實例管理（建立 / 啟停 / 刪除）
  • 透過 cron 觸發 Step()
  • 交易指令下發（WebSocket Hub）
禁區
  • 持有交易所 API Key
  • GA 進化運算
  • 回測運算（Lab 才能跑）
💻LocalAgent 執行端
用戶本地 · 執行手
開放能力
  • 接收 TradeCommand
  • 呼叫交易所 REST 下單
  • 上報 DeltaReport（成交 + 餘額）
  • 心跳維持 + 自動重連
禁區
  • 任何策略代碼
  • 連接資料庫
  • 自主決策
  • 繞過 SaaS 直接下單
🔬Lab 算力面
app_role: lab · 實驗室
開放能力
  • GA 進化任務
  • 回測批量運算
  • 挑戰者基因產出
  • 與雲端共用同一 Postgres
禁區
  • 真實交易指令下發
  • 實例啟停（只讀）
  • 操作正式用戶資料

三份真源文檔

Source of Truth · docs/quantsaas/
§01系統總體拓撲
docs/quantsaas/01-系統總體拓撲.md
三端部署形態（SaaS / Agent / Lab）、四大邏輯模組邊界、雲端 ↔ 端側通訊協議全表、生命週期動作、十一條鐵律完整版。
三端TradeCommand / DeltaReport十一鐵律
§02策略數學引擎
docs/quantsaas/02-策略數學引擎.md
Step() 契約、資產三態、市場狀態（NORMAL / VOLATILE / QUIET）、宏觀 DCA 引擎、Sigmoid 動態天平、20 維染色體與 SpawnPoint。
Step()Sigmoid 動態天平20 維染色體
§03進化計算引擎
docs/quantsaas/03-進化計算引擎.md
多時段坩堝視窗（6m / 2y / 5y / 10y）、適應度公式、Ghost DCA 基準、級聯短路、EvolvableStrategy 八動詞契約。
坩堝視窗Ghost DCA八動詞

測試與驗證

Vitest · 22 tests passed · 414ms
所有測試覆蓋 plan §11 規定的四大區域 + lifecycle 額外驗證。 指令：pnpm test（vitest run）／ pnpm test:watch。
6 ✓
quant/microEngine.test.ts
Sigmoid 6 個性質：Signal/TargetWeight 方向、中性點、純函數確定性、楔形區過濾
2 ✓
ga/backtest.test.ts
回測決定性（相同輸入 → 相同輸出）、不足資料 emptyResult
3 ✓
ga/engine.test.ts
變異斜坡公式、Fatal 個體錦標賽選中率 < 5%、runEpoch 完整流程
4 ✓
hub/memoryHub.test.ts
Long-poll timeout / notifyUser push / 立即查詢 / 心跳追蹤
7 ✓
instance/lifecycle.test.ts
7 種狀態轉換（合法 + 非法 + audit log）
Vitest run output：
Test Files 5 passed (5)　·　Tests 22 passed (22)　·　Duration 414ms
代碼位置：src/lib/quantsaas/**/*.test.ts　· 下一步 Phase 12 為前端 dashboard 完整版（Templates / Instances / Evolution / Agents / Settings 頁面）

系統入口 + Cron Tick

instrumentation hook · vercel.json · graceful shutdown stub
cold-start boot 流程
1
register hook 觸發
src/instrumentation.ts (Next.js nodejs runtime)
2
載入 config
zod 校驗 env；缺欄位 fallback dev role
3
取得 sharedRepo
MemoryRepo singleton + seed demo user/instance
4
取得 sharedHub
connection registry 初始化
5
恢復 RUNNING 實例
listRunningInstances → 數量寫入 boot state
6
紀錄 bootedAtMs
globalThis __quantsaas_boot__ 跨 HMR 保留
Phase 10 新增 endpoints
GET/api/quantsaas/cron/scheduler-tickVercel cron 觸發點，CRON_SECRET 認證
GET/api/quantsaas/v1/system/status健康檢查（公開），含 boot / cron / agent 狀態
vercel.json
{ "crons": [
    { "path": "/api/cron/hourly-pnl",                "schedule": "0 0 * * *" },
    { "path": "/api/quantsaas/cron/scheduler-tick",  "schedule": "0 1 * * *" }
  ]}
Vercel Hobby plan 每日上限 2 cron；Pro 可改 * * * * * 每分鐘。
運作流程：cold-start 後 bootSystem 一次性初始化、cron 每 tick 跑完 scheduler 後 寫入 lastTickResult，/v1/system/status endpoint 統一回報 boot / cron / agent 三區塊狀態（auth 驗證後可查）。
代碼位置：src/instrumentation.ts、src/lib/quantsaas/bootstrap.ts　· 下一步 Phase 11 將實作核心模組的單元測試（Sigmoid 性質 / 回測決定性 / GA 行為）

REST API v1（完整路由 + Auth 中介層）

16 endpoints · /api/quantsaas/v1/*
所有 v1 endpoints 經 requireAuth（JWT Bearer）+ 可選 role gate （requireLabRole / requireSaasRole）。Auth token 支援 jose JWT（QUANTSAAS_JWT_SECRET 設定後）或 demo 簡化格式 demo-{userId}-{rand}。
Auth (public)POST/v1/auth/registerpublic
Auth (public)POST/v1/auth/loginpublic
AuthGET/v1/auth/meany
StrategiesGET/v1/strategiesany
InstancesGET/v1/instancesany
InstancesPOST/v1/instancesany
InstancesGET/v1/instances/:idany
InstancesDELETE/v1/instances/:idany
InstancesPOST/v1/instances/:id/startany
InstancesPOST/v1/instances/:id/stopany
DashboardGET/v1/dashboardany
Evolution (lab)GET/v1/evolution/tasksany
Evolution (lab)POST/v1/evolution/taskslab
Evolution (lab)POST/v1/evolution/tasks/:id/promotelab
GenomeGET/v1/genome/championany
GenomeGET/v1/genome/challengersany
典型流程：register → login → me → 401 check → strategies → create instance → start → dashboard → POST evolution task → promote challenger → champion 切換 → stop → delete。實際資料需登入 dashboard 後檢視。
代碼位置：src/app/api/quantsaas/v1/　· 中介層：src/lib/quantsaas/auth/middleware.ts　· 下一步 Phase 10 將實作系統入口（優雅停機 + 狀態快照 + 信號處理）

Push Hub（long-poll 替代 WebSocket）

globalThis singleton · notifyUser · 心跳追蹤
⚠ 為什麼不是真實 WebSocket
Vercel serverless 不支援長連線（請求被 30s timeout）。本實作改用 long-polling + notifyUser：agent 打 long-poll，server 持有 request 直到 scheduler 產出指令或 25s 後 timeout。 等價 WS push 語意，push 延遲降至毫秒級（vs 30s 固定 polling）。
訊息類型契約與原 Plan 完全對齊，後續切到 Cloudflare Durable Objects / 自建 WS 伺服器只需替換 Hub 實作層。
Plan 訊息類型 ↔ HTTP endpoint 對映
auth→POST /api/quantsaas/agent/authPhase 7
heartbeat→POST /api/quantsaas/hub/heartbeatPhase 8
command (push)→GET /api/quantsaas/hub/long-pollPhase 8
command_ack→implicit（long-poll resolve 即視為收到）Phase 8
delta_report→POST /api/quantsaas/agent/delta-reportPhase 7
report_ack→同 endpoint 之 200 回應Phase 7
Phase 8 新增 endpoints
GET/api/quantsaas/hub/long-poll?userId=X&timeoutMs=25000Block 直到有指令或 timeout（push 等效）
POST/api/quantsaas/hub/heartbeat每 30 秒心跳（更新 lastSeenMs）
GET/api/quantsaas/hub/status[?userId=X]查詢單一 user 或全部 connected 狀態
Push 延遲特性：開 long-poll → scheduler 產生指令時呼叫 notifyUser → server 立即 resolve 該 poll（毫秒級），無需等到下次 polling 週期。 相較固定 30s polling，延遲縮短一個數量級。
代碼位置：src/lib/quantsaas/hub/　· 下一步 Phase 9 將整合所有現有 endpoints 加 JWT auth + role gate（saas / lab / dev）

LocalAgent 執行端

@quantsaas/agent · HTTP polling · MockExchange
1
authenticate
email/password → JWT + instances
2
送初始 DeltaReport
當前餘額快照，clientOrderId=null
3
pollCommands
GET pending 指令陣列
4
exchange.placeOrder
呼叫交易所 API（MockExchange 或真實實作）
5
sendDeltaReport
POST execution + balances 給 SaaS
6
sleep + 回到 3
pollIntervalMs（預設 30s）
7
斷線指數退避重連
1s → 2s → 4s ... 上限 5 分鐘
SaaS 端 endpoints
POST/api/quantsaas/agent/auth登入取 JWT + 取得 instance 清單
GET/api/quantsaas/agent/commandsPoll pending TradeCommand（每 30 秒）
POST/api/quantsaas/agent/commands觸發 scheduler tick（測試用）
POST/api/quantsaas/agent/delta-report上傳成交回報 + 餘額快照
POST/api/quantsaas/agent/reset重置共享 MemoryRepo（測試用）
🔑 鐵律 §5：API key 物理隔離
交易所憑證只存在於 config.agent.json（已在 .gitignore）， 永不進 SaaS、永不寫 DB、永不上雲。
MockExchange 模擬瞬時成交（0.1% slippage + 0.05% fee）。 真實 Pionex/OKX/Bitget 後續可實作 Exchange 介面替換。
啟動 Agentcd packages/quantsaas-agent && pnpm start
代碼位置：packages/quantsaas-agent/　· README：packages/quantsaas-agent/README.md　· 下一步 Phase 8 將實作真實 WebSocket Hub（替代 polling）

實例生命週期 + Cron Tick

InstanceRepo · 狀態機 · 9 步驟 Tick
STOPPED→RUNNINGstart
RUNNING→STOPPEDstop
RUNNING→ERROR異常觸發
any→DELETEDdelete
1
幂等桶去重
latestBarMs <= lastProcessedBarMs → skip
2
讀狀態
PortfolioState / RuntimeState / Lots / 冠軍參數
3
ACL 降級
Bar[] → closes + timestamps（鐵律 §4）
4
建 StrategyInput
注入 nowMs / 帳戶 / 參數
5
呼叫 step()
與回測共用同一純函數（鐵律 §2）
6
持久化 Runtime
setRuntimeState（含 lastMacroBuyMs / 累計）
7
落地 release
splitLot + 寫 audit（鐵律 §9：不下發）
8
翻譯 commands
inst{id}-{engine}-{ts} + pending 紀錄
9
更新 lastBar
updateLastProcessedBar 避免重跑
內部煙霧測試GET /api/quantsaas/tick-testlifecycle + 3 輪 tick + 幂等驗證（dev 環境呼叫）
代碼位置：src/lib/quantsaas/instance/　· 下一步 Phase 7-8 將實作 LocalAgent + WebSocket Hub 把 pending commands 真實下發

GA 進化引擎

EvolvableStrategy · 八動詞契約
1strategyId回傳策略識別字串
2sample從合法空間隨機採樣基因
3mutateBernoulli + 加性高斯變異
4crossoverUniform 50% 每維獨立選
5fingerprintFNV-1a-64（1e-6 量化）
6evaluate4 坩堝視窗 + 級聯短路
7decodeEliteJSON → Gene（fallback default）
8encodeResultGene + Spawn → ParamPack JSON
Epoch 流程
1. 種群初始化（10% 精英 + 40% 強化變異 + 50% 隨機）
2. 並發評估（指紋快取去重，預期命中率 15-30%）
3. 主迴圈：排序 → 收斂偵測 → 變異斜坡 → 精英保留 → 錦標賽 + Crossover + Mutate
4. Early Stop（mutation 雙上限 + 連續無改善）
5. 輸出 challenger 寫入 DB，等待人工 Promote
內部煙霧測試GET /api/quantsaas/ga-testMini epoch（POP=8, GEN=3）· dev 環境呼叫
代碼位置：src/lib/quantsaas/ga/　· 下一步 Phase 6 將以 cron + 背景 worker 推進真實 epoch（POP=300, GEN=25）

Step() 策略決策流程

sigmoid-balance-v1 · 純函數無 I/O
1
資料窗口檢查
closes.length >= 200 否則回空 output
2
總帳計算
TotalEquity / SpendableUSDT / CurrentMicroWeight
3
市場狀態
NORMAL / VOLATILE / QUIET → 超參輸出
4
軟釋放決策
DeadStack → Float（只更帳，不下單）
5
宏觀引擎
DCA 觸發 + 死線兜底，產 BUY 意圖
6
微觀引擎
Sigmoid 動態天平 6 步驟產 OrderUSD
7
微觀意圖翻譯
SELL 時硬釋放補足 Float
8
RuntimeState 更新
lastMacroBuyMs / cumulativeMicroNet
9
組裝輸出
intents + releases + marketState + microDecision
內部煙霧測試GET /api/quantsaas/step-test合成 K 線跑一次 Step()（dev 環境呼叫）
代碼位置：src/lib/quantsaas/strategies/sigmoid-balance-v1/　· 下一步 Phase 5 將實作 GA 進化引擎包裹此 Step() 跑回測尋優

量化數學基礎層

9 modules · src/lib/quantsaas/quant/
L0math.tsEMA / stdDev / mavAbsChange / clip / logReturns
L0data.tsBar / StrategyInput/Output / TradeIntent / RuntimeState
L0closes.tsACL 降級 — Bar[] → number[]（鐵律 §4）
L1genome.ts20 維 Chromosome + HARD_BOUNDS + clampChromosome
L1lot.tsDeadBtc/FloatBtc 總量 + 軟釋放 / 硬釋放
L2marketState.tsNORMAL / VOLATILE / QUIET 三態感知 + 超參輸出
L2macroEngine.tsDCA + 死線兜底（只 BUY、never SELL）
L2microEngine.tsSigmoid 動態天平 — 6 步驟（系統核心創新）
L2ghostDca.ts被動 DCA 基準 + Modified Dietz ROI + MaxDD
L0 基礎層 / L1 資產與基因 / L2 引擎與基準　·　Phase 4 將組裝 Step() 主函數

DB Schema

Drizzle ORM · Code-First · 12 model
users使用者 + 訂閱配額
strategy_templates策略模板註冊表 + Manifest
strategy_instances實例（模板 + 標的 + 配額）狀態機
portfolio_states即時帳戶快照（USDT / Dead / Float / ColdSealed）
runtime_states策略內部運行狀態 JSON
spot_lots仓位 lot（三態 + 老化）
trade_records已成交紀錄（UI / 審計）
spot_executions下發指令執行狀態機 pending→filled
audit_logs所有 PortfolioState 變更 + 指令下發
gene_records基因庫 challenger / champion / retired
evolution_tasksGA 任務追蹤 + 進度
klines歷史 K 線（symbol+interval+openTime UQ）
Schema 真源：packages/dashboard/src/lib/quantsaas/db/schema.ts　· 同步至 DB：pnpm drizzle-kit push（取代 GORM AutoMigrate）

四大邏輯模組

Logical Modules
Strategy 策略模組
策略模板註冊表，定義參數結構、版本、現貨 / 合約類型。Step() 是策略決策唯一外部入口。
Instance 實例模組
實例 = 策略模板 + 標的 + 資金配額 + 使用者。負責生命週期與運行狀態。
Evolution 進化模組
GA 對策略參數進化迭代，產出 challenger，人工 Promote 為 champion 後驅動實盤。
Auth 認證模組
使用者註冊 / JWT 簽發 / 訂閱配額守門，不涉入策略邏輯。

十一條鐵律

Iron Laws · 違反必停
§01複利前置條件
所有策略設計必須能說明複利如何發生；無法論證複利的策略不開發。
§02策略同構原則
回測與實盤共用同一個 Step()；禁止 if isBacktest 分支。
§03策略內部純淨原則
Step() 內禁止定時器、網路、DB、檔案 I/O；只吃 StrategyInput 吐 StrategyOutput。
§04現貨策略 ACL OHLC 剝離
策略內核只消費 [number] 收盤序列，OHLCV 降級在 ACL 外圈完成。
§05API Key 物理隔離
交易所 Key/Secret/Passphrase 只存 LocalAgent 本地檔，永不進 SaaS。
§06Schema Code-First
資料庫結構以 Code 為真源（TS 等價於 GORM AutoMigrate），不寫 SQL migration。
§07無量綱計算
價格計算用對數收益率或比率，禁止跨標的比較絕對價格。
§08倉位三態
DeadStack（長期底倉）/ FloatStack（浮動倉）/ ColdSealed（封存）語義不可混用。
§09底倉釋放只更帳，不下單
DeadStack → Floating 僅更新 SaaS 帳本，不向 Agent 發指令，必寫審計日誌。
§10單一資料庫，無分庫
Postgres 單例；Redis 僅作快取，不承擔信號傳遞。
§11使用者介面零數學
對使用者文案避免裸希臘字母、內部狀態機名、無上下文數學量名。

開發 Phase 進度

13 / 13 完成
✓
Phase 0 — 環境初始化與基礎設施DONE
Sidebar 入口、系統總覽頁、視覺主題
✓
Phase 1 — 三份真源文檔DONE
系統拓撲 / 策略數學引擎 / 進化計算引擎（繁中設計稿 docs/quantsaas/）
✓
Phase 2 — 基礎設施層DONE
zod Config + Drizzle Schema（12 model）+ jose JWT + Redis namespace
✓
Phase 3 — 量化數學基礎層DONE
9 個 quant 模組：math / data / genome / lot / marketState / macro / micro / ghostDca / closes
✓
Phase 4 — 策略主函數 Step()DONE
sigmoid-balance-v1：manifest + params + step 三檔；含 /api/quantsaas/step-test 煙霧測試
✓
Phase 5 — GA 進化引擎DONE
八動詞契約 + 4 坩堝視窗 + 級聯短路 + 變異斜坡 + 指紋快取；GA-test 已通過
✓
Phase 6 — 實例生命週期 + CronDONE
InstanceRepo + 狀態機（start/stop/error/delete）+ Tick + Scheduler；tick-test 已通過
✓
Phase 7 — LocalAgent 執行端DONE
@quantsaas/agent package、HTTP polling、MockExchange、配對 3 個 SaaS endpoints；端到端通過
✓
Phase 8 — Push Hub（long-poll）DONE
globalThis singleton + notifyUser + 心跳 + 連線狀態；push 延遲 ~500ms（vs polling 30s）
✓
Phase 9 — REST API 路由DONE
12 個 v1 endpoint + Auth middleware + role gate；12 步驟端到端驗證通過
✓
Phase 10 — 系統入口 + CronDONE
instrumentation hook + bootSystem + vercel cron + status endpoint
✓
Phase 11 — 測試與驗證DONE
Vitest 22 個測試覆蓋 Sigmoid / 回測 / GA / Hub / Lifecycle；全部 passed 414ms
✓
Phase 12 — Web 前端完整版DONE
Login / Dashboard / Instances / Evolution / Agents + Shell；全部 client component + SWR
QuantSaaS · 全天候智能量化管理工具 · Phase 0 · 本頁來源：系統架構設計.md + 進化文檔.md + Plan[含phase和提示词].md