finance-dashboard/lib/indicators.js

// ═══════════════════════════════════════════════════════════
//  指標設定 — 全站唯一的「資料字典」
//  每個指標都在這裡定義：要抓哪條 FRED 序列、怎麼換算、
//  中文名、是否為「反向指標」（數字越高越糟），以及給初學者
//  看的三段式解釋（這是什麼 / 怎麼看 / 對市場影響）。
//
//  欄位說明：
//   - group        所屬分組（對應下方 GROUPS）
//   - label        中文主標題
//   - labelEn      英文副標（保留對照）
//   - source       'fred' 或 'stooq'
//   - seriesId     FRED 序列代碼（source=fred 時）
//   - symbol       Stooq 代碼（source=stooq 時）
//   - transform    換算方式（見 lib/fred.js 的 computeMetric）
//   - periodsPerYear  做 YoY 時，一年有幾期（月=12、季=4、週=52）
//   - format       顯示格式（見 lib/fred.js 的 formatValue）
//   - decimals     小數位數
//   - inverted     true = 反向指標（數字越高代表越糟，例如失業率、VIX）
//   - excludeFromScore  true = 不納入總體健康分數（中性或方向不明確者）
//   - substitute   若為免費替代指標，放原本想要的名稱（會在畫面標示）
//   - tip          三段式解釋 + 資料來源與更新頻率
// ═══════════════════════════════════════════════════════════

// 分組（依「故事線」排序：利率 → 通膨 → 就業 → 成長 → 貨幣信用 → 市場反應）
export const GROUPS = [
  {
    key: 'rates',
    title: '利率 & 殖利率',
    titleEn: 'Interest Rates & Yield Curve',
    icon: '$',
    colorKey: 'blue',
    intro: '一切的起點。央行（聯準會）的利率決定了整個經濟「借錢的成本」。利率高，企業與家庭就少借錢、少消費，經濟降溫；利率低則相反。先看這裡，後面的通膨、就業、市場都是它的連鎖反應。',
  },
  {
    key: 'inflation',
    title: '通膨指標',
    titleEn: 'Inflation Indicators',
    icon: '\uD83D\uDCC8',
    colorKey: 'yellow',
    intro: '聯準會升降息，最主要就是為了「控制物價」。這裡看物價漲多快——數字越接近 2%（聯準會目標）越健康；太高代表生活變貴、可能還要再升息，太低（甚至負的）則代表經濟可能太冷。',
  },
  {
    key: 'labor',
    title: '勞動市場',
    titleEn: 'Labor Market',
    icon: '\uD83D\uDCBC',
    colorKey: 'green',
    intro: '有沒有工作、薪水漲不漲，直接影響大家敢不敢消費。就業強勁通常是好事，但「太強」會推升薪資與物價，讓聯準會更難降息。觀察就業是否從高峰開始降溫，是判斷景氣轉折的關鍵。',
  },
  {
    key: 'growth',
    title: '景氣成長',
    titleEn: 'Economic Growth',
    icon: '\uD83D\uDCC9',
    colorKey: 'purple',
    intro: '把前面的利率、通膨、就業加總起來，整體經濟到底在擴張還是收縮？這組是「成績單」，也包含幾個能提早預警衰退的領先指標。',
  },
  {
    key: 'money',
    title: '貨幣 & 信用',
    titleEn: 'Money Supply & Credit',
    icon: '\uD83C\uDFE6',
    colorKey: 'orange',
    intro: '市場上的錢多不多、好不好借？資金寬鬆時資產容易上漲，資金緊縮（信用利差擴大）往往是市場壓力的早期訊號。這組看的是金融體系的「血液循環」。',
  },
  {
    key: 'sentiment',
    title: '市場情緒 & 大宗商品',
    titleEn: 'Markets & Commodities',
    icon: '\uD83D\uDCCA',
    colorKey: 'red',
    intro: '最後是市場的即時反應。股市、波動率、美元與大宗商品價格，反映投資人此刻是貪婪還是恐懼，也是前面所有總經訊號的「綜合投票結果」。',
  },
];

