Skip to content

Repository files navigation

Taiwan Stock Advisor

台股智能投資顧問 — 多代理人換股決策系統

目標年化報酬 15%17 個專家 Agent 協同分析整合台股完整稅費與健保補充保費

Python FastAPI React TypeScript PostgreSQL Redis Docker License: MIT


目錄


專案概述

Taiwan Stock Advisor 是一個聚焦於「換股決策」的台股智能投資顧問系統。系統會分析使用者目前的持股,告訴你「該賣哪些、改買哪些」,目標年化報酬 15%

為什麼做這個專案?

市面上多數選股工具只回答「現在買什麼」,卻忽略了散戶最關鍵的問題:「我手上這幾支該不該換?」。換股決策同時牽涉:

  • 量化評分(多維度、多週期)
  • 法規成本(手續費、證交稅、健保補充保費)
  • 行為心理(停損點、加減碼節奏)
  • 總體環境(Fed 利率、川普政策、地緣政治)

本系統用 17 個專業代理人(agent) 各司其職、整合輸出單一可執行的換股建議,並附上完整成本試算與換股後投組模擬。

核心設計哲學

哲學 落實方式
可執行優於理論最佳 所有建議都附「賣多少、買多少、何時、成本多少」
理由 ≥ 3 條才賣 評分 < 40 才觸發賣出,且必附 3 條量化理由
台股稅費內建 證交稅 / 健保補充保費 / 零股 / 除權息全考量
多代理人協同 17 個 agent 分工,避免單一模型過擬合
失敗安全 任何資料源失效都有 fallback,永遠給得出建議

核心特色

換股決策引擎(系統核心)

  • 整合評分公式:技術面 25% + 基本面 30% + AI 信心 20% + 量化 15% + 法人籌碼 10%
  • 動態權重調整:依市場環境(多頭 / 盤整 / 空頭)自動調整各維度權重
  • 賣出觸發條件:整合評分 < 40 自動建議賣出,附 3 條量化理由
  • 換股後投組模擬:預估年化報酬、波動度、夏普比率、最大回撤
  • 集中度警示:單一個股 > 25%、單一產業 > 40% 觸發警示

完整成本試算

換股總成本 = 賣出手續費(0.06%) + 證交稅(股票 0.3% / ETF 0.1%)
           + 買入手續費(0.06%)
           + 健保補充保費(單次股利 > 2 萬時 2.11%)
           + 損益兩平天數估算

多元資料源整合

  • TWSE OpenAPI:上市股票、三大法人、融資融券(免費,官方)
  • TPEX OpenAPI:上櫃股票(免費,官方)
  • FinMind:歷史股價、財報、籌碼(部分免費 + 付費)
  • 永豐 Shioaji:使用者持股自動同步、即時行情
  • Yahoo Finance(yfinance):ETF 備援資料源
  • 可降級設計:免費版 FinMind 時自動將技術面權重從 25% 拉到 70%

機器學習預測

  • LSTM:5 / 10 / 20 日股價預測
  • XGBoost + LightGBM Ensemble:技術指標特徵融合
  • SHAP 解釋性:列出影響預測最大的 top-5 特徵
  • 回測驗證:MAPE、方向準確率、Sharpe ratio

風險管理

  • VaR / CVaR:95% / 99% 信心水準
  • GARCH 波動度預測
  • 效率前緣(PyPortfolioOpt):MPT 投組最佳化
  • 下行風險與最大回撤估算

