docs(modularization): 建立模組化治理守門

docs/memory/README.md

@@ -18,6 +18,7 @@
 | `feedback_db_metadata_import.md` | SQLAlchemy metadata / `create_all()` 漏表鐵律 | 新增 model、修 schema、排查 fresh env 漏表時 |
 | `db_connection_pool_singleton_20260430.md` | PostgreSQL `too many clients` 連線池放大事故與 DatabaseManager singleton 修正 | 排查 DB 連線數暴增、route 內反覆初始化 DatabaseManager、SQLAlchemy engine/pool 行為時 |
 | `project_phase3f_cleanup_roadmap.md` | ADR-017 執行矩陣與階段紅線 | 正在做 3f 模組化收尾時 |
+| `code_modularization_inventory_20260430.md` | Python 大檔盤點、分層規範與拆分工作項目 | 新增功能、拆大檔、審查是否違反模組化治理時 |
 | `schema_inventory_baseline.md` | DB 表分類與 drift 基線 | 要收斂 migration / ORM / raw SQL 真相時 |
 
 ## 關聯 Guide

docs/memory/code_modularization_inventory_20260430.md

@@ -0,0 +1,44 @@
+# 程式碼模組化盤點（2026-04-30）
+
+> 用途：接續 ADR-017 Phase 3f 時，快速知道哪些 Python 檔案仍是大檔技術債，以及新增功能應該放在哪個模組層。
+
+## 盤點結論
+
+- Python 總量：約 64,748 行。
+- 最大壓力區：`routes/` 約 21,020 行、`services/` 約 24,533 行。
+- `app.py` 已降到 1,206 行，功能定位應固定為 bootstrap / Blueprint registration / startup guard，不再承接新 route。
+- 目前仍有 15 個 Python 檔案超過 800 行；這些不是禁止修 bug，而是禁止繼續塞新功能。
+
+## 超過 800 行檔案清單
+
+| 行數 | 檔案 | 分類 | 拆分方向 |
+|---:|---|---|---|
+| 5543 | `routes/openclaw_bot_routes.py` | P0 巨型 Blueprint | route / bot command service / report service / scheduler hook |
+| 2653 | `routes/sales_routes.py` | P0 巨型 Blueprint | page routes / API routes / chart query service / calendar service |
+| 2644 | `scheduler.py` | P0 排程總管 | task registry / crawler jobs / report jobs / notification jobs |
+| 1662 | `routes/ai_routes.py` | P1 AI Blueprint | route glue / AI orchestration service / prompt builders |
+| 1661 | `routes/vendor_routes.py` | P1 Vendor Blueprint | route glue / vendor query service / stockout service |
+| 1345 | `services/ppt_generator.py` | P1 報表生成 service | deck orchestration / slide builders / chart builders |
+| 1339 | `services/nemoton_dispatcher_service.py` | P1 NemoTron service | NIM client / tool-call parser / action dispatcher |
+| 1300 | `services/openclaw_strategist_service.py` | P1 OpenClaw service | prompt builders / report composer / strategy rules |
+| 1206 | `app.py` | P1 bootstrap | 保持只做 app setup；繼續往 app_factory / extension setup 抽 |
+| 1079 | `routes/cicd_routes.py` | P2 CI/CD Blueprint | route glue / CI query service / deployment action service |
+| 986 | `services/telegram_bot_service.py` | P2 Telegram service | command handlers / message formatters / bot client |
+| 966 | `services/trend_crawler.py` | P2 crawler service | source adapters / parser / persistence |
+| 868 | `services/elephant_alpha_autonomous_engine.py` | P2 ElephantAlpha engine | HITL / executor / planning policy |
+| 818 | `services/import_service.py` | P2 import service | validators / import writers / report builders |
+| 805 | `routes/bot_api_routes.py` | P2 Bot API Blueprint | route glue / bot action service |
+
+## 工作項目
+
+1. P0：拆 `routes/openclaw_bot_routes.py`，先把非 HTTP 邏輯搬到 `services/openclaw_bot/` 子模組。
+2. P0：拆 `routes/sales_routes.py`，先把 chart/query/calendar 計算搬到 `services/sales/`。
+3. P0：拆 `scheduler.py`，建立 `jobs/` 或 `services/scheduler/` task registry。
+4. P1：把 `routes/ai_routes.py` 與 `routes/vendor_routes.py` 的資料處理移出 route。
+5. P1：把 PPT / NemoTron / OpenClaw 大 service 拆成 client、parser、composer、policy。
+6. P2：對 800-1100 行檔案採「碰到就順手抽」策略，但不可讓淨行數繼續增加。
+
+## 守門
+
+- `tests/test_modularization_governance.py` 會掃描所有 Python 檔案；任何新的 >800 行檔案沒有列在本 inventory 就會失敗。
+- 若檔案拆小後低於 800 行，可從本清單移除並同步更新測試。

docs/memory/history_logs.md

@@ -42,6 +42,7 @@
 - **Scheduler 例外記錄強化**: 清除 `scheduler.py` 靜默 `except/pass`，Chrome 清理、EDM optional 欄位、備份 insight/Telegram 失敗均保留 log。
 - **AI metrics baseline 觀測**: `/metrics` 在尚無 AI 自動化事件時仍輸出 `momo_ai_*` zero-baseline series，避免 app 重啟後 Grafana/Prometheus 看不到 metric names。
 - **ElephantAlpha transient fallback**: NVIDIA NIM primary model timeout、connection error、429 與 5xx 會嘗試下一個 fallback model，400 等非暫時性請求錯誤不重試。
+- **模組化治理守門**: 盤點 15 個超過 800 行 Python 大檔，新增 `docs/guides/modularization_governance.md` 與 `tests/test_modularization_governance.py`，防止未分類巨檔再長出來。
 
 ### 2026-04-28~29：Phase 3e 重構大戰 + daily_sales cache 隱形 bug 根除
 - **app.py 縮減 -10.8%**: 7,386 → 6,590 行，11 commits 全綠零 502。

docs/memory/project_phase3f_cleanup_roadmap.md

@@ -18,6 +18,7 @@
 | 3f-3 | scheduler 裸 `except`、EventRouter 同步告警、compose mount、vendor template_folder | 中 | 1-2h |
 | 3f-4 | 模板統一至 `templates/` 與 `web/templates/vendor_stockout/` | 低 | 2-3h |
 | 3f-5 | 孤兒 service 與 `.env.example` 收尾 | 極低 | 30m |
+| 3f-6 | 模組化治理守門：大檔 inventory、分層 guide、測試防新增巨檔 | 低 | 30m |
 
 ## 已校正事項
 
@@ -26,3 +27,4 @@
 - 3f-2 的 `--preload` 只降低 copy-on-write 記憶體成本，一致性仍以 DB fingerprint 為準。
 - 3f-3 必須先補 `EventRouter` 同步 facade，再把 scheduler P1/P2 失敗導入告警。
 - 3f-4 移除 ChoiceLoader fallback 前，需先清 docker-compose 舊 mount 與根目錄模板。
+- 3f-6 已將 >800 行 Python 檔案列入 `docs/memory/code_modularization_inventory_20260430.md`；未來新增巨檔需更新 inventory，否則 `tests/test_modularization_governance.py` 會失敗。