finance-dashboard/lib/glossary.js

// 白話名詞解釋 — 供 ? 浮動卡片使用（國高中生也看得懂）
function _esc(s) {
  return String(s == null ? '' : s)
    .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
    .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
}

const TERM_TIPS = {
  market_cap: {
    label: '市值',
    what: '把這家公司所有股票加起來，現在市場願意付多少錢。就像整間店「全部股份」的標價。',
    how: '市值大通常代表公司規模大、影響力大，但不代表一定貴或一定好賺。',
  },
  ev: {
    label: '企業價值 EV',
    what: '如果要「整間買下來」，大概要花多少。算法是：市值 ＋ 欠的債 － 手邊現金。',
    how: '比只看市值更公平，因為有些公司欠很多債、有些現金很多，真正價值會不一樣。',
  },
  pe: {
    label: '市盈率 P/E',
    what: '你願意用「公司一年淨利」的幾倍價格來買。P/E＝20 代表：公司一年賺 1 元，你願意花 20 元買。',
    how: '數字高＝大家期待它未來賺更多；數字低＝比較便宜或大家不看好。要搭配成長速度一起看。',
    example: '一年淨利 5 元、股價 100 元 → P/E＝20 倍。',
  },
  shares: {
    label: '流通股數',
    what: '可以在市場上自由買賣的股票總張數（或總股數）。',
    how: '股數越多，同樣的獲利要分給更多人，每股賺到的錢可能較少。',
  },
  dividend_yield: {
    label: '股息殖利率',
    what: '如果公司發現金股息，依現在股價算，一年能領回多少％。',
    how: '像定存利率的概念，但股價會漲會跌，股息也可能增減，不是保證收入。',
    example: '股價 100、一年股息 3 → 殖利率 3%。',
  },
  rev_growth: {
    label: '營收成長',
    what: '公司賣東西／提供服務的收入，跟去年同期比，增加了多少％。',
    how: '成長快通常代表生意在擴張；但如果賺不到錢，營收高也不等於好投資。',
  },
  ma: {
    label: '均線 MA',
    what: '把最近 N 天的收盤價平均起來，畫成一條線。MA20＝最近 20 天平均僡。',
    how: '股價在均線上方，通常代表短中期偏強；在下方則偏弱。常用來看趨勢方向。',
  },
  rsi: {
    label: 'RSI',
    what: '最近漲跌力道強不強的指標，0～100 分。算的是「漲的日子 vs 跌的日子」誰比較猛。',
    how: '超過 70 常說「偏熱」、低於 30 常說「偏冷」。只是參考，不是買賣鐵律。',
  },
  macd: {
    label: 'MACD',
    what: '用兩條不同速度的均線相減，看動能是在變強還是變弱。',
    how: '柱狀圖由負轉正，常被解讀為動能轉多；由正轉負則偏空。適合搭配趨勢一起看。',
  },
  boll: {
    label: '布林通道',
    what: '在均線上下各畫一條「正常波動範圍」的界線，像橡皮筋包著股價。',
    how: '貼近上緣可能偏貴、貼近下緣可能偏便宜，但強勢股可以一直沿上緣走。',
  },
  pos52: {
    label: '52 週位置',
    what: '現在股價，落在過去一年最高價和最低價之間的哪個位置（0％＝最低、100％＝最高）。',
    how: '接近 100％ 代表在一年高檔，追價要小心；接近 0％ 可能便宜，但要確認為什麼跌。',
  },
  volume_ratio: {
    label: '成交量 / 均量',
    what: '今天成交的股數，是平常平均的幾倍。',
    how: '放量（比平常多很多）常代表大家特別關心，可能是好消息或壞消息在發酵。',
  },
  debt_assets: {
    label: '負債 / 總資產',
    what: '公司欠的錢，占全部家當的幾％。',
    how: '比例越高，景氣不好或利率升時，還債壓力越大。',
  },
  debt_equity: {
    label: '負債股本比',
    what: '公司欠多少錢，跟股東投入的錢比，是幾倍。',
    how: '大於 1 代表債比股東權益還多，槓桿較高，風險要留意。',
  },
  current_ratio: {
    label: '流動比率',
    what: '一年內能變現的資產，夠不夠還一年內要還的債。公式：流動資產 ÷ 流動負債。',
    how: '大於 1 代表短期還債能力 OK；太低可能有資金週轉問題。',
  },
  cash_debt: {
    label: '現金 / 債務',
    what: '手邊現金，跟總負債比，是幾倍。',
    how: '大於 1 代表現金就夠還債，財務較有緩衝；太低則景氣差時較危險。',
  },
  volatility: {
    label: '年化波動',
    what: '股價每天上上下下的幅度，換算成「一年大概會晃多兇」。',
    how: '數字越大，心臟要越大顆；部位要小一點或分批進出。',
  },
  max_drawdown: {
    label: '最大回撤',
    what: '從過去某個高點跌到最低點，最多跌了多少％。',
    how: '幫你想像「最慘曾經虧多少」。回撤大代表坐雲霄飛車，要評估自己受不受得了。',
  },
  gross_margin: {
    label: '毛利率',
    what: '賣 100 元東西，扣掉直接成本後，還剩多少。越高代表產品越「有價錢」。',
    how: '科技、品牌公司通常較高；原物料、零售可能較低。',
  },
  op_margin: {
    label: '營業利潤率',
    what: '本業賺錢效率：營業利益 ÷ 營收。扣掉管銷等日常開銷後，本業還剩多少％。',
    how: '比毛利率更能反映公司「真正會做生意」的程度。',
  },
  net_margin: {
    label: '淨利率',
    what: '最後真正落袋的利潤，占營收幾％（扣完稅、利息等所有費用）。',
    how: '這才是股東最終能分到的獲利比例。',
  },
  roa: {
    label: 'ROA 資產報酬率',
    what: '公司用全部資產（不管誰的錢），一年幫你賺了幾％的淨利。',
    how: '看「整盤生意」用資產賺錢的效率，適合比較同產業公司。',
  },
  roe: {
    label: 'ROE 股東權益報酬率',
    what: '股東投入的錢，一年幫你賺了幾％的淨利。',
    how: '長期 ROE 高且穩，常代表是好公司；但太高可能是借很多債撐出來的，要搭配負債一起看。',
  },
  fcf_margin: {
    label: 'FCF Margin',
    what: '自由現金流占營收的％。自由現金流＝營運賺到的現金，扣掉維修、擴廠等必要支出後，真正自由運用的錢。',
    how: '比「帳上淨利」更難造假，長期為正且成長，通常是健康訊號。',
  },
  target_price: {
    label: '1 年目標價',
    what: '券商分析師預測，這檔股票一年後「合理價位」大概在哪。',
    how: '只是預測，常偏樂觀；當參考就好，不要當成一定會到的價格。',
  },
  dcf: {
    label: 'DCF 公允價值',
    what: '把公司未來可能賺到的現金，一筆一筆折現加總，估算「現在值多少錢」。',
    how: '假設（成長率、折現率）一改，結果差很多；適合看區間，不適合當精準股價。',
  },
  margin_of_safety: {
    label: '安全邊際',
    what: '估算的合理價值，比現在股價高多少％。代表「便宜緩衝」有多大。',
    how: '正值代表現價低於估算值；負值代表可能偏貴。留安全邊際是為了估錯還有退路。',
  },
  dcf_assumption: {
    label: '估值假設',
    what: 'DCF 裡你猜的：未來幾年成長多快、折現率（要求報酬）多少、長期成長率多少。',
    how: '假設越樂觀，算出來的價值越高；看這行是在提醒「這只是模型，不是真理」。',
  },
  cagr: {
    label: 'CAGR 年化報酬',
    what: '如果每年穩穩複利，要多少％才會從起點賺到終點。把整段報酬平均成「每年幾％」。',
    how: '回測策略時常用來比「這方法長期平均一年賺多少」。',
  },
  sma_strategy: {
    label: '均線趨勢策略',
    what: '短均線在上、長均線在下就持有；反過來就空手。用來跟著大趨勢走。',
    how: '震盪盤容易來回被洗；趨勢明顯時較有用。',
  },
  dip_strategy: {
    label: '回落買進',
    what: '從近期高點跌達一定幅度（例如 15％）才買，不追在高點。',
    how: '可能買在半山腰；適合願意分批、有耐心等回檔的人。',
  },
  dca_strategy: {
    label: '分批投入（定期定額）',
    what: '不管高低，固定時間、固定金額買進，不猜最低點。',
    how: '降低「一次買在最高點」的風險，但牛市可能平均成本偏高。',
  },
  fomc: {
    label: 'FOMC',
    what: '美國聯準會開會決定「要不要調利率、調多少」。全球資金成本都跟著動。',
    how: '升息通常打壓估值高的成長股；降息則常有利風險資產。公布當天波動常很大。',
  },
  dot_plot: {
    label: '點陣圖',
    what: 'Fed 官員各自預測「未來利率會在哪」的圖，一個點代表一位官員的預期。',
    how: '市場會看「中位數」和上次比有沒有變高，來猜還會不會升息。',
  },
  cpi: {
    label: 'CPI 通膨',
    what: '一籃子日常用品（食衣住行）跟去年比，平均貴了多少％。就是大家說的「通膨率」。',
    how: 'CPI 比預期高 → 市場怕 Fed 繼續升息；比預期低 → 可能降息期待升溫。',
  },
  nfp: {
    label: '非農就業',
    what: '美國非農業新增多少工作、失業率多少。看勞動市場健不健康。',
    how: '就業太強＋通膨高，Fed 可能不敢降息；就業轉弱則可能刺激降息預期。',
  },
  pce: {
    label: 'PCE',
    what: 'Fed 最在意的通膨指標之一，看個人花了多少錢、物價漲多少。比 CPI 範圍更廣一點。',
    how: 'Fed 的 2％ 通膨目標常看 PCE；公布時市場反應可能很大。',
  },
  gdp: {
    label: 'GDP',
    what: '一個國家一段時間內，所有商品和服務的總價值。看經濟是在成長還是衰退。',
    how: 'GDP 成長放緩或負成長，通常代表景氣轉弱，企業獲利可能受壓。',
  },
  earnings: {
    label: '財報',
    what: '上市公司每季公布的成績單：賺多少、花多少、展望如何。',
    how: '數字或展望不如預期，股價常大跌；超預期則可能大漲。公布前後波動大。',
  },
  eps: {
    label: 'EPS',
    what: '每股賺多少錢。把公司淨利除以流通股數，看「每一股」分到多少利潤。',
    how: '財報常比「EPS 有沒有 beat 預期」；beat＝比分析師猜的還好。',
  },
  ppi: {
    label: 'PPI',
    what: '工廠、批發端賣出去的東西，價格跟去年比漲多少。可當 CPI 的領先指標。',
    how: 'PPI 先漲，有時之後 CPI 也會跟著漲。',
  },
  jolts: {
    label: 'JOLTS 職缺',
    what: '美國有多少職缺、多少人自願離職。看勞動市場是緊還是鬆。',
    how: '職缺多、離職率高，常代表工人議價力強，可能推升薪資和通膨。',
  },
  quadruple_witching: {
    label: '四巫日',
    what: '每年 3、6、9、12 月「第三個週五」，期指、指數選擇權、個股選擇權等多種衍生品同一天到期結算。',
    how: '到期日前後常見換倉、成交量放大、股價晃動加劇；大型權值股有時波動更明顯。',
  },
  monthly_opex: {
    label: '月選擇權結算',
    what: '每個月第三個週五，大量股票與指數選擇權到期，投資人常在此前後調整部位。',
    how: '非四巫日的月份仍有結算壓力，但通常比四巫日溫和一些。',
  },
  adp_employment: {
    label: 'ADP 私部門就業',
    what: '民間機構統計的「私企新增工作」人數，比官方非農早幾天公布。',
    how: '常被當成非農就業的預演；方向一致時市場較安心，差很多則會重新定價。',
  },
  jobless_claims: {
    label: '初領失業救濟金',
    what: '每週有多少人第一次申請失業救濟。看裁員是否在升溫。',
    how: '每週都有，突然大增代表勞動市場轉弱，可能推升降息預期。',
  },
  retail_sales: {
    label: '零售銷售',
    what: '美國商店、餐廳賣了多少東西，看老百姓有沒有在花钱。',
    how: '數字強代表內需好；弱則擔心經濟放緩，也可能影響 Fed 政策預期。',
  },
  industrial_production: {
    label: '工業生產',
    what: '工廠、礦場、電力等產出量，反映實體經濟是否在擴張。',
    how: '下滑常代表製造業轉弱，對原物料、工業股情緒偏空。',
  },
  michigan_sentiment: {
    label: '密西根消費者信心',
    what: '問一般家庭對景氣、通膨、購屋的看法，是「信心」指標。',
    how: '信心下滑時，市場常擔心消費會縮，對零售、可選消費類股偏空。',
  },
  housing_data: {
    label: '房市數據',
    what: '新屋開工、營建許可、成屋銷售等，看住宅市場活不活躍。',
    how: '房市對利率很敏感；數據轉弱常代表高利率正在壓抑需求。',
  },
  durable_goods: {
    label: '耐久財訂單',
    what: '能用好幾年的大件商品（機器、飛機、電腦等）訂單，看企業投資意願。',
    how: '訂單增代表企業願意擴產；大減則暗示景氣與資本支出轉冷。',
  },
  consumer_credit: {
    label: '消費信貸',
    what: '信用卡、汽車貸款等借款餘額，看家庭是否靠借錢消費。',
    how: '借貸快速增加有時代表需求強，但也可能暗示財務壓力上升。',
  },
  eci: {
    label: '就業成本指數 ECI',
    what: '企業付給員工的薪資與福利漲多少，Fed 用它看「薪資通膨」。',
    how: '薪資漲太快，Fed 可能更不敢降息；降溫則有利降息預期。',
  },
  productivity: {
    label: '生產力 / 單位成本',
    what: '工人產出效率與每單位產出成本，看通膨是來自薪資還是效率。',
    how: '生產力高、成本可控，對企業獲利與通膨都是好消息。',
  },
  philly_fed: {
    label: '費城 Fed 製造業調查',
    what: '美國東部製造業經理人的景氣問卷，類似 PMI 的先行指標。',
    how: '高於 0 代表擴張、低於 0 代表收縮；公布時短線波動常見。',
  },
  services_pmi: {
    label: '非製造業景氣調查',
    what: '服務業（占美國 GDP 大部分）的景氣問卷，看活動是在擴張還是收縮。',
    how: '服務業強，通常代表整體經濟仍有支撐；轉弱則偏空。',
  },
  trade_balance: {
    label: '國際貿易',
    what: '美國出口、進口與貿易逆差數字，看對外需求與美元流向。',
    how: '逆差擴大不一定壞，但會影響 GDP 與匯率討論；公布時市場會快速反應。',
  },
  import_export_prices: {
    label: '進出口物價',
    what: '進口與出口商品的價格變化，可當通膨的領先或補充線索。',
    how: '進口物價漲，有時預告國內通膨壓力將來會升高。',
  },
  real_earnings: {
    label: '實質薪資',
    what: '把通膨扣掉之後，工人薪水實際能買到多少東西。',
    how: '實質薪資在漲，消費較有支撐；若通膨吃掉加薪，則消費可能轉弱。',
  },
  market_holiday: {
    label: '美股休市',
    what: '紐約證交所休市或提早收盤，當天（或前後）成交量通常較低。',
    how: '休市日前後常見部位調整；重要數據若撞上休市，反應可能延後到 reopen。',
  },
  jackson_hole: {
    label: 'Jackson Hole 央行年會',
    what: '全球央行官員與經濟學者的大會，Fed 主席常發表重要政策談話。',
    how: '講話若偏鷹（抗通膨），股市常承壓；偏鴿（願降息）則風險資產較受益。',
  },
  ecb_rate: {
    label: '歐洲央行利率決議',
    what: '歐元區的「央行開會決定要不要調利率」，影響歐股、歐元、全球資金。',
    how: '升息打壓估值、降息通常有利風險資產；記者會語氣也會被放大解讀。',
  },
  boj_rate: {
    label: '日本央行利率決議',
    what: '日本央行的貨幣政策決議，決定是否調整利率或購債。',
    how: '日圓、日股、套息交易都會動；若傳出升息或收緊，全球市場常波動。',
  },
  boe_rate: {
    label: '英央行 MPC 決議',
    what: '英格蘭銀行貨幣政策委員會決定英國利率，影響英鎊與英股。',
    how: '與 Fed、ECB 類似：偏鷹偏空風險資產，偏鴿則相反。',
  },
  section_market: {
    label: '市場總覽',
    what: '這一區看「這檔股票現在市場怎麼定價」：股價、大小、貴不貴、成長快不快。',
    how: '先建立第一印象，再往下挖財報和技術面。',
  },
  section_technical: {
    label: '技術面',
    what: '用股價和成交量的圖表、指標，看短中期趨勢和熱度。',
    how: '不能預測公司長期價值，但可幫你決定「現在進場會不會太追」。',
  },
  section_risk: {
    label: '風險',
    what: '公司財務健不健康、股價晃多兇。看「最壞情況可能多慘」。',
    how: '風險高不代表不能買，但要控制部位、知道自己在賭什麼。',
  },
  section_return: {
    label: '回報',
    what: '不同時間長度，買這檔股票賺或虧了多少％。',
    how: '看長期（1～5 年）比只看最近一個月更能反映趨勢。',
  },
  section_efficiency: {
    label: '效率',
    what: '公司賺錢的「品質」：毛利高不高、用資產和股東的錢賺錢效率高不高。',
    how: '好公司通常毛利率、ROE 長期都不錯，且自由現金流跟得上。',
  },
  section_forecast: {
    label: '預測',
    what: '分析師目標價、DCF 估算等「向前看」的數字，都是模型和猜測。',
    how: '當參考區間，不要當成精準預言。',
  },
  section_robust: {
    label: '穩健度',
    what: '把前面各項整理成紅綠燈和簡短結論，方便快速掃描。',
    how: '紅燈多就要更保守；綠燈多也要記得沒有百分之百。',
  },
};

