股價顧問 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%）"}
  ],
  "ma20": 432.1, "highest": 677.7, "lowest": 411.0,
  "rangePosition": 50.0, "annualizedVolatility": 28.4, "windowDays": 120,
  "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: email, password(≥6), displayName?
POST/api/auth/login登入取得 tokenbody: 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；路徑參數

未帶有效 token 呼叫受保護端點會回傳 401 {"error":"unauthorized"}。Client 範例：

// 登入取得 token
const r = await fetch(BASE+'/api/auth/login', {method:'POST',
  headers:{'Content-Type':'application/json'},
  body: JSON.stringify({email, 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}%)`;
  });

六、注意事項