docs: add README with setup, workflow, and guardrails; no code changes

README.md

@@ -0,0 +1,71 @@
+### 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`。
+