function termTipBtn(key, label) {
  if (!TERM_TIPS[key]) return '';
  const aria = label || TERM_TIPS[key].label || key;
  return `<button type="button" class="info-btn" data-term-key="${_esc(key)}" aria-label="說明：${_esc(aria)}" tabindex="0">?</button>`;
}

function termTipHTML(t) {
  let html = `<div class="tip-title">${_esc(t.label)}</div>`;
  html += `<div class="tip-row"><span class="tip-k">白話說</span>${_esc(t.what)}</div>`;
  if (t.how) html += `<div class="tip-row"><span class="tip-k">怎麼看</span>${_esc(t.how)}</div>`;
  if (t.example) html += `<div class="tip-row"><span class="tip-k">舉例</span>${_esc(t.example)}</div>`;
  return html;
}

function termTipContent(key) {
  const t = TERM_TIPS[key];
  return t ? termTipHTML(t) : '';
}

function showTermTip(btn) {
  const el = document.getElementById('tooltip');
  if (!el) return;
  const html = termTipContent(btn.dataset.termKey);
  if (!html) return;
  el.innerHTML = html;
  el.classList.add('show');
  const r = btn.getBoundingClientRect();
  const tw = el.offsetWidth, th = el.offsetHeight;
  let left = r.left + r.width / 2 - tw / 2;
  left = Math.max(10, Math.min(left, window.innerWidth - tw - 10));
  let top = r.top - th - 10;
  if (top < 10) top = r.bottom + 10;
  el.style.left = left + 'px';
  el.style.top = top + 'px';
}

