forked from lab/TPM
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
71 lines
2.9 KiB
71 lines
2.9 KiB
### 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`。 |
|
|
|
|