資安強化

  • 金鑰隔離:永豐 API Key 僅存 sessionStorage,不寫入後端 DB
  • 錯誤訊息脫敏:分類化錯誤訊息,不洩漏 person_id / IP
  • 路徑穿越防護.pfx 憑證路徑強制白名單
  • JWT 認證:所有 /api/* 端點需登入
  • CORS 嚴格限制:僅允許設定的來源

系統架構

┌─────────────────────────────────────────────────────────────────┐
│                          前端(Frontend)                        │
│  React 18 + TypeScript + Vite + Ant Design + Zustand            │
│  ┌─────────┬──────────┬──────────┬────────┬─────────┬────────┐  │
│  │ 儀表板   │ 換股建議  │ 每日建議  │ 選股   │ 觀察名單 │ 持股管理 │  │
│  └─────────┴──────────┴──────────┴────────┴─────────┴────────┘  │
└──────────────────────────────┬──────────────────────────────────┘
                               │ HTTPS / JWT
                               ▼
┌─────────────────────────────────────────────────────────────────┐
│                         API Gateway (FastAPI)                    │
│   /api/v1/portfolio  /rebalance  /screener  /watchlist  /stock  │
│   /market  /daily-picks  /portfolio/sync (Sinopac)              │
└──────────────────────────────┬──────────────────────────────────┘
                               │
            ┌──────────────────┼──────────────────┐
            ▼                  ▼                  ▼
   ┌─────────────────┐ ┌──────────────┐ ┌──────────────────┐
   │  Service Layer  │ │  ML Pipeline │ │ Celery Workers   │
   │ ┌─────────────┐ │ │ ┌──────────┐ │ │ ┌──────────────┐ │
   │ │ Portfolio   │ │ │ │ LSTM     │ │ │ │ ETL Tasks    │ │
   │ │ Rebalance   │ │ │ │ Ensemble │ │ │ │ Daily Sync   │ │
   │ │ Screener    │ │ │ │ Features │ │ │ │ News Monitor │ │
   │ │ Daily Picks │ │ │ │ SHAP     │ │ │ │ Score Recalc │ │
   │ │ Sinopac     │ │ │ └──────────┘ │ │ └──────────────┘ │
   │ └─────────────┘ │ └──────────────┘ └──────────────────┘
   └────────┬────────┘
            │
            ▼
   ┌────────────────────────────────────────────────────────────┐
   │                       Data Layer                            │
   │ ┌────────────┐  ┌──────────┐  ┌─────────────────────────┐  │
   │ │ PostgreSQL │  │  Redis   │  │ External APIs            │  │
   │ │  16 (主存) │  │  7 (快取)│  │ TWSE / TPEX / FinMind    │  │
   │ │            │  │  Celery  │  │ Yahoo Finance / Sinopac  │  │
   │ └────────────┘  └──────────┘  └─────────────────────────┘  │
   └────────────────────────────────────────────────────────────┘

換股決策資料流

使用者持股
    ▼
[1] 多源價格擷取(TWSE / FinMind / yfinance fallback)
    ▼
[2] 技術指標計算(RSI, MACD, KD, MA20/60, BollingerBand)
    ▼
[3] 基本面分析(PE, PB, ROE, 殖利率, 營收 YoY)
    ▼
[4] AI 預測(LSTM 5/10/20 日 + Ensemble + SHAP)
    ▼
[5] 量化指標(動量、波動、夏普)
    ▼
[6] 法人籌碼(外資 / 投信 / 自營買賣超)
    ▼
[7] 整合評分(依市場環境動態權重)
    ▼
[8] 評分 < 40 → 賣出建議(含 ≥ 3 條量化理由)
    ▼
[9] 從候選池找替換標的(排除現有持股 + 重複產業)
    ▼
[10] 完整成本試算(手續費 + 證交稅 + 健保補充保費)
    ▼
[11] 換股後投組模擬(年化報酬、波動、夏普、Beta)
    ▼
[12] 輸出 RebalanceResponse(賣出清單 + 買入清單 + 模擬結果)

技術棧

Backend

類別 套件 說明
Web Framework FastAPI 0.115 Async-first、自動產生 OpenAPI 文件
ORM SQLAlchemy 2.0 (async) 含 Alembic migration
資料庫 PostgreSQL 16 持久層
快取 / 訊息佇列 Redis 7 API 快取 + Celery broker
任務排程 Celery 5.4 + RedBeat 排程 ETL、每日重算
機器學習 scikit-learn / XGBoost / LightGBM / SHAP 集成模型 + 解釋性
投組最佳化 PyPortfolioOpt 效率前緣 / Black-Litterman
風險指標 statsmodels / arch GARCH 波動度模型
台股資料 yfinance / shioaji Yahoo + 永豐證券
認證 python-jose / passlib[bcrypt] JWT + 密碼雜湊
日誌 loguru 結構化日誌
測試 pytest / pytest-asyncio / factory-boy 含 async 測試

Frontend

類別 套件 說明
Framework React 18.3 含 Suspense + 懶載入
Build Tool Vite 5.3 極速 HMR
Language TypeScript 5.5 (strict) 完整型別定義
UI Library Ant Design 5.20 含 zh-TW locale
狀態管理 Zustand 4.5 輕量 store
資料抓取 TanStack Query 5.62 Server state + cache
圖表 Recharts 2.12 響應式 SVG 圖表
路由 React Router 6.26
HTTP Axios 1.7 攔截器集中處理錯誤
測試 Vitest + Testing Library

DevOps

類別 工具
容器化 Docker + Docker Compose
CI/CD GitHub Actions(規劃中)
監控 Flower(Celery)、loguru、PostgreSQL pg_stat_statements

專案結構

taiwan-stock-advisor/
├── README.md
├── docker-compose.yml              # 5 個服務一鍵啟動
├── .env.example                    # 環境變數範本
│
├── backend/
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── alembic/                    # DB migrations
│   └── app/
│       ├── main.py                 # FastAPI 入口(lifespan + CORS + middleware)
│       ├── config.py               # pydantic-settings
│       ├── database.py             # SQLAlchemy async engine
│       ├── celery_app.py           # Celery + RedBeat 排程
│       │
│       ├── models/                 # SQLAlchemy ORM
│       │   ├── user.py
│       │   ├── portfolio.py
│       │   ├── stock.py
│       │   ├── watchlist.py
│       │   └── analysis.py
│       │
│       ├── schemas/                # Pydantic v2 Schemas
│       │   ├── portfolio.py
│       │   └── rebalance.py
│       │
│       ├── api/                    # FastAPI Routers
│       │   ├── portfolio.py        # 持股 CRUD
│       │   ├── rebalance.py        # 換股建議(核心)
│       │   ├── screener.py         # 選股篩選
│       │   ├── watchlist.py        # 觀察名單
│       │   ├── stock.py            # 個股分析
│       │   ├── market.py           # 市場概況
│       │   ├── sync.py             # 永豐 Shioaji 同步
│       │   └── daily_picks.py      # 每日建議
│       │
│       ├── services/               # 業務邏輯
│       │   ├── portfolio_service.py
│       │   ├── rebalance_service.py     # 換股核心邏輯(800+ 行)
│       │   ├── screener_service.py
│       │   ├── real_analysis_service.py # 整合真實資料的評分
│       │   ├── daily_picks_service.py
│       │   ├── sinopac_service.py       # 永豐證券 API
│       │   └── stock_metadata_service.py
│       │
│       ├── data/                   # 外部資料源
│       │   ├── twse_client.py           # TWSE OpenAPI
│       │   ├── finmind_client.py        # FinMind API
│       │   ├── technical_indicators.py  # 技術指標自製實作
│       │   ├── fundamental_analyzer.py  # 基本面分析
│       │   └── news_monitor.py          # 新聞情緒監測
│       │
│       ├── ml/                     # 機器學習
│       │   ├── lstm_model.py            # LSTM 模型
│       │   ├── ensemble_predictor.py    # XGBoost + LightGBM
│       │   ├── feature_engineering.py
│       │   ├── model_evaluator.py
│       │   └── model_config.py
│       │
│       └── tasks/                  # Celery Tasks
│           └── etl_tasks.py
│
├── frontend/
│   ├── Dockerfile
│   ├── package.json
│   ├── vite.config.ts
│   ├── tsconfig.json
│   └── src/
│       ├── main.tsx
│       ├── App.tsx                 # 路由 + 佈局
│       ├── pages/
│       │   ├── DashboardPage.tsx
│       │   ├── RebalancePage.tsx       # 換股建議頁
│       │   ├── DailyPicksPage.tsx
│       │   ├── ScreenerPage.tsx
│       │   ├── WatchlistPage.tsx
│       │   └── PortfolioPage.tsx
│       ├── components/
│       │   ├── HoldingScoreCard.tsx
│       │   └── SwitchCostCalculator.tsx
│       ├── api/
│       │   ├── rebalance.ts
│       │   ├── dailyPicks.ts
│       │   └── sync.ts
│       ├── store/
│       │   └── portfolioStore.ts        # Zustand
│       └── types/
│
└── .claude/
    └── agents/                     # 17 個專家 Agent 規格
        ├── architect.md
        ├── backend.md
        ├── frontend.md
        ├── data-engineer.md
        ├── ml-engineer.md
        ├── quant-analyst.md
        ├── risk-manager.md
        ├── technical-analyst.md
        ├── fundamental-analyst.md
        ├── etf-specialist.md
        ├── stock-screener.md
        ├── rebalancing-engine.md   # 換股決策引擎(核心)
        ├── stock-advisor.md
        ├── news-observer.md        # 時事觀測員
        ├── security-engineer.md
        ├── tester.md
        └── devops.md

快速開始

前置需求

  • Docker Desktop 4.20+ 或 Docker Engine 24+
  • Node.js 20+(如果想跑非容器版本)
  • Python 3.12+(如果想跑非容器版本)
  • 8 GB RAM、10 GB 可用磁碟
  • (選用)FinMind API Token、OpenAI API Key、永豐 Shioaji 帳號

一鍵啟動(Docker Compose)

# 1. Clone repo
git clone https://github.com/D11225687/taiwan-stock-advisor.git
cd taiwan-stock-advisor

# 2. 複製環境變數範本並填入金鑰
cp .env.example .env
# 至少填入:APP_SECRET_KEY、JWT_SECRET、FINMIND_TOKEN(可選)

# 3. 啟動所有服務(PostgreSQL + Redis + Backend + Celery + Frontend)
docker-compose up -d

# 4. 等待 healthcheck 通過(約 30 秒)
docker-compose ps

# 5. 開啟瀏覽器
# Frontend: http://localhost:3000
# API Docs: http://localhost:8000/docs
# Flower (Celery 監控): http://localhost:5555

本機開發(非容器)

Backend

cd backend

# 建立虛擬環境
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

# 安裝相依套件
pip install -r requirements.txt

# 啟動 PostgreSQL 與 Redis(可用 Docker 只起這兩個)
docker-compose up -d postgres redis

# 執行 migration
alembic upgrade head

# 啟動 API
uvicorn app.main:app --reload --port 8000

# 另開 terminal 啟動 Celery
celery -A app.celery_app worker --loglevel=info -Q default,analysis,data_fetch
celery -A app.celery_app beat --loglevel=info --scheduler redbeat.RedBeatScheduler

Frontend

cd frontend
npm install
npm run dev
# 開啟 http://localhost:5173

使用方式

第一次使用(建議路徑)

Step 1:匯入持股

兩種方式:

  1. 手動建立:到 /portfolio 頁面 → 「新增持股」 → 輸入股票代號、股數、成本
  2. 永豐自動同步:到 /portfolio → 「同步永豐持股」 → 輸入 API Key + Secret + 身分證 + 電子憑證 PIN
    • 金鑰僅存於 sessionStorage,關閉分頁即清除
    • 後端不持久化任何金鑰

Step 2:產生第一份換股建議

/rebalance → 點「分析持股」按鈕:

  • 系統會跑完整 12 步資料流(見換股決策資料流
  • 看每支股票的整合評分(0-100 分):
    • < 40 → 系統建議賣出,看 3 條量化理由是否合理
    • 40-55 → 觀察名單,暫不動作但盯著
    • > 75 → 強力持有
  • 看「距 15% 目標還差多少」

Step 3:建立換股候選池

/screener

  • 選「存股模式」「成長模式」「波段模式」
  • 系統按整合評分排序,列出符合條件的 20-30 支
  • 把前 5-10 名加入觀察名單

Step 4:執行換股

確認系統建議 → 到券商 App 操作 → 回 /rebalance/history/{id}/execute 標記已執行

每週例行流程(建議 30 分鐘)

時間 動作 重點
週一盤前 10:00 看儀表板 + 時事燈號 確認本週是進攻還是防守
週三盤中 14:00 重新跑 /rebalance 看新的賣出建議與評分變動
週五收盤後 14:30 本週總結 + 三大法人動向 複盤 + 規劃下週

API 範例

完整 OpenAPI 文件:http://localhost:8000/docs

1. 分析持股並產生換股建議(POST /api/v1/rebalance/analyze

Request

curl -X POST "http://localhost:8000/api/v1/rebalance/analyze" \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_demo_001",
    "portfolio": [
      {"stock_id": "2330", "quantity": 1000, "cost_price": 850.0},
      {"stock_id": "2317", "quantity": 2000, "cost_price": 180.0},
      {"stock_id": "00878", "quantity": 5000, "cost_price": 20.0}
    ],
    "cash_available_twd": 200000,
    "target_annual_return_pct": 15.0,
    "market_env": "sideways",
    "max_candidates": 5
  }'

Response(節錄)

{
  "request_id": "abc123-...",
  "user_id": "user_demo_001",
  "analyzed_at": "2026-05-10T01:30:00Z",
  "market_env": "sideways",
  "holding_scores": [
    {
      "stock_id": "2330",
      "stock_name": "台積電",
      "composite_score": 82.5,
      "breakdown": {
        "technical": 78.0,
        "fundamental": 88.0,
        "ai_confidence": 80.0,
        "quantitative": 85.0,
        "institutional": 75.0
      },
      "action": "hold",
      "sell_reasons": [],
      "price_percentile_52w": 87.3
    },
    {
      "stock_id": "2317",
      "stock_name": "鴻海",
      "composite_score": 35.2,
      "action": "sell",
      "sell_reasons": [
        "RSI(14) = 78.5,技術面顯著超買",
        "近 60 日外資累計賣超 4.2 萬張",
        "EPS YoY -12.3%,基本面轉弱"
      ]
    }
  ],
  "switch_candidates": [
    {
      "stock_id": "2454",
      "stock_name": "聯發科",
      "composite_score": 79.8,
      "suggested_position_pct": 8.0,
      "entry_price": 1150.0,
      "stop_loss": 1058.0,
      "take_profit": 1380.0
    }
  ],
  "switch_cost": {
    "total_switch_cost": 1428.5,
    "cost_rate_pct": 0.42,
    "break_even_days": 12,
    "nhi_supplement_applicable": false
  },
  "portfolio_simulation": {
    "estimated_annual_return_pct": 14.8,
    "delta_to_target_pct": -0.2,
    "annual_volatility_pct": 18.6,
    "sharpe_ratio": 0.71,
    "concentration_warnings": []
  },
  "action_summary": "建議賣出 2317(評分 35.2),換入 2454(評分 79.8)...",
  "concentration_warning": null
}

2. 換股成本試算(GET /api/v1/rebalance/cost

curl "http://localhost:8000/api/v1/rebalance/cost?\
sell_amount=330000&buy_amount=345000&\
sell_is_etf=false&buy_is_etf=false&\
expected_excess_return_pct=5.0&dividend_income_twd=15000"
{
  "sell_amount": 330000,
  "buy_amount": 345000,
  "sell_brokerage_fee": 198.0,
  "sell_transaction_tax": 990.0,
  "buy_brokerage_fee": 207.0,
  "total_switch_cost": 1395.0,
  "cost_rate_pct": 0.42,
  "nhi_supplement_applicable": false,
  "break_even_days": 9
}

3. 選股篩選(POST /api/v1/screener/run

curl -X POST "http://localhost:8000/api/v1/screener/run" \
  -H "Content-Type: application/json" \
  -d '{
    "preset": "growth",
    "filters": {
      "min_market_cap_billion": 100,
      "min_roe_pct": 15,
      "max_pe": 25,
      "min_dividend_yield_pct": 2.0
    },
    "sort_by": "composite_score",
    "limit": 20
  }'

4. 永豐 Shioaji 同步持股(POST /api/portfolio/sync/sinopac

curl -X POST "http://localhost:8000/api/portfolio/sync/sinopac" \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "...",
    "secret_key": "...",
    "person_id": "A123456789",
    "ca_path": "/app/certs/Sinopac.pfx",
    "ca_password": "..."
  }'

後端會驗證 ca_path 必須以 /app/certs/ 開頭、不允許 ..、必須 .pfx 結尾,防範路徑穿越攻擊。


整合評分公式

基礎權重(資料完整時)

維度 權重 計算來源
技術面 25% RSI、MACD、KD、MA、Bollinger Band
基本面 30% PE、PB、ROE、殖利率、營收 YoY、EPS QoQ
AI 信心 20% LSTM 5/10/20 日預測 + Ensemble
量化 15% 動量、波動度、夏普比率
法人籌碼 10% 外資、投信、自營商買賣超

動態權重調整(依市場環境)

維度 多頭乘數 盤整乘數 空頭乘數
技術面 1.2× 1.0× 0.8×
基本面 0.9× 1.0× 1.3×
AI 信心 1.0× 1.0× 0.9×
量化 1.1× 1.0× 1.1×
法人籌碼 1.2× 1.0× 0.9×

多頭時技術 / 法人權重提升、基本面降低;空頭時相反,更看重財報穩健度。

免費版降級規則

當 FinMind 為免費版(無基本面 / 籌碼資料)時,系統自動將權重調整為:

技術面 70% + 基本面 15% + AI 5% + 量化 5% + 法人籌碼 5%

避免因為其他維度都是預設值 60,導致整合評分被「壓平」失去區分能力。

賣出觸發

if composite_score < 40 and len(sell_reasons) >= 3:
    action = SELL
elif 40 <= composite_score < 55:
    action = WATCH
else:
    action = HOLD

17 個專家 Agent

每個 Agent 都有獨立規格文件(.claude/agents/*.md),可被 Claude Code subagent 系統獨立呼叫。

# Agent 職責 對換股決策的貢獻
1 架構師 整體系統設計、模組拆分 決定 evaluator pipeline 的編排
2 後端工程師 API、業務邏輯 換股決策 API 的實作
3 前端工程師 UI、圖表 換股建議的視覺化呈現
4 資料工程師 ETL、資料管線 TWSE / FinMind 串接
5 DevOps 工程師 部署、排程、監控 每日重算 score 的排程
6 資安工程師 認證、加密、審查 永豐金鑰處理、JWT
7 AI/ML 工程師 LSTM、Ensemble AI 信心評分(20%)
8 量化分析師 投組最佳化、回報試算 量化評分(15%)
9 基本面分析師 財報、估值 基本面評分(30%,最大權重)
10 技術面分析師 指標、K 線、籌碼 技術面評分(25%)
11 風險管理師 VaR、壓力測試、停損 賣出觸發、停損價計算
12 ETF 專家 ETF 成分股、配息 ETF 候選評分
13 時事觀測員 川普政策、Fed、地緣政治 動態權重調整觸發
14 股市顧問 需求審視、實務判斷 投資邏輯合理性檢核
15 選股篩選引擎 全市場掃描 提供換入候選池
16 換股決策引擎 整合輸出最終建議 系統核心,整合所有 agent 結果
17 測試工程師 單元、整合、回測 模型準確度驗證

設計原則

  • 每個 Agent 都有明確的「輸入」「輸出」「失敗模式」
  • Agent 之間通過明確 schema 通訊(Pydantic)
  • 任一 Agent 失效都不會讓整個系統崩潰,會 fallback 到預設值並標記 data_quality: degraded

開發指南

Coding Style

Backend(Python)

  • Formatterruff format(line-length 100)
  • Linterruff check(含 pyflakes, pycodestyle, isort, bugbear
  • Type Checkmypy --strict
  • 命名:snake_case for functions/vars,PascalCase for classes
  • Async-first:所有 I/O 走 async,避免阻塞 event loop
  • Logging:用 loguru.logger,不要用 print

Frontend(TypeScript)

  • Formatter:Prettier(內建於 Vite)
  • Linter:ESLint(@typescript-eslint
  • TypeScriptstrict: true,禁用 any
  • Component:function component + hooks,避免 class
  • State:local state 用 useState,跨頁用 Zustand,server state 用 React Query

Git Workflow

# 主幹分支
main         # production-ready
develop      # integration

# 功能分支
feature/<topic>   # 新功能
fix/<topic>       # 修 bug
chore/<topic>     # 雜項
docs/<topic>      # 文件

Commit 訊息使用 Conventional Commits

feat(rebalance): add dynamic weight adjustment by market env
fix(sinopac): mask person_id in error messages
docs: update API examples in README
chore: bump fastapi to 0.115.6

新增一個 API 端點的步驟

  1. backend/app/schemas/<domain>.py 定義 Pydantic Request/Response
  2. backend/app/services/<domain>_service.py 寫業務邏輯
  3. backend/app/api/<domain>.py 寫 router
  4. backend/app/main.py 掛載 router
  5. frontend/src/api/<domain>.ts 寫 typed client
  6. frontend/src/pages/<Domain>Page.tsx 接 UI
  7. 寫測試(backend pytest + frontend vitest)

測試

Backend

cd backend

# 跑所有測試
pytest

# 跑特定模組
pytest tests/test_rebalance_service.py -v

# 覆蓋率報告
pytest --cov=app --cov-report=html
open htmlcov/index.html

Frontend

cd frontend

# 跑單元測試
npm test

# Watch 模式
npm run test:watch

# 覆蓋率
npm run test:coverage

ML 模型回測

cd backend
python -m app.ml.model_evaluator --start-date 2020-01-01 --end-date 2024-12-31
# 輸出:MAPE、方向準確率、Sharpe、最大回撤

Roadmap

v1.0(已完成)

  • 後端 API 17 個端點
  • 整合評分公式(5 維度動態權重)
  • 換股成本試算(含健保補充保費)
  • 永豐 Shioaji 持股同步
  • 前端 6 個頁面
  • LSTM + XGBoost + LightGBM 集成
  • 17 個 Agent 規格

v1.1(進行中)

  • WebSocket 即時價格推送
  • LINE Notify 換股建議推播
  • 回測平台(給定歷史持股,模擬若每月跑換股建議的累積績效)
  • PWA 支援(離線查看快取資料)

v2.0(規劃中)

  • 多帳戶支援(家人共享)
  • 美股 / 港股延伸
  • 自訂評分權重(給專業使用者)
  • AI Chat:用自然語言詢問「現在該不該賣台積電?」

免責聲明

本系統所有分析與建議僅供參考,不構成投資建議。

投資涉及風險,過去績效不代表未來結果。投資人應依自身財務狀況、風險承受能力與投資目標做出獨立判斷。本系統開發者對使用本系統造成的任何投資損失不承擔法律責任。

系統使用的資料來源(TWSE / TPEX / FinMind / Yahoo Finance / 永豐證券)的正確性與即時性由各原始來源負責,本系統不保證資料無誤。


License

MIT License — 詳見 LICENSE

投資相關免責聲明另見 DISCLAIMER.md


Credits

  • 開發者:Alex Lin
  • 開發工具:Claude Code 多代理人協作
  • 資料來源:TWSE OpenAPI、TPEX OpenAPI、FinMind、Yahoo Finance、永豐證券 Shioaji
  • UI 元件:Ant Design、Recharts
  • 圖表:Recharts、ECharts(規劃中)

若你覺得這個專案有趣,歡迎 ⭐ Star、Fork 或來信交流

Issues · Discussions

About

Taiwan Stock Advisor — 台股智能投資顧問系統|17-agent multi-collaborator architecture for stock rebalancing decisions targeting 15% annual return. FastAPI + React + PostgreSQL + Redis + ML (LSTM/XGBoost/LightGBM).

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages