大盤 index-range 端點 Integration Guide — Frontend

Backend branch: feat/daily-market-index-range → cortex/dev（issue #1645） API base: 公開端點（與 /api/daily-market/range 同）生效時間：merge 後 cortex-api 重啟即生效，無 migration

後續新增：daily[].bias_rate_ma120_pct / bias_rate_ma240_pct（半年線／年線乖離率）見 daily-market-ma120-ma240-frontend.md。

Consumer：cortex-web 首頁「大盤健康儀表板 › Index K-Line」（src/components/dashboard/index-kline-panel.tsx）。該面板目前以 useDailyMarketRange({startDate, endDate}) 打 GET /api/daily-market/range 只為了拿 market_trade_value_amount（成交金額柱），卻要等 /range 算完上市融資維持率的全市場擔保品聚合（冷路徑 2.4–14 s，且 cache key 每個交易日必換）。本次新增只回大盤欄位的端點供首頁改打。

1. 欄位改名對照表（Breaking）

無。/range 的欄位、值、cache key 一律未動（其擔保品 SQL 改為 LATERAL，只是變快）。

2. 新端點（additive）

GET /api/daily-market/index-range?start_date=YYYY-MM-DD&end_date=YYYY-MM-DD&market=taiwan

Query 參數與 /range 完全相同（省略 start_date = end_date − 30、省略 end_date = 今天、start > end → 422）。

Response：

{
  "market": "taiwan",
  "start_date": "2025-11-20",
  "end_date": "2026-09-17",
  "count": 200,
  "daily": [
    {
      "trade_date": "2026-09-17",
      "market_index_close": 46288.0,
      "market_trade_value_amount": 850394000000,
      "bias_rate_ma5_pct": 0.76,
      "bias_rate_ma20_pct": 0.28,
      "bias_rate_ma60_pct": 2.5
    }
  ]
}

欄位	型別	與 `/range` 的關係
`daily[].trade_date`	`string`	同
`daily[].market_index_close`	`number \\| null`	同名同值（允許 `derived_available`）
`daily[].market_trade_value_amount`	`number \\| null`	同名同值（僅 `available`）
`daily[].bias_rate_ma5_pct` / `ma20` / `ma60`	`number \\| null`	同名同值

日期集合 ⊆ /range：index-range 只以 market_daily_metrics 為日期驅動（/range 另聯集 market_chip_metrics）。共同日期上五欄逐欄相等；/range 多出的日期其大盤欄位本來就是 null，首頁不受影響。

3. 前端改法（cortex-web）

src/lib/api/endpoints.ts：新增 DAILY_MARKET_INDEX_RANGE: "/api/daily-market/index-range"。
src/lib/api/services/daily-market.ts：新增 getIndexRange({startDate, endDate, market})（與 getRange 同參數）。
src/types/daily-market.ts：新增 DailyMarketIndexRangeResponse（daily[] 只有上表 6 個 key）。
src/lib/api/hooks/use-daily-market.ts：新增 useDailyMarketIndexRange（queryKey ["daily-market", "index-range", start, end, market]，staleTime 沿用 MARKET_RANGE_STALE_TIME_MS）。
src/components/dashboard/index-kline-panel.tsx：useDailyMarketRange → useDailyMarketIndexRange；讀取的欄位 daily[].market_trade_value_amount 名稱不變，其餘邏輯零改動。
/market 頁（src/app/market/page.tsx）不改：它同時用兩群欄位，繼續打 /range。

4. 驗證

本機：curl -w '%{time_total}\n' 'http://localhost:8000/api/daily-market/index-range?start_date=2025-11-20&end_date=2026-09-17' 冷路徑 < 0.5 s。
首頁 network log：/api/daily-market/index-range 取代 /api/daily-market/range；K 線成交金額柱數值與改前一致。