# 程式碼模組化盤點（2026-04-30，2026-05-13 校正）

> 用途：接續 ADR-017 Phase 3f 時，快速知道哪些 Python 檔案仍是大檔技術債，以及新增功能應該放在哪個模組層。

## 盤點結論

- Python 總量：約 90,293 行（排除 `venv/`、`backups/`、`__pycache__/`、`.claude/worktrees/`）。
- 最大壓力區：`services/` 約 42,364 行、`routes/` 約 29,511 行。
- `app.py` 目前約 1,232 行，功能定位應固定為 bootstrap / Blueprint registration / startup guard，不再承接新 route。
- 目前工作樹仍有 27 個 Python 檔案達到或超過 800 行；這些不是禁止修 bug，而是禁止繼續塞新功能。
- 2026-05-05 追記：Phase 38→56 觀測台戰役讓 `routes/admin_observability_routes.py` 與 `run_scheduler.py` 進入大檔治理清單；後續觀測台功能應先抽 query/action service，不再把新 SQL 與 L2 mutation 直接塞回 route。
- 2026-05-06 追記：跨平台市場情報模組啟動前，必須先把新增爬蟲、排程、DB schema、UI route 全部隔離在 `market_*` / `services/market_intel/` / `routes/market_intel_routes.py`，不可塞回既有大檔。
- 2026-05-18 追記：Phase 42 市場情報只在 `app.py` 的 `EXPECTED_METADATA_TABLES` 補上 `market_alert_review_queue` 名稱，未新增 route / bootstrap 邏輯；後續仍應把 metadata verification 抽到 app factory 或 startup guard module，避免 `app.py` 繼續承接功能。
- 2026-05-19 追記：同步治理測試盤點，校正 `routes/admin_observability_routes.py` 行數；此處只更新 inventory，不變更觀測台功能。
- 2026-05-19 追記：V10.229 之後 `services/ppt_vision_service.py` 進入 800 行治理清單；本次只補 inventory 讓守門測試反映現況，不變更 PPT 視覺 QA 功能。
- 2026-05-19 追記：同步背景 V10.267 ElephantAlpha 更新後的 `services/elephant_alpha_autonomous_engine.py` 行數；此處只更新 inventory，不變更 AI engine 行為。

## 達到或超過 800 行檔案清單

| 行數 | 檔案 | 分類 | 拆分方向 |
|---:|---|---|---|
| 9225 | `routes/openclaw_bot_routes.py` | P0 巨型 Blueprint | route / bot command service / report service / scheduler hook；禁止再新增市場情報入口 |
| 5499 | `services/ppt_generator.py` | P0 報表生成巨型 service | deck orchestration / slide builders / chart builders / report type registry |
| 3186 | `routes/sales_routes.py` | P0 巨型 Blueprint | page routes / API routes / chart query service / calendar service；分析頁新增功能先抽 `services/sales/` |
| 2821 | `scheduler.py` | P0 排程總管 | task registry / crawler jobs / report jobs / notification jobs；市場情報只能透過獨立 job module 掛入 |
| 2731 | `services/openclaw_strategist_service.py` | P0 OpenClaw service | prompt builders / report composer / strategy rules |
| 3681 | `routes/admin_observability_routes.py` | P0 觀測台巨型 Blueprint | `services/observability_query_service.py` / `services/observability_action_service.py` / route glue |
| 1796 | `routes/ai_routes.py` | P1 AI Blueprint | route glue / AI orchestration service / prompt builders |
| 1721 | `services/nemoton_dispatcher_service.py` | P1 NemoTron service | NIM client / tool-call parser / action dispatcher |
| 1507 | `routes/dashboard_routes.py` | P1 Dashboard Blueprint | competitor decision overview / dashboard query service；首頁資料整併需抽 service |
| 1485 | `routes/vendor_routes.py` | P1 Vendor Blueprint | route glue / stockout mutation/email；V2 page query、stockout list/batches API query、vendor list/detail query 已抽到 `services/vendor_stockout_query_service.py` |
| 1390 | `services/telegram_bot_service.py` | P1 Telegram service | command handlers / message formatters / bot client |
| 1237 | `app.py` | P1 bootstrap | 保持只做 app setup；繼續往 app_factory / extension setup 抽；Phase 42 只做 metadata table name 對齊 |
| 1597 | `services/elephant_alpha_autonomous_engine.py` | P1 ElephantAlpha engine | HITL / executor / planning policy |
| 970 | `routes/cicd_routes.py` | P2 CI/CD Blueprint | route glue / CI query service / deployment action service |
| 1017 | `run_scheduler.py` | P2 scheduler entrypoint | observability jobs / token report jobs / task registration 分離 |
| 916 | `services/ppt_auto_generation_service.py` | P2 PPT 自動產線 service | schedule resolver / generation queue / missing report planner |
| 966 | `services/trend_crawler.py` | P2 crawler service | source adapters / parser / persistence |
| 942 | `services/learning_pipeline.py` | P2 RAG learning pipeline | distiller / promotion gate / persistence / telemetry |
| 940 | `services/import_service.py` | P2 import service | validators / import writers / report builders |
| 867 | `services/token_report_service.py` | P2 token report service | query / aggregation / chart payload / notification formatting |
| 865 | `routes/daily_sales_routes.py` | P2 Daily Sales Blueprint | route glue / export helpers / daily query and formatting service |
| 844 | `services/ollama_service.py` | P2 Ollama client | host health / request client / fallback policy / response parsing |
| 837 | `services/code_review_pipeline_service.py` | P2 Code review pipeline service | scan orchestration / finding normalization / persistence adapter |
| 832 | `routes/export_routes.py` | P2 Export flow | export command/router glue / file path / download orchestration |
| 816 | `services/ppt_vision_service.py` | P2 PPT vision QA service | runtime state / queue status / model probe / audit execution 分離 |
| 904 | `services/competitor_price_feeder.py` | P2 competitor price feeder | crawler scheduling / price normalization / cache strategy |
| 805 | `routes/bot_api_routes.py` | P2 Bot API Blueprint | route glue / bot action service |