function hideTermTip() {
  const el = document.getElementById('tooltip');
  if (el) el.classList.remove('show');
}

function bindTermTips(root) {
  root = root || document;
  root.querySelectorAll('.info-btn[data-term-key]').forEach(btn => {
    if (btn.dataset.termBound) return;
    btn.dataset.termBound = '1';
    btn.addEventListener('mouseenter', () => showTermTip(btn));
    btn.addEventListener('mouseleave', hideTermTip);
    btn.addEventListener('focus', () => showTermTip(btn));
    btn.addEventListener('blur', hideTermTip);
    btn.addEventListener('click', e => {
      e.preventDefault();
      e.stopPropagation();
      const el = document.getElementById('tooltip');
      el && el.classList.contains('show') ? hideTermTip() : showTermTip(btn);
    });
  });
}

function glossInline(text) {
  const terms = [
    ['FOMC', 'fomc'], ['點陣圖', 'dot_plot'], ['CPI', 'cpi'], ['非農', 'nfp'],
    ['PCE', 'pce'], ['GDP', 'gdp'], ['財報', 'earnings'], ['四巫', 'quadruple_witching'],
  ];
  let out = _esc(text);
  for (const [word, key] of terms) {
    if (!TERM_TIPS[key]) continue;
    const re = new RegExp(_esc(word).replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
    out = out.replace(re, `${_esc(word)}${termTipBtn(key, word)}`);
  }
  return out;
}

function eventTipKey(title, note) {
  const t = `${title || ''} ${note || ''}`;
  if (/點陣|SEP|dot plot/i.test(t)) return 'dot_plot';
  if (/ADP/i.test(t)) return 'adp_employment';
  if (/初領失業|jobless claims/i.test(t)) return 'jobless_claims';
  if (/密西根|surveys of consumers/i.test(t)) return 'michigan_sentiment';
  if (/零售銷售|retail sales/i.test(t)) return 'retail_sales';
  if (/工業生產|industrial production/i.test(t)) return 'industrial_production';
  if (/新屋開工|成屋|營建許可|housing starts/i.test(t)) return 'housing_data';
  if (/耐久財|manufacturer.*shipments/i.test(t)) return 'durable_goods';
  if (/消費信貸|consumer credit/i.test(t)) return 'consumer_credit';
  if (/就業成本|\beci\b/i.test(t)) return 'eci';
  if (/生產力|productivity and costs/i.test(t)) return 'productivity';
  if (/費城 Fed|製造業指數|manufacturing business outlook/i.test(t)) return 'philly_fed';
  if (/非製造業|nonmanufacturing business outlook/i.test(t)) return 'services_pmi';
  if (/國際貿易|international trade/i.test(t)) return 'trade_balance';
  if (/進出口物價|import and export price/i.test(t)) return 'import_export_prices';
  if (/實質薪資|real earnings/i.test(t)) return 'real_earnings';
  if (/Jackson Hole/i.test(t)) return 'jackson_hole';
  if (/歐洲央行|\bECB\b/i.test(t)) return 'ecb_rate';
  if (/日本央行|\bBOJ\b/i.test(t)) return 'boj_rate';
  if (/英央行|MPC/i.test(t)) return 'boe_rate';
  if (/四巫|衍生品結算/i.test(t)) return 'quadruple_witching';
  if (/月選擇權結算/i.test(t)) return 'monthly_opex';
  if (/美股休市/i.test(t)) return 'market_holiday';
  if (/FOMC|聯準會.*利率/i.test(t)) return 'fomc';
  if (/CPI|消費者物價/i.test(t)) return 'cpi';
  if (/非農|employment situation/i.test(t)) return 'nfp';
  if (/PCE|個人收入/i.test(t)) return 'pce';
  if (/GDP|國內生產/i.test(t)) return 'gdp';
  if (/PPI|生產者物價/i.test(t)) return 'ppi';
  if (/JOLTS|職缺/i.test(t)) return 'jolts';
  if (/財報/i.test(t)) return 'earnings';
  if (/EPS/i.test(t)) return 'eps';
  return null;
}