跳轉到

ADR-0001: 上市融資維持率（每日盤後指標，live 計算）

  • Status: Accepted
  • Date: 2026-06-14
  • PR / Commit: #427（基礎指標）、#428 df1baa86（previous-day change 延伸）
  • 相關: follow-up issue #426（全市場版）、docs/API_SPEC.md、docs/api-reference.md

Context

每日盤後市場面需要一個「上市融資維持率」指標：融資戶整體擔保品市值相對融資金額的比率， 是觀察市場槓桿風險的常用訊號。當時的限制：

  • 沒有官方逐日「上市融資維持率」數值可直接抓 —— 只有官方「上市融資金額（元）」。 分子（擔保品市值）得自己從個股融資張數 × 收盤價聚合。
  • 不想動 schema：這是衍生指標，不應為它新增資料表 / 欄位、也不該跑歷史 backfill。
  • 上市 / 上櫃分母來源不同：官方上市融資金額只含上市（TWSE）；上櫃（TPEx）每日只公布 張數、不公布金額（元），分母湊不齊。所以這一版只能先做上市。

Decision

在 GET /api/daily-market/{trade_date}?market=taiwan（及 /latest）的 margin payload 新增巢狀欄位 twse_listed_maintenance_ratio，並在 data_status 加對應 key。Live 計算、無 schema 變動。

公式：

維持率(%) = Σ(上市個股融資張數 × 收盤價 × 1000) ÷ official_market_margin_balance_amount × 100
  • 分子：margin_balance（source_market='TWSE'）JOIN stock_ohlc 即時聚合。 source_market='TWSE' 是排除上櫃的關鍵 —— 整合測試證明 TPEx 個股不計入分子。
  • 分母：官方上市融資金額。
  • 欄位以 label="上市融資維持率" + scope="twse_listed" 明確標注僅含上市，避免被誤讀為全市場。
  • Status gating 四情境：available / pending_source / no_data / non-taiwan，皆有測試。

延伸（#428）：新增 previous_day_change（與前一個可用交易日的百分點差），對齊 index / turnover 既有的 previous_day_change 慣例。新 loader _load_previous_market_margin_row 取前一可用日的官方融資金額作分母，分子重用既有 collateral loader。前一日 no_data 條件： 今日無值、無前一日、gap > 10 日（stale）、或前一日不可計算。

實作位置：investment-agent/backend/services/daily_market_service.py （builders、_load_previous_market_margin_row）。

Consequences

正面

  • 市場面多了一個槓桿風險訊號，零 schema 成本、零 backfill。
  • 真實資料驗收（真實 DB run，記錄於 PR #427 / commit df1baa86，非單元測試 mock 的近似值）： 2026-06-12 value=193.2（matched_stocks=1205，與 DB 試算一致）； previous_value=188.87（2026-06-11）→ value_change=+4.33。
  • 效能：#428 把 collateral 聚合的時間範圍改成綁在 trade_date 參數的常數邊界 （而非 join 後的 mb.trade_date），讓 planner 在 join 前就用 idx_ohlc_timestamp 裁剪 stock_ohlc —— EXPLAIN cost 111611→12574，約 168ms→29ms（連帶加速已上線的當日路徑）。

代價 / trade-off

  • 只含上市：分子刻意排除上櫃，因為上櫃分母（融資金額元）湊不齊。scope 欄位誠實標注此限制。
  • Live 計算每次請求都要聚合，靠上述 index 裁剪把成本壓住。

後續 follow-up

  • #426：全市場（上市+上櫃）版 —— 需先找到每日上櫃融資金額（元）來源（TPEx 信用交易統計 / FinMind 上櫃 total / 付費源）。此為 ROADMAP 的 Now 項目。
  • 本版不做：融資使用率、個股維持率、歷史 backfill、存入 market_chip_metrics。