## 市場情報開發前置禁區

- 不得把跨平台活動頁、商品池、比對審核 API 新增到 `routes/sales_routes.py`、`routes/dashboard_routes.py` 或 `app.py`。
- 不得把 MOMO / PChome / Coupang / Shopee adapter 寫進 `scheduler.py` 或既有 crawler 巨檔；必須放在 `services/market_intel/adapters/`。
- 不得把市場情報商品塞回 `promo_products` 作為唯一真相；新資料以 `market_*` schema 為主，舊表只可做相容讀取或明確雙寫過渡。
- 不得在第一階段啟用正式排程或大量入庫；必須先 feature flag 關閉、dry-run、run log、rate limit 與 rollback path。
- 新市場情報 UI 必須先使用共用 V2 token / 分析頁元件規範，避免複製 `templates/sales_analysis.html` 的巨型 template 模式。

## 工作項目

1. P0：持續拆 `routes/openclaw_bot_routes.py`；Telegram API helper 已搬到 `services/openclaw_bot/telegram_api.py`，Inline Keyboard builders 已搬到 `services/openclaw_bot/menu_keyboards.py`，下一步拆 report formatting 或 command dispatcher。
2. P0：拆 `routes/sales_routes.py`，先把 chart/query/calendar 計算搬到 `services/sales/`。
3. P0：拆 `scheduler.py`，建立 `jobs/` 或 `services/scheduler/` task registry。
4. P0：拆 `routes/admin_observability_routes.py`，先搬純查詢函式到 `services/observability_query_service.py`，再搬 AutoHeal / Code Review / AiderHeal / throttle mutation 到 `services/observability_action_service.py`。
5. P1：把 `routes/ai_routes.py` 與 `routes/vendor_routes.py` 的資料處理移出 route；Vendor V2 page query、stockout API list/batches、vendor list/detail 已完成，下一步可抽 email grouping 或 vendor mutation service。
6. P1：把 PPT / NemoTron / OpenClaw / Telegram 大 service 拆成 client、parser、composer、policy。
7. P2：對 800-1100 行檔案採「碰到就順手抽」策略，但不可讓淨行數繼續增加。
8. 市場情報：先建獨立 `services/market_intel/`、`routes/market_intel_routes.py`、`database/market_intel_models.py`，再評估是否接進 scheduler registry。

## 守門

- `tests/test_modularization_governance.py` 會掃描所有 Python 檔案；任何新的 >800 行檔案沒有列在本 inventory 就會失敗。
- 若檔案拆小後低於 800 行，可從本清單移除並同步更新測試。