7.6 KiB
7.6 KiB
程式碼模組化盤點（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。- 目前工作樹仍有 26 個 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-18 追記：同步治理測試盤點，新增
services/code_review_pipeline_service.py、services/ppt_auto_generation_service.py，並校正routes/admin_observability_routes.py、services/import_service.py行數。
達到或超過 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 |
| 3283 | 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 對齊 |
| 1144 | 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 |
| 809 | 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 模式。
工作項目
- 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 / Telegram 大 service 拆成 client、parser、composer、policy。
- P2：對 800-1100 行檔案採「碰到就順手抽」策略，但不可讓淨行數繼續增加。
- 市場情報：先建獨立
services/market_intel/、routes/market_intel_routes.py、database/market_intel_models.py，再評估是否接進 scheduler registry。
守門
tests/test_modularization_governance.py會掃描所有 Python 檔案；任何新的 >800 行檔案沒有列在本 inventory 就會失敗。- 若檔案拆小後低於 800 行，可從本清單移除並同步更新測試。