forked from lab/TPM
Eric0801
2 months ago
parent
c35d0cd8aa
commit
3290b69d72
1 changed files with 57 additions and 0 deletions
@ -0,0 +1,57 @@ |
||||
### 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 中說明動機與回滾方案。 |
||||
|
||||
Loading…
Reference in new issue