ewoooc/docs/guides/modularization_governance.md

模組化治理指南

目的：讓 EwoooC 後續功能不再回到「單一巨檔、分類不清、共用邏輯複製貼上」的狀態。

分層規則

層級	放什麼	不放什麼
app.py	Flask 初始化、Blueprint 註冊、啟動自檢、版本	route 實作、DB 查詢、商業邏輯、排程任務
routes/	HTTP request/response、表單參數解析、權限 decorator、呼叫 service	大量資料轉換、外部 API client、可重用計算
services/	商業邏輯、AI pipeline、外部 API client、報表生成、可重用流程	Flask request 物件、template rendering、route-only glue
database/	ORM models、DB manager、schema helpers、migration baseline	HTTP/Telegram/AI side effect
utils/	無狀態純工具、字串/時間/安全 helper	需要 DB/session/env-heavy 的流程
templates/	Jinja UI	Python business rule

檔案尺寸規則

• 300 行以下：健康範圍。
• 300-600 行：可接受，但新增功能前要確認是否能抽 service/helper。
• 600-800 行：警戒範圍；PR/commit 需說明為何不拆。
• 800 行以上：技術債範圍；只能做 bugfix、安全修補、或「往外抽」的過渡改動。新增功能應先拆模組。
• 新增超過 800 行的 Python 檔案必須更新 docs/memory/code_modularization_inventory_20260430.md，否則 tests/test_modularization_governance.py 會失敗。

新功能落點決策

1. 先問：這是 HTTP endpoint、商業流程、DB access、外部 API、還是純工具？
2. endpoint 只新增到對應 Blueprint，不新增到 app.py。
3. route 內超過 40 行的資料處理，優先抽到 services/。
4. 兩個以上 route 需要同一段邏輯時，第一次就抽 shared service，不複製貼上。
5. service 需要 DB 時，透過既有 DatabaseManager / repository-style helper，不在 route 裡反覆建立 engine。
6. AI 自動化、告警、自癒相關變更需同步檢查 docs/AI_INTELLIGENCE_MODULE_SOT.md。

拆大檔順序

優先處理「又大又承擔多種責任」的檔案：

1. routes/openclaw_bot_routes.py：拆成 route、bot command service、learning/report service、scheduler hook。
2. routes/sales_routes.py：拆 dashboard/page routes、API routes、chart/query service。
3. scheduler.py：拆 task registry、crawler jobs、report jobs、notification jobs。
4. routes/ai_routes.py / routes/vendor_routes.py：把資料處理與整合邏輯移到 services。
5. services/ppt_generator.py：拆 deck orchestration、chart builders、slide templates。

Review 檢查表

• 是否新增 @app.route？若是，退回改 Blueprint。
• route 是否直接包含大量 SQL、DataFrame、AI prompt 組裝或外部 API 呼叫？若是，抽 service。
• 是否讓既有 >800 行檔案淨增加？若是，先抽模組或更新 inventory 與拆分計畫。
• 是否新增重複 cache / DB manager / Telegram / AI client 初始化？若是，改用既有 service。
• 是否需要更新 ADR、memory、SOT 或 guide？若是，本次 commit 一起更新。