ewoooc/docs/memory/code_modularization_inventory_20260430.md

程式碼模組化盤點（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.276 ElephantAlpha 更新後的 services/elephant_alpha_autonomous_engine.py 行數；此處只更新 inventory，不變更 AI engine 行為。
• 2026-05-19 追記：同步背景 V10.281/V10.282 dashboard 與 Code Review pipeline 更新後的行數；此處只更新 inventory，不變更 dashboard 或 code review 行為。

達到或超過 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
1777	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 對齊
1800	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
1042	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 行，可從本清單移除並同步更新測試。