即時大盤、盤中圖表與持股期間基準

本文件補充 API reference 中既有的股票即時快照、SSE、持股批次報價及績效契約。以下新增端點皆需 Authorization: Bearer <access_token>，且會員的有效權限須含 realtime_quote: true（目前只有 admin 開啟；規則見 API reference 的「即時報價權限」），否則回 403 FEATURE_REQUIRED；只讀已存快照及會計資料，不呼叫供應商、不寫入日 OHLC。

GET /api/market/realtime-quote、/api/market/realtime-quote/stream

加權指數專用入口，固定讀取 FinMind 001，以日資料識別碼 ^TWII 表示。沒有 path/query/body，不變更股票端點的 .TW / .TWO 驗證。

REST 200 application/json：{ticker:"^TWII",status:"available"|"no_data",quote:RealtimeQuote|null}。完整 quote 欄位及 nullable 型別沿用 API reference 的股票快照表；quote.stock_code="001"、quote.name="加權指數"。價格為指數點數，total_amount 等金額為元；trading_date 為 YYYY-MM-DD，quote_time 及 fetched_at 為 UTC ISO-Z，顯示轉 Asia/Taipei。no_data 時 quote 為 null。

實際快照節錄：{"ticker":"^TWII","status":"available","quote":{"stock_code":"001","name":"加權指數","trading_date":"2026-10-08","quote_time":"2026-10-08T01:26:55Z","open":49783.06,"high":49783.06,"low":49243.31,"close":49280.79,"change_price":-525.58,"change_rate":-1.05,"total_amount":254968131730}}。其餘原 quote 欄位仍存在且允許 null。

SSE 200 text/event-stream：event: msg，data 沿用 quote 事件 JSON，不含 ticker wrapper。quote 帶 status 和 quote；session_closed、token_expired、unauthorized 為原終止事件。保留 keep-alive 註解、短連線 DB 查詢、每輪重驗 token、14:35:10 收盤截止及既有 headers。連線 HTTP 401 刷新後重試一次；token_expired 刷新重連；網路錯誤或非正常 EOF 隔 10 秒重連；session_closed/unauthorized 不重連。

缺 Authorization 回 422 FastAPI detail；401 error.code=INVALID_TOKEN|TOKEN_EXPIRED、403 MEMBER_SUSPENDED 或 FEATURE_REQUIRED（無 realtime_quote 權限；串流連線時即回、不開始送事件），完整 error envelope 為 {error:{code,message,details}}，與原股票端點相同。串流中失去權限時送 unauthorized 後結束。

首頁共享一條指數串流，只在可確認的交易日 09:00–13:30、登入且頁面可見時連線，卸載 abort。no_data 或無效價格保留日資料；即時日期不推進日資料 anchor。盤中成交金額另標 FinMind／億元，不混入官方日成交值、MA、廣度、法人或籌碼。即時日 K 的股數 volume 和官方成交值 bar 留 null。

GET /api/stocks/{ticker}/intraday-ohlc

取得最新保留交易日的單日盤中 K 和分時價格。ticker 為已收錄的 .TW / .TWO 台股；query interval=10s|1m|5m 可選，預設 5m，無 body 或分頁。

200 application/json：

{
  "ticker": "2330.TW", "status": "available", "trading_date": "2026-10-07",
  "opening_price": 2565.0, "interval_seconds": 300,
  "interval_minutes": 5, "source": "quote_snapshots", "volume_unit": "lots",
  "candles": [{
    "time": "2026-10-07T01:00:00Z", "open": 2565.0, "high": 2580.0,
    "low": 2565.0, "close": 2575.0, "volume": 3752,
    "last_quote_time": "2026-10-07T01:04:59.893847Z", "closed": true
  }],
  "price_series": [{"time": "2026-10-07T01:04:59.893847Z", "price": 2575.0}]
}

欄位型別：ticker 為 string；status 為 available/no_data；trading_date 為 YYYY-MM-DD 或 null；opening_price 為 number 或 null；interval_seconds 為 10/60/300，interval_minutes 為 null/1/5；source 固定 quote_snapshots；股票 volume_unit 固定 lots。candles 和 price_series 必定為陣列。

