4.8 KiB
4.8 KiB
程式碼模組化盤點（2026-04-30）
用途：接續 ADR-017 Phase 3f 時，快速知道哪些 Python 檔案仍是大檔技術債，以及新增功能應該放在哪個模組層。
盤點結論
- Python 總量：約 66,997 行。
- 最大壓力區：
routes/約 21,095 行、services/約 26,023 行。 app.py目前約 1,209 行，功能定位應固定為 bootstrap / Blueprint registration / startup guard，不再承接新 route。- 目前工作樹仍有 18 個 Python 檔案超過 800 行；這些不是禁止修 bug，而是禁止繼續塞新功能。
- 2026-05-05 追記：Phase 38→56 觀測台戰役讓
routes/admin_observability_routes.py與run_scheduler.py進入大檔治理清單；後續觀測台功能應先抽 query/action service，不再把新 SQL 與 L2 mutation 直接塞回 route。
超過 800 行檔案清單
| 行數 | 檔案 | 分類 | 拆分方向 |
|---|---|---|---|
| 5240 | routes/openclaw_bot_routes.py |
P0 巨型 Blueprint | route / bot command service / report service / scheduler hook |
| 2707 | scheduler.py |
P0 排程總管 | task registry / crawler jobs / report jobs / notification jobs |
| 2653 | routes/sales_routes.py |
P0 巨型 Blueprint | page routes / API routes / chart query service / calendar service |
| 2550 | routes/admin_observability_routes.py |
P0 觀測台巨型 Blueprint | services/observability_query_service.py / services/observability_action_service.py / route glue |
| 1743 | routes/ai_routes.py |
P1 AI Blueprint | route glue / AI orchestration service / prompt builders |
| 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 |
| 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 |
| 1209 | 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 |
| 1024 | routes/dashboard_routes.py |
P2 Dashboard Blueprint | competitor decision overview / dashboard query 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 |
| 946 | services/elephant_alpha_autonomous_engine.py |
P2 ElephantAlpha engine | HITL / executor / planning policy |
| 868 | run_scheduler.py |
P2 scheduler entrypoint | observability jobs / token report jobs / task registration 分離 |
| 829 | routes/export_routes.py |
P2 Export flow | export command/router glue / file path / download orchestration |
| 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 |
| 805 | services/competitor_price_feeder.py |
P2 competitor price feeder | crawler scheduling / price normalization / cache strategy |
工作項目
- 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。 - P0：拆
routes/sales_routes.py，先把 chart/query/calendar 計算搬到services/sales/。 - P0：拆
scheduler.py，建立jobs/或services/scheduler/task registry。 - P0：拆
routes/admin_observability_routes.py，先搬純查詢函式到services/observability_query_service.py，再搬 AutoHeal / Code Review / AiderHeal / throttle mutation 到services/observability_action_service.py。 - 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。 - P1：把 PPT / NemoTron / OpenClaw 大 service 拆成 client、parser、composer、policy。
- P2：對 800-1100 行檔案採「碰到就順手抽」策略，但不可讓淨行數繼續增加。
守門
tests/test_modularization_governance.py會掃描所有 Python 檔案；任何新的 >800 行檔案沒有列在本 inventory 就會失敗。- 若檔案拆小後低於 800 行，可從本清單移除並同步更新測試。