現貨持倉視角
聚焦 large-cap allocation（大型幣配置），不處理合約或自動下單。
Overview
先判斷持倉風險，再產生可追溯建議
這個 showcase（展示頁）用人類可檢查的方式說明：資料如何從 read-only sync（唯讀同步）進入資料庫、如何被風險模型與建議引擎消化，以及哪裡留下 audit trail（稽核軌跡）。
風險護欄
用 target weights（目標權重）、risk limits（風險限制）與 stress test（壓力測試）降低任意建議。
決策留痕
每次產生 advice（建議）都能回到 prices、positions、config 與 decision logs。
Dynamic Pipeline
Dynamic Pipeline（水管線路圖）
這條水管線路圖表現資料流，不是裝飾。每個節點都能對應到 repo 內的 module（模組）、API 或資料表。
交易所同步是唯讀入口
`binance_sync.py` 與 `okx_sync.py` 只讀取現貨持倉。API keys（API 金鑰）留在 `.env`，不得提交。
資料庫保存可追溯狀態
`sql/` 定義 positions（持倉）、prices（價格）、advice_logs（建議紀錄）與 decision_logs（決策紀錄）。
風險特徵是建議前置條件
`risk_features.py` 與 market price jobs（價格工作）提供 drawdown、long-window metrics（長週期指標）與 stress-test inputs（壓力測試輸入）。
建議不等於交易
`advice.py` 產生 target-weight advice（目標權重建議），但不連接任何下單能力。
提醒有優先級與時間窗
`alerts.py` 依 P0/P1/P2 policy（政策）決定即時或排程通知，避免所有訊號都打擾使用者。
API 可以回看決策歷史
`/decision/history`、`/advice/history` 與 audit tables（稽核表）讓人類 reviewer（審查者）追蹤建議來源。
System Architecture
System Architecture（系統架構）
系統分層重點是「API 表面薄、service 層承擔規則、資料層保留追溯」。這樣新增交易所或新風險指標時，不需要重寫整個 API。
API Layer`app/api/routes.py`：health、portfolio、risk、advice、config、sync endpoints
Scheduler Layer`app/main.py`：sync、price ingest、risk feature、alert jobs
Operations Docs`docs/OPERATIONS/`：release、backfill、scheduler recovery
Core Domain
Portfolio intelligence + risk guardrails
核心規則集中在 `app/services/`，包含 portfolio aggregation（投資組合彙總）、asset mapping（資產對照）、risk features（風險特徵）、advice generation（建議產生）與 alerts（提醒）。
Data LayerPostgreSQL / TimescaleDB、`sql/schema.sql`、migration files
Config Layertarget weights、risk limits、sync schedule、asset mapping
Test Layer`tests/`：API smoke、risk、alerts、advice、config regression
User Architecture
User Architecture（使用者架構）
使用者不是被系統自動代操，而是 review（審查）建議、調整配置、維護風險邊界的人。
設定資料來源與同步
維護 `.env`、read-only exchange keys（唯讀交易所金鑰）、sync schedule（同步排程）與 Docker runtime（執行環境）。
審查投資建議
查看 portfolio risk（投資組合風險）、stress test（壓力測試）與 advice history（建議歷史），再自行決策。
維護規則與稽核
更新 target weights（目標權重）、risk limits（風險限制）與 audit policy（稽核政策）。
Verification Panel
Verification Panel（驗證面板）
文件補強與 runtime（執行環境）驗證分開。這裡先保證 repo documentation（文件）可讀且邊界清楚。
Scaffold check（骨架檢查）
powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\verify.ps1確認 README links（README 連結）、showcase（展示頁）與基線文件存在。
Runtime tests（執行測試）
pytest
docker compose up -d --build完整服務驗證需在有 Docker、DB 與測試依賴的環境執行。
System architecture 對應到 `app/`、`sql/`、`docs/OPERATIONS/`。
Pipeline 節點可追到實際 service（服務）或 API。
Showcase 不讀取 API、database（資料庫）或 exchange account（交易所帳戶）。
真實 portfolio data（投資組合資料）與 API keys 不進 repo。
Advice（建議）明確標示為 no auto-trading（不自動交易）。
Browser QA 需確認 desktop/mobile 無橫向溢出。
Private Data Boundary
展示頁只描述系統
真實持倉、交易所金鑰、Telegram token、DB dumps 與 runtime logs 不得提交。本頁所有數值與流程都是靜態說明。