# 程式碼模組化盤點（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 行，可從本清單移除並同步更新測試。