TPM/README.md

TPM – 投資組合大擂台

1) 內容概要

• Flask + PostgreSQL + Redis 的投資策略平台，內含回測、圖表與 LLM 投資建議。
• 前端採 Jinja SSR + Bootstrap；LLM 透過 llm_service.py 封裝，可切換 OpenAI/OpenRouter/Mock。

2) 技術棧（現況，請勿任意更換）

• Backend: Flask 2.2, psycopg2, Flask-Caching, Plotly
• DB/Cache: PostgreSQL, Redis
• Frontend: Jinja, Bootstrap 5, Bootstrap Icons（避免新增其他 CSS 框架）
• LLM: OpenAI SDK（可接 OpenRouter），支援 Mock
• Container: Docker, docker-compose

3) 目錄重點

• main.py: 路由與頁面組裝；禁止塞商業邏輯
• llm_service.py: LLM 供應商、Prompt、重試、快取
• portfolio_builder.py: 投組演算法
• templates/: Jinja 模板（僅結構與少量初始化）
• static/js/{components,pages}/: 前端 JS 組件與頁面邏輯
• sql_script/: DB 初始化
• data_init/: 資料初始化與更新腳本

4) 快速開始

1. 準備 .env（置於專案根目錄）

LLM_PROVIDER=openrouter
OPENROUTER_API_KEY=your_key
OPENROUTER_MODEL=google/gemini-2.0-flash-exp:free
LLM_TIMEOUT=60
LLM_MAX_TOKENS=1500
LLM_TEMPERATURE=0.6
MOCK_LLM=false

2. 啟動容器

docker compose up -d --build --force-recreate

3. 服務連線

• Web: http://localhost:8007
• Postgres: container 內部名稱 db
• Redis: container 內部名稱 redis

5) 開發規範（避免技術債）

• 不動既有架構、Docker 設定與不相關功能。
• 僅在確定「已使用」時才把套件寫入 requirements.txt；未用到的要移除。
• 完成一個環節、測試通過才 commit；不要在同一個 commit 混雜多項變更。
• 前端：避免大型 inline JS；新邏輯放 static/js/pages/*.js 或 static/js/components/*.js。
• 後端：商業邏輯放在服務檔案（如 llm_service.py），main.py 保持輕薄。
• LLM：僅經 get_llm_advisor().generate_advice(strategy_id, strategy_dict)；參數由 .env 控制。

6) 測試

• 後端：可使用離線腳本（MOCK_LLM=true）進行測試。
• 任何變更建議附最小可重現測試或腳本（避免手動點擊測試）。

7) 常見問題

• 500 + LLM 失敗：確認 .env 已注入容器；離線測試可先設 MOCK_LLM=true
• DB 連線錯誤：程式內部連線 host 應為 db
• KeyError（TSLA/AAPL）：確認 data_init 成功寫入對應市場資料

8) Git / PR 規範

• 分支命名：feature/<area>-<short>、fix/<area>-<short>
• PR 標題：[TPM] <Title>；內容包含「動機 / 變更 / 風險 / 測試方式」
• 小步提交、保持向後相容；前端改動請將 JS 抽出至 static/js/

9) 設計原則

• 關注點分離：路由薄、服務厚；模板薄、JS 組件化
• 僅在既有層擴展功能；避免跨層耦合
• 可回退：大改以 feature flag 包裝，保持 simple 模式可用

更詳細的協作規範請見 cursor.md。