TPM/cursor.md

Purpose

• 定義 AI 與人類協作的開發規範，避免分散、重複與難以維護的代碼。
• 嚴格限制可修改範圍與方式，降低技術債。

Architecture Guardrails

• Backend: 維持 Flask（單應用）+ PostgreSQL + Redis + Plotly SSR。不得引入新後端框架（如 FastAPI、Django）。
• Frontend: 維持 Jinja SSR + Bootstrap 5。避免新增其他 CSS 框架；僅在必要時使用 jQuery（若頁面已依賴）。
• LLM: 只能透過 llm_service.py 的封裝介面呼叫；前端僅呼叫既有 API。
• DB: 目前採 psycopg2 直連 SQL。若要導入 ORM，需先提 RFC 並分層重構（Repository/Service 分離）。
• Realtime: 若需 Agentic 進度，優先 SSE；如需 WebSocket，需提 RFC。禁止同時混用兩者。

Files Ownership

• main.py: 僅負責路由、參數與 Response 序列化；禁止寫演算法或外部 API 邏輯。
• llm_service.py: 唯一 LLM 入口；新增供應商、Prompt、重試、快取皆在此擴展。
• portfolio_builder.py: 僅放投組相關演算法。
• templates/*.html: 僅做結構與插值；避免大型 inline JS；頁面邏輯放 static/js/pages/*.js。
• static/js/components/*: 前端可複用組件；不得引用非必要的全域物件。
• docker-compose.yml: 僅調整現有服務設定；新增服務需提 RFC。
• requirements.txt: 僅加入「已使用」的最小依賴；未使用須移除。

Frontend Rules

• 禁止在模板中新增大型 inline JS。新邏輯放 static/js/pages/<page>.js 或 static/js/components/<comp>.js，模板只保留初始化。
• 樣式統一 Bootstrap 5；避免再引入其他 CSS 框架；圖標統一 Bootstrap Icons。
• Markdown：優先在後端使用 markdown 轉 HTML；不要寫自製 Markdown 解析器。

LLM Rules

• 僅用 get_llm_advisor().generate_advice(strategy_id, strategy_dict) 封裝介面。
• Provider/Model/Token/Timeout 由 .env 或 config.py 管理；程式內不得硬編碼。
• 慢任務需提供 mode=simple|agentic|auto，預設 simple。
• Mock 測試：支援 MOCK_LLM=true 的離線路徑。

Testing & Quality

• 後端：新增/修改路由與服務需附基本單元測試或離線測試腳本（可用 MOCK_LLM）。
• 前端：邏輯拆為可測的純函數；避免深層 DOM 操作耦合。
• 風格：PEP8；命名語義化；函式不超過 ~100 行；避免深巢狀。
• 禁留 TODO/死碼；必要時加簡短註解說明「為何存在」。

Git / PR Workflow

• 分支：feature/<area>-<short>、fix/<area>-<short>。
• PR 標題：[TPM] <Title>；內容包含「動機 / 變更 / 雙向風險 / 測試」。
• 提交頻率：完成一個環節且測試通過才 commit；不要在同一 commit 混雜多項變更。
• 禁止無關變更（例如排版清理與邏輯修改混在一起）。

Change Checklist (DoD)

• 有對應文件或內嵌註解簡述「為何」。
• 測試或腳本可重跑；離線可跑（如 LLM mock）。
• API 相容，不破壞現有 flow。
• 不新增全域副作用或跨層耦合。

Out-of-Scope（需先提 RFC）

• 更換 Web 框架或引入大型基礎設施（如微服務、消息隊列）。
• 引入新前端框架或 CSS 系統。
• 重構資料層成 ORM。

---

本文件供 AI/協作工具與開發者遵循，若有必要變更，請先起草 RFC 並在 PR 中說明動機與回滾方案。