股價顧問 Stock Advisor — 使用手冊

一個涵蓋 台股 / 美股 / 港股 的個股查詢與投資參考網站。提供即時股價、漲跌、走勢圖與程式化「顧問觀點」，並開放 REST API 供 iOS App 與其他 webspace 取用。

一、功能概覽

二、網站進入方式

三、API 列表

所有端點以 https://www.herelai.fun/ws/stock-advisor 為基礎路徑（以下省略前綴）。回傳皆為 application/json，market 取值 TW / HK / US。

方法路徑說明參數
GET/api/health服務健康檢查—
GET/api/markets三市場開收市狀態與交易時段—
GET/api/universe標的清單（熱門＋家族基金持倉）market（可選）
GET/api/search?q=依代碼／名稱搜尋（含即時探測）q、market（可選）
GET/api/quote/:market/:symbol個股即時報價路徑參數
GET/api/quote/multi?items=批次報價items=TW:2330,HK:00700,US:AAPL
GET/api/history/:market/:symbol歷史收盤價（走勢圖用）days（10–250，預設 90）
GET/api/advisor/:market/:symbol顧問觀點（啟發式指標）路徑參數

範例回傳 — GET /api/quote/TW/2330

{
  "market": "TW", "symbol": "2330", "name": "台積電", "currency": "TWD",
  "price": 2475.0, "prevClose": 2500.0, "open": 2480.0,
  "high": 2490.0, "low": 2470.0, "volume": 12990,
  "change": -25.0, "changePct": -1.0,
  "updatedAt": "2026-09-25T05:30:00.000Z", "source": "mis", "marketOpen": false
}

範例回傳 — GET /api/advisor/HK/00700

{
  "available": true,
  "signals": [
    {"label": "短期趨勢", "value": "短線高於月線（20 日均），偏多"},
    {"label": "區間位置", "value": "居中震盪（中段，約 50% 分位）"},
    {"label": "年化波動", "value": "中等（約 28.4%）"},
    {"label": "年化報酬（估）", "value": "+12.3%"}
  ],
  "ma20": 432.1, "ma60": 420.5, "highest": 677.7, "lowest": 411.0,
  "rangePosition": 50.0, "annualizedVolatility": 28.4,
  "annualizedReturn": 12.3, "return7d": 1.8, "windowDays": 120,
  "valueSpectrum": {
    "score": 58, "leftPct": 42, "rightPct": 58,
    "leftLabel": "投機", "rightLabel": "價值投資", "label": "偏價值",
    "factors": [
      {"label":"穩定性","value":"中等波動（28.4%），得分 62"},
      {"label":"安全邊際","value":"50% 分位，居中，得分 50"},
      {"label":"品質趨勢","value":"站穩月線、年均報酬正，得分 80"}
    ]
  },
  "horizons": {
    "short":  {"title":"短期 · 7 天","posture":"偏多","confidence":"中高","points":["站穩 20 日均線且近週動能為正，短線偏多","可沿月線逢回分批，但不宜滿倉"]},
    "medium": {"title":"中期 · 3 個月","posture":"逢低布局","confidence":"中高","points":["具備安全邊際且中期趨勢向上，符合價值投資節奏","以 3 個月視角分批建立部位，忽略短期雜訊"]},
    "long":   {"title":"長期 · 3 年以上","posture":"適合長期持有","confidence":"高","points":["符合巴菲特「以合理價買好公司、長期持有」原則","波動低、具安全邊際，適合做時間的朋友、享受複利"]}
  },
  "disclaimer": "本網站資訊與「顧問觀點」皆由程式依公開歷史資料計算，僅供參考，不構成任何投資建議；巴菲特原則僅作為選股邏輯示範，非個股買賣指示。",
  "quote": { "market":"HK", "symbol":"00700", "name":"騰訊控股", "price":436.6 }
}

核心投顧建議欄位說明：

三之一、帳號與自選股 API（需登入）

自選股綁定帳號：先註冊／登入取得 Bearer token，後續受保護請求於標頭帶 Authorization: Bearer <token>。所有端點皆啟用 CORS（Access-Control-Allow-Origin: *），可供 iOS App 與其他網站呼叫。