Candle 的 time/last_quote_time 為 UTC ISO-Z，open/high/low/close 為有效 number，volume 為 integer 或 null，closed 為 boolean。Price point 為 {time:UTC ISO-Z,price:number}。資料按時間升序，10 秒／1 分／5 分最多 1620／270／54 根 K。上述節錄為 2026-10-07 2330 已存快照。

time 是區間起點，OHLC 是區間內已觀察 close 的首／最高／最低／末價，不是日 OHLC，也不保證包含全部成交。last_quote_time 是最後有效價格的成交時間，closed 表示區間已結束。僅納入台北 09:00–13:30；13:30 收盤成交歸各週期最後一桶，排除盤後、未來和日期不符的快照。

volume 為區間成交量「張」，由相鄰桶末累積量差計算；09:00 桶以 0 為基準。缺相鄰基準、null 或倒退 counter 回 null，不能當成 0。缺區間不補造 K 棒。官方日 OHLC 量為「股」，兩者不能混用。

price_series 不隨 K 週期變粗，始終為 10 秒桶最後有效快照的實際成交時間和價格，最多 1620 筆，與 candles 共用一次 DB 讀取。opening_price 是當日快照報告的最後有效 open；缺值為 null，不以第一筆保留 close 代替開盤價。

no_data 回 trading_date/opening_price 為 null、candles/price_series 為空，其餘常數及所選週期照常存在。只提供最新保留交易日，無日期切換。

缺 header 或非法 interval 回 422 validation detail；token 無效／過期 401、停權 403、無 realtime_quote 權限 403 FEATURE_REQUIRED（先於 ticker 與 interval 驗證）、ticker 不存在或非台股 404，沿用 API reference 的 {error:{code,message,details}}。

前端先讀 history，之後依原 quote SSE 的狀態變更重新讀取，不新增 SSE。history 可於盤後讀取；quote 呼叫仍限制開盤時段。分時 X 軸固定今日台北 09:00–13:30，以報告的開盤價分段紅綠，不把舊交易日曲線冒充今日；K 模式標示實際資料日期及快照來源。

GET /api/market/intraday-ohlc

固定 FinMind 001 / ticker ^TWII，不使用股票 ticker resolver。Bearer 必填；無 path/body，interval query 和股票 history 相同，預設 5m。回應沿用上述完整 IntradayOHLC，但 volume_unit=null，所有 candles[].volume=null；指數價格單位為點數。no_data 時仍保留 null volume_unit。缺 Authorization 或非法 interval 回 422（無 realtime_quote 權限時先回 403 FEATURE_REQUIRED），401/403 沿指數報價契約。

首頁同張圖切換分時／10 秒／1 分／5 分／歷史日 K；各模式共用原指數串流，日 K 模式停用 history。分時固定今日交易時段，以開盤值作紅綠基準；休市仍可讀最新保留交易日的 K。日資料日期由常駐日 K 查詢回報，不隨模式或即時日期改變；MA、官方成交值和廣度維持自己的日期。

GET /api/portfolio/performance：期間日期

所有既有單檔／批次／彙總／分組模式新增可選 query reference_date: YYYY-MM-DD，預設 null；Bearer、原 ticker/type/tickers 互斥及批次上限保持不變。未提供時使用原 as_of_date。未來台北日期回 422 {error:{code:"reference_date cannot be in the future.",message:"reference_date cannot be in the future.",details:{}}}。

所有績效 response 及各分組新增 period_reference_date: YYYY-MM-DD|null；沒有日價格資料時為 null。as_of_date 仍表示官方日價格日期。reference_date 只調整期間開始和原 lot 成本基準，不改目前日收盤／市值、費用或會計資料。

盤中前端以有效持股日價日期與接受的 quote 交易日的共同最大值查期間基準，避免基準早於已使用的日價格。只有 response 的 period_reference_date 與共同基準匹配時才加入即時市值差額；逐檔也要求 as_of_date 等於該股原 market_price_date。尚未取得匹配基準時損益留 null。原 holding 的 market_price_date、批次報價事件及會計定義仍見 API reference。

本文件不新增後端 trading-calendar API；Web 使用自己的 TWSE local route。PR 發布不代表 SIT 已部署這些新增端點。