export const INDICATORS = [
  // ───────────── 利率 & 殖利率 ─────────────
  {
    key: 'fed_funds', group: 'rates',
    label: '聯邦基金利率', labelEn: 'Fed Funds Rate (upper)',
    source: 'fred', seriesId: 'DFEDTARU',
    transform: 'level', format: 'pct', decimals: 2, inverted: false, excludeFromScore: true,
    tip: {
      what: '聯準會（Fed）設定的政策利率目標區間上緣，是所有市場利率的源頭。',
      how: '升息代表央行想替過熱經濟與通膨降溫；降息代表想刺激經濟。本身無絕對好壞。',
      impact: '利率走向幾乎左右所有資產價格，是看總經的第一個錨點。',
      source: 'FRED · DFEDTARU', freq: '隨 FOMC 會議調整',
    },
  },
  {
    key: 'treasury_10y', group: 'rates',
    label: '10 年期公債殖利率', labelEn: '10Y Treasury Yield',
    source: 'fred', seriesId: 'DGS10',
    transform: 'level', format: 'pct', decimals: 2, inverted: false, excludeFromScore: true,
    tip: {
      what: '美國 10 年期公債的市場殖利率，是全球長期利率的基準。',
      how: '反映市場對長期成長與通膨的預期；上升代表資金成本變高。',
      impact: '房貸、企業借貸、股票評價都以它為定價基準。',
      source: 'FRED · DGS10', freq: '每日',
    },
  },
  {
    key: 'treasury_2y', group: 'rates',
    label: '2 年期公債殖利率', labelEn: '2Y Treasury Yield',
    source: 'fred', seriesId: 'DGS2',
    transform: 'level', format: 'pct', decimals: 2, inverted: false, excludeFromScore: true,
    tip: {
      what: '美國 2 年期公債殖利率，對「短期升降息預期」最敏感。',
      how: '通常貼近市場對未來一兩年聯準會利率的看法。',
      impact: '與 10 年期相比可看出殖利率曲線是否倒掛（見下方）。',
      source: 'FRED · DGS2', freq: '每日',
    },
  },
  {
    key: 'yield_spread', group: 'rates',
    label: '10年-2年利差', labelEn: '10Y-2Y Spread',
    source: 'fred', seriesId: 'T10Y2Y',
    transform: 'percent_to_bp', format: 'bp', decimals: 0, inverted: true,
    tip: {
      what: '長天期（10年）減短天期（2年）殖利率的差距，單位是基點（bp）。',
      how: '正常為正值；一旦變負（倒掛）代表短率高於長率，歷史上常是衰退前兆。',
      impact: '反向指標：數字越低/負越值得警惕，這是最受關注的衰退訊號之一。',
      source: 'FRED · T10Y2Y', freq: '每日',
    },
  },
  {
    key: 'real_rate', group: 'rates',
    label: '10年期實質利率', labelEn: 'Real Rate (10Y TIPS)',
    source: 'fred', seriesId: 'DFII10',
    transform: 'level', format: 'pct', decimals: 2, inverted: false, excludeFromScore: true,
    tip: {
      what: '扣掉通膨預期後的「真實」10年利率（以抗通膨債 TIPS 衡量）。',
      how: '實質利率越高，持有黃金、成長股等不孳息資產的機會成本越高。',
      impact: '是黃金與高估值科技股的重要逆風/順風指標。',
      source: 'FRED · DFII10', freq: '每日',
    },
  },
  {
    key: 'sofr', group: 'rates',
    label: '擔保隔夜融資利率', labelEn: 'SOFR',
    source: 'fred', seriesId: 'SOFR',
    transform: 'level', format: 'pct', decimals: 2, inverted: false, excludeFromScore: true,
    tip: {
      what: '美國銀行間隔夜借錢的基準利率，已取代舊的 Libor。',
      how: '通常緊貼聯邦基金利率；若突然跳動，代表短期資金市場有壓力。',
      impact: '大量浮動利率貸款與衍生性商品都以它計價。',
      source: 'FRED · SOFR', freq: '每日',
    },
  },

  // ───────────── 通膨 ─────────────
  {
    key: 'cpi', group: 'inflation',
    label: '消費者物價指數 (年增)', labelEn: 'CPI YoY',
    source: 'fred', seriesId: 'CPIAUCSL',
    transform: 'yoy', periodsPerYear: 12, format: 'pct', decimals: 2, inverted: true,
    tip: {
      what: '一籃子日常商品與服務的價格，與一年前相比漲了多少（年增率）。',
      how: '聯準會目標約 2%。越高代表生活越貴、可能還要升息。',
      impact: '反向指標：太高是警訊；數字下降（降溫）通常對股債友善。',
      source: 'FRED · CPIAUCSL', freq: '每月',
    },
  },
  {
    key: 'core_cpi', group: 'inflation',
    label: '核心 CPI (年增)', labelEn: 'Core CPI YoY',
    source: 'fred', seriesId: 'CPILFESL',
    transform: 'yoy', periodsPerYear: 12, format: 'pct', decimals: 2, inverted: true,
    tip: {
      what: 'CPI 扣掉波動劇烈的食品與能源，更能看出物價的「底層趨勢」。',
      how: '比整體 CPI 更黏、降得更慢，是聯準會緊盯的數字。',
      impact: '反向指標：核心通膨遲遲不降，降息就會延後。',
      source: 'FRED · CPILFESL', freq: '每月',
    },
  },
  {
    key: 'ppi', group: 'inflation',
    label: '生產者物價指數 (年增)', labelEn: 'PPI YoY',
    source: 'fred', seriesId: 'PPIFIS',
    transform: 'yoy', periodsPerYear: 12, format: 'pct', decimals: 2, inverted: true,
    tip: {
      what: '生產端（工廠出廠）的物價年增率，常領先消費者端的 CPI。',
      how: '生產成本上升，之後往往會轉嫁到消費者價格。',
      impact: '反向指標：可當成 CPI 的「上游預警」。',
      source: 'FRED · PPIFIS', freq: '每月',
    },
  },
  {
    key: 'pce', group: 'inflation',
    label: '核心 PCE (年增)', labelEn: 'Core PCE YoY',
    source: 'fred', seriesId: 'PCEPILFE',
    transform: 'yoy', periodsPerYear: 12, format: 'pct', decimals: 2, inverted: true,
    tip: {
      what: '聯準會「最偏好」的通膨指標——核心個人消費支出物價。',
      how: '聯準會的 2% 目標其實是看這個數字，重要性高於 CPI。',
      impact: '反向指標：這個數字往 2% 靠近，是降息的關鍵前提。',
      source: 'FRED · PCEPILFE', freq: '每月',
    },
  },
  {
    key: 'breakeven', group: 'inflation',
    label: '5年通膨預期', labelEn: '5Y Breakeven Inflation',
    source: 'fred', seriesId: 'T5YIE',
    transform: 'level', format: 'pct', decimals: 2, inverted: true,
    tip: {
      what: '市場（債券交易者）預期未來 5 年的平均通膨率。',
      how: '反映「市場相不相信通膨會被控制住」；脫錨上升是大麻煩。',
      impact: '反向指標：穩定在 2% 附近代表預期良好；飆高代表信心動搖。',
      source: 'FRED · T5YIE', freq: '每日',
    },
  },

  // ───────────── 勞動市場 ─────────────
  {
    key: 'unemployment', group: 'labor',
    label: '失業率', labelEn: 'Unemployment Rate',
    source: 'fred', seriesId: 'UNRATE',
    transform: 'level', format: 'pct', decimals: 2, inverted: true,
    tip: {
      what: '想工作但找不到工作的人口比例。',
      how: '低代表就業市場熱絡；但若從低點開始快速上升，常是衰退啟動的訊號。',
      impact: '反向指標：上升是警訊（可參考 Sahm 法則：升幅過快即衰退）。',
      source: 'FRED · UNRATE', freq: '每月',
    },
  },
  {
    key: 'nfp', group: 'labor',
    label: '非農就業 (月增)', labelEn: 'Nonfarm Payrolls (MoM)',
    source: 'fred', seriesId: 'PAYEMS',
    transform: 'payems_diff', format: 'k_signed', decimals: 0, inverted: false,
    tip: {
      what: '排除農業後，當月新增的工作數（千人）。最受市場關注的就業數據。',
      how: '正數且穩健代表經濟在創造就業；急速放緩代表動能轉弱。',
      impact: '每月公布時常引發股債大幅波動。',
      source: 'FRED · PAYEMS（取月變動）', freq: '每月',
    },
  },
  {
    key: 'claims', group: 'labor',
    label: '初領失業金人數', labelEn: 'Initial Jobless Claims',
    source: 'fred', seriesId: 'ICSA',
    transform: 'level_per_thousand', format: 'k', decimals: 0, inverted: true,
    tip: {
      what: '每週第一次申請失業救濟的人數（千人），是最即時的就業溫度計。',
      how: '低且平穩代表裁員少；持續攀升代表勞動市場開始惡化。',
      impact: '反向指標：因為每週公布，比月報更早反映轉折。',
      source: 'FRED · ICSA', freq: '每週',
    },
  },
  {
    key: 'wages', group: 'labor',
    label: '平均時薪 (年增)', labelEn: 'Avg Hourly Earnings YoY',
    source: 'fred', seriesId: 'CES0500000003',
    transform: 'yoy', periodsPerYear: 12, format: 'pct', decimals: 2, inverted: false, excludeFromScore: true,
    tip: {
      what: '民間部門平均時薪與一年前相比的漲幅。',
      how: '對勞工是好事，但漲太快會推升物價（薪資-通膨螺旋），讓聯準會緊張。',
      impact: '方向解讀較中性：需搭配通膨一起看，故不計入總分。',
      source: 'FRED · CES0500000003', freq: '每月',
    },
  },

  // ───────────── 景氣成長 ─────────────
  {
    key: 'gdp', group: 'growth',
    label: '實質 GDP (年增)', labelEn: 'Real GDP YoY',
    source: 'fred', seriesId: 'GDPC1',
    transform: 'yoy', periodsPerYear: 4, format: 'pct', decimals: 2, inverted: false,
    tip: {
      what: '經通膨調整後的經濟總產出，與一年前相比的成長率。',
      how: '正成長代表經濟擴張；連兩季萎縮常被視為技術性衰退。',
      impact: '是經濟整體健康最根本的「成績單」。',
      source: 'FRED · GDPC1（取年增）', freq: '每季',
    },
  },
  {
    key: 'mfg', group: 'growth',
    label: '製造業景氣', labelEn: 'Mfg Activity (Philly Fed)',
    source: 'fred', seriesId: 'GACDFSA066MSFRBPHI',
    transform: 'level', format: 'num1', decimals: 1, inverted: false,
    substitute: 'ISM 製造業 PMI',
    tip: {
      what: '費城聯儲製造業景氣調查（擴散指數），用來替代需付費的 ISM 製造業 PMI。',
      how: '大於 0 代表製造業在擴張，小於 0 代表收縮。',
      impact: '替代指標：製造業常領先整體景氣，是循環的風向球。',
      source: 'FRED · GACDFSA066MSFRBPHI', freq: '每月',
    },
  },
  {
    key: 'indpro', group: 'growth',
    label: '工業生產 (年增)', labelEn: 'Industrial Production YoY',
    source: 'fred', seriesId: 'INDPRO',
    transform: 'yoy', periodsPerYear: 12, format: 'pct', decimals: 2, inverted: false,
    tip: {
      what: '工廠、礦業與公用事業的實際產出，與一年前相比。',
      how: '正成長代表實體生產活絡；轉負代表工業部門走弱。',
      impact: '與製造業景氣互相印證實體經濟的力道。',
      source: 'FRED · INDPRO（取年增）', freq: '每月',
    },
  },
  {
    key: 'sentiment_consumer', group: 'growth',
    label: '消費者信心', labelEn: 'Consumer Sentiment (UMich)',
    source: 'fred', seriesId: 'UMCSENT',
    transform: 'level', format: 'num1', decimals: 1, inverted: false,
    substitute: '世界大型企業聯合會 CCI',
    tip: {
      what: '密西根大學消費者信心指數，用來替代需付費的世界大型企業聯合會 CCI。',
      how: '數字越高代表民眾對經濟與荷包越有信心，越敢消費。',
      impact: '替代指標：消費占美國經濟約七成，信心是重要前瞻訊號。',
      source: 'FRED · UMCSENT', freq: '每月',
    },
  },
  {
    key: 'retail', group: 'growth',
    label: '零售銷售 (月增)', labelEn: 'Retail Sales (MoM)',
    source: 'fred', seriesId: 'RSAFS',
    transform: 'mom', format: 'pct_signed', decimals: 1, inverted: false,
    tip: {
      what: '零售與餐飲銷售額與上月相比的變化，直接反映消費力道。',
      how: '正成長代表民眾持續花錢；轉負代表消費降溫。',
      impact: '消費是經濟主引擎，這是它的即時脈搏。',
      source: 'FRED · RSAFS（取月增）', freq: '每月',
    },
  },
  {
    key: 'recession_prob', group: 'growth',
    label: '衰退機率 (殖利率模型)', labelEn: 'Recession Probability',
    source: 'fred', seriesId: 'RECPROUSM156N',
    transform: 'level', format: 'pct', decimals: 1, inverted: true,
    substitute: '領先指標 LEI',
    tip: {
      what: '紐約聯儲依殖利率曲線推估「未來 12 個月內衰退」的機率，替代需付費的 LEI 領先指標。',
      how: '數字越高代表模型認為衰退風險越大；超過 30% 通常值得警戒。',
      impact: '反向指標（替代）：是純數據、無情緒的前瞻衰退訊號。',
      source: 'FRED · RECPROUSM156N', freq: '每月',
    },
  },

  // ───────────── 貨幣 & 信用 ─────────────
  {
    key: 'm2', group: 'money',
    label: 'M2 貨幣供給 (年增)', labelEn: 'M2 Money Supply YoY',
    source: 'fred', seriesId: 'M2SL',
    transform: 'yoy', periodsPerYear: 12, format: 'pct', decimals: 2, inverted: false,
    tip: {
      what: '市場上流通的廣義貨幣（現金+存款）與一年前相比的變化。',
      how: '正成長代表流動性增加；負成長（罕見）代表錢在收縮。',
      impact: '流動性是資產價格的潤滑劑，過去與股市關聯密切。',
      source: 'FRED · M2SL（取年增）', freq: '每月',
    },
  },
  {
    key: 'credit_spread', group: 'money',
    label: '高收益債信用利差', labelEn: 'High-Yield OAS',
    source: 'fred', seriesId: 'BAMLH0A0HYM2',
    transform: 'percent_to_bp', format: 'bp', decimals: 0, inverted: true,
    tip: {
      what: '高收益（垃圾）債相對公債的額外利率補償，單位基點（bp）。',
      how: '利差小代表市場願意承擔風險；急速擴大代表恐慌、信用收緊。',
      impact: '反向指標：擴大是金融壓力的早期且靈敏的訊號。',
      source: 'FRED · BAMLH0A0HYM2', freq: '每日',
    },
  },
  {
    key: 'fin_cond', group: 'money',
    label: '金融條件指數', labelEn: 'Financial Conditions (NFCI)',
    source: 'fred', seriesId: 'NFCI',
    transform: 'level', format: 'num2_signed', decimals: 2, inverted: true,
    tip: {
      what: '芝加哥聯儲綜合衡量整體金融鬆緊的指數（NFCI）。',
      how: '注意：正值代表比平均「更緊」，負值代表「更寬鬆」（與直覺相反）。',
      impact: '反向指標：數字上升代表金融環境收緊，對風險資產不利。',
      source: 'FRED · NFCI', freq: '每週',
    },
  },
  {
    key: 'fed_balance', group: 'money',
    label: '聯準會資產負債表', labelEn: 'Fed Balance Sheet',
    source: 'fred', seriesId: 'WALCL',
    transform: 'millions_to_trillions', format: 'trillions', decimals: 2, inverted: false, excludeFromScore: true,
    tip: {
      what: '聯準會持有的資產總額（兆美元）。擴張=QE 印鈔，收縮=QT 縮表。',
      how: '上升代表向市場注入流動性，下降代表抽走流動性。',
      impact: '是判斷央行「鬆或緊」的直接量化證據，方向中性故不計分。',
      source: 'FRED · WALCL', freq: '每週',
    },
  },

  // ───────────── 市場情緒 & 大宗商品 ─────────────
  {
    key: 'vix', group: 'sentiment',
    label: 'VIX 恐慌指數', labelEn: 'VIX',
    source: 'fred', seriesId: 'VIXCLS',
    transform: 'level', format: 'num1', decimals: 1, inverted: true,
    tip: {
      what: '市場對未來 30 天股市波動的預期，俗稱「恐慌指數」。',
      how: '一般低於 20 代表平靜；飆高（>30）代表市場恐慌。',
      impact: '反向指標：低=自滿、高=恐慌，常與股市反向。',
      source: 'FRED · VIXCLS', freq: '每日',
    },
  },
  {
    key: 'dxy', group: 'sentiment',
    label: '美元指數 (廣義)', labelEn: 'Broad USD Index',
    source: 'fred', seriesId: 'DTWEXBGS',
    transform: 'level', format: 'num1', decimals: 1, inverted: false, excludeFromScore: true,
    tip: {
      what: '美元對一籃子貿易夥伴貨幣的強弱（聯準會廣義美元指數）。',
      how: '走強通常代表避險或美國相對強勁；走弱有利新興市場與大宗商品。',
      impact: '方向中性：影響跨資產但無絕對好壞，故不計分。',
      source: 'FRED · DTWEXBGS', freq: '每日',
    },
  },
  {
    key: 'oil', group: 'sentiment',
    label: '西德州原油 (WTI)', labelEn: 'WTI Crude Oil',
    source: 'fred', seriesId: 'DCOILWTICO',
    transform: 'level', format: 'usd', decimals: 1, inverted: false, excludeFromScore: true,
    tip: {
      what: '西德州中質原油價格（美元/桶）。',
      how: '反映能源需求與地緣風險；油價飆漲會推升通膨。',
      impact: '方向中性：是成長與通膨的雙面刃，故不計分。',
      source: 'FRED · DCOILWTICO', freq: '每日',
    },
  },
  {
    key: 'gold', group: 'sentiment',
    label: '黃金', labelEn: 'Gold Futures (GC=F)',
    source: 'yahoo', symbol: 'GC=F',
    transform: 'level', format: 'usd0', decimals: 0, inverted: false, excludeFromScore: true,
    tip: {
      what: '黃金期貨價格（美元/盎司），經典的避險與抗通膨資產。',
      how: '在恐慌、低實質利率或美元走弱時通常上漲。',
      impact: '方向中性：作為避險溫度計參考，故不計分。',
      source: 'Yahoo Finance · GC=F', freq: '每日',
    },
  },
  {
    key: 'copper', group: 'sentiment',
    label: '銅價', labelEn: 'Copper (USD/tonne)',
    source: 'fred', seriesId: 'PCOPPUSDM',
    transform: 'level', format: 'usd0', decimals: 0, inverted: false, excludeFromScore: true,
    tip: {
      what: '全球銅價（美元/公噸）。因廣泛用於工業，被稱為「銅博士」。',
      how: '上漲常代表全球製造與建設需求強，是景氣的風向球。',
      impact: '方向中性：作為成長動能參考，故不計分。',
      source: 'FRED · PCOPPUSDM', freq: '每月',
    },
  },
  {
    key: 'sp500', group: 'sentiment',
    label: 'S&P 500 指數', labelEn: 'S&P 500',
    source: 'fred', seriesId: 'SP500',
    transform: 'level', format: 'num0', decimals: 0, inverted: false, excludeFromScore: true,
    tip: {
      what: '美國 500 大企業股價指數，最具代表性的股市基準。',
      how: '上漲反映市場樂觀；它是所有總經訊號的「綜合投票結果」。',
      impact: '方向中性（本身即市場）：故不計入總經健康分數。',
      source: 'FRED · SP500', freq: '每日',
    },
  },
];

// 方便用 key 取得設定
export const INDICATOR_MAP = Object.fromEntries(INDICATORS.map((i) => [i.key, i]));