方法路徑說明參數
POST/api/auth/register註冊並登入（回傳 token＋account）body: username(3-30, 限英數 _ . -), password(≥6), email?, displayName?（email 已改為選填）
POST/api/auth/login登入取得 tokenbody: identifier(用戶名或 email), password
POST/api/auth/logout登出（註銷目前登入會話）需 token
GET/api/auth/me取得目前帳號資訊需 token
DELETE/api/auth/me註銷帳號（刪除帳號＋其自選＋所有會話）需 token
GET/api/watchlist取得我的自選（含每檔即時報價）需 token
POST/api/watchlist加入自選需 token；body: market, symbol, name?
DELETE/api/watchlist/:market/:symbol移除自選需 token；路徑參數
PATCH/api/auth/me修改顯示名稱 / 變更密碼需 token；body: displayName?、currentPassword?、newPassword?(≥6)
POST/api/auth/request-reset申請重設密碼（產生 reset token）body: email
POST/api/auth/reset-password以 reset token 重設密碼body: token、newPassword(≥6)
PATCH/api/watchlist/:market/:symbol修改自選股分組 / 備註 / 排序需 token；body: group?、note?、sortOrder?
GET/api/watchlist/export匯出自選股 JSON（下載）需 token
POST/api/watchlist/share產生唯讀分享連結需 token
GET/api/share/:token公開唯讀自選股（不需登入）路徑參數

未帶有效 token 呼叫受保護端點會回傳 401 {"error":"unauthorized"}；登入連續失敗 5 次會被鎖定 15 分鐘並回傳 429 {"error":"locked"}（防暴力破解）。重設密碼：若伺服器未配置 SMTP，reset token 會寫入伺服器日誌（管理員可查），或以啟動參數 ALLOW_RESET_RETURN=1 直接回傳。

三之二、管理帳號與管理後台 API（需 admin）

系統內建一個投顧專家管理帳號，用於使用者管理、檢視用戶自選股與登入紀錄：

管理端點皆需在標頭帶管理員的 Bearer token，且該帳號 role='admin'，否則回傳 403 {"error":"forbidden"}：

方法路徑說明參數
GET/api/admin/stats總覽：總用戶、管理員數、自選總數、線上 Session、今日登入需 admin
GET/api/admin/users用戶列表（含各自選數）需 admin；?q= 可搜尋用戶名/email/名稱
GET/api/admin/users/:id單一用戶詳情：基本資料＋自選股（含即時報價）＋登入紀錄需 admin
GET/api/admin/login-logs全站登入紀錄（成功/失敗、IP、UA）需 admin；?limit= 預設 100
DELETE/api/admin/users/:id刪除用戶（含其自選+會話+登入紀錄；不可刪自己或其他管理員）需 admin

所有登入／註冊行為都會寫入 login_logs（含 IP 與 User-Agent），供管理員稽核。

Client 範例：

// 登入取得 token（identifier 可為用戶名或 email）
const r = await fetch(BASE+'/api/auth/login', {method:'POST',
  headers:{'Content-Type':'application/json'},
  body: JSON.stringify({identifier: username, password})});
const {token, account} = await r.json();
// 加入自選（帶 token）
await fetch(BASE+'/api/watchlist', {method:'POST',
  headers:{'Content-Type':'application/json','Authorization':'Bearer '+token},
  body: JSON.stringify({market:'TW', symbol:'2330', name:'台積電'})});

四、iOS App 呼叫範例（Swift）

import Foundation

struct Quote: Decodable {
    let market, symbol, name, currency: String
    let price: Double
    let change, changePct: Double
}

func fetchQuote(market: String, symbol: String) async throws -> Quote {
    let base = "https://www.herelai.fun/ws/stock-advisor"
    let url = URL(string: "\(base)/api/quote/\(market)/\(symbol)")!
    let (data, _) = try await URLSession.shared.data(from: url)
    return try JSONDecoder().decode(Quote.self, from: data)
}

// 使用：
// let q = try await fetchQuote(market: "TW", symbol: "2330")
// print(q.name, q.price, q.changePct)

五、其他 webspace 嵌入範例（JavaScript）

// 於任意網頁中顯示台積電即時價（API 已開啟 CORS）
fetch('https://www.herelai.fun/ws/stock-advisor/api/quote/TW/2330')
  .then(r => r.json())
  .then(q => {
    document.getElementById('tsmc').textContent =
      `${q.name} ${q.price} (${q.changePct}%)`;
  });

六、注意事項