ewoooc/docs/memory/code_modularization_inventory_20260430.md

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

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

盤點結論

• Python 總量：約 139,476 行（排除 venv/、backups/、__pycache__/、.claude/worktrees/）。
• 最大壓力區：services/ 約 84,159 行、routes/ 約 36,245 行。
• app.py 目前約 1,232 行，功能定位應固定為 bootstrap / Blueprint registration / startup guard，不再承接新 route。
• 目前工作樹仍有 33 個 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-24 追記：同步 V10.460 ElephantAlpha decision_envelope helper 後的 services/elephant_alpha_autonomous_engine.py 行數；此處只更新 inventory，不變更 AI engine 行為。
• 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 行為。
• 2026-05-19 追記：同步背景 PChome identity 價格刷新與競品風險查詢更新後的 services/competitor_price_feeder.py 行數；此處只更新 inventory，不變更 feeder 行為。
• 2026-05-19 追記：同步背景 Telegram 模板擴充後的 services/telegram_templates.py 行數；此處只更新 inventory，不變更 Telegram 格式化行為。
• 2026-05-20 追記：同步背景 PChome unit-comparable identity 更新後的 services/marketplace_product_matcher.py 行數；此處只更新 inventory，不變更商品比對行為。
• 2026-05-20 追記：同步背景商品看板覆核快取回填後的 services/competitor_intel_repository.py 行數；此處只更新 inventory，不變更競品情報 repository 行為。
• 2026-05-20 追記：同步背景商品看板比價覆核狀態分流後的 routes/dashboard_routes.py 行數；此處只更新 inventory，不變更 dashboard 行為。
• 2026-05-20 追記：同步背景匯出流程更新後的 routes/export_routes.py 行數；此處只更新 inventory，不變更 export 行為。
• 2026-05-20 追記：同步背景 PChome feeder 人工覆核回饋採納後的 services/competitor_price_feeder.py 行數；此處只更新 inventory，不變更 feeder 行為。
• 2026-05-20 追記：同步背景 PChome 比價人工覆核閉環後的 services/competitor_intel_repository.py 行數；此處只更新 inventory，不變更競品情報 repository 行為。
• 2026-05-20 追記：同步背景 PChome identity / price direction 更新後的 services/marketplace_product_matcher.py 行數；此處只更新 inventory，不變更商品比對行為。
• 2026-05-20 追記：同步背景 PChome crawler 搜尋韌性擴充後的 services/pchome_crawler.py 行數；此處只更新 inventory，不變更 PChome crawler 行為。
• 2026-05-20 追記：同步 PChome 近門檻候選重評與 matcher 系列/刀片數防錯配更新後的 services/marketplace_product_matcher.py、services/competitor_price_feeder.py 行數；此處只更新 inventory，不變更比價行為。
• 2026-05-20 追記：同步 PChome 搜尋詞品質層、候選召回與 hard-veto 狀態分流更新後的 services/marketplace_product_matcher.py、services/competitor_price_feeder.py 行數；並補列背景市場情報 deployment readiness 大檔，僅更新 inventory。
• 2026-05-20 追記：同步 PChome 搜尋詞特定品線優先級更新後的 services/marketplace_product_matcher.py 行數；此處只更新 inventory，不變更模組化決策。
• 2026-05-20 追記：同步 PChome 共享 identity anchor scorer 與市場情報 review report route 進入大檔門檻後的行數；此處只更新 inventory，不變更功能。
• 2026-05-20 追記：同步 PChome contained identity anchor scorer 更新後的 services/marketplace_product_matcher.py 行數；此處只更新 inventory，不變更模組化決策。
• 2026-05-20 追記：同步 PChome spec/name alignment near-threshold scorer 更新後的 services/marketplace_product_matcher.py 行數；此處只更新 inventory，不變更模組化決策。
• 2026-05-20 追記：同步市場情報 review report route 與 review receipt 巨檔現況，並校正 PChome fresh-search recovery 更新後的 services/competitor_price_feeder.py、services/marketplace_product_matcher.py 行數；此處只更新 inventory，不變更模組化決策。
• 2026-05-21 追記：同步 Browse.sh 診斷導入、PChome 變體搜尋與色號防錯配更新後的 services/marketplace_product_matcher.py 行數，並校正市場情報 review report route 目前行數；此處只更新 inventory，不變更模組化決策。
• 2026-05-21 追記：同步市場情報 MCP runtime smoke receipt gate 後的 routes/market_intel_routes.py 與 services/market_intel/deployment_readiness.py 行數；本次 route 只承接既有 Blueprint glue，後續新增 MCP/UI gate 應優先拆出子 Blueprint 或 route registration helper。
• 2026-05-21 追記：同步 111 fallback context/resource guard 合併後的 services/ollama_service.py 行數；此處只更新 inventory，不變更 Ollama 路由行為。
• 2026-05-21 追記：同步專業比價分級連動合併後的 services/competitor_intel_repository.py 與 services/nemoton_dispatcher_service.py 行數；此處只更新 inventory，不變更比價或告警行為。
• 2026-05-21 追記：同步市場情報 MCP runtime promotion gate 後的 routes/market_intel_routes.py 與 services/market_intel/deployment_readiness.py 行數；此處只更新 inventory，後續市場情報 MCP route 應拆出子 Blueprint。
• 2026-05-24 追記：同步市場情報 MCP manual fetch handoff gate 後的 routes/market_intel_routes.py 與 services/market_intel/deployment_readiness.py 行數；本次新增邏輯已放在獨立 services/market_intel/mcp_manual_fetch_handoff.py，route 僅保留薄 glue，下一個 MCP/UI gate 應優先拆出子 Blueprint 或 route registration helper。
• 2026-05-24 追記：同步市場情報 MCP fetch target review gate 後的 routes/market_intel_routes.py 與 services/market_intel/deployment_readiness.py 行數；本次新增邏輯已放在獨立 services/market_intel/mcp_fetch_target_review.py，route 僅保留薄 glue，後續市場情報 MCP route 應拆出子 Blueprint 或 route registration helper。
• 2026-05-24 追記：同步市場情報 MCP fetch run package gate 後的 routes/market_intel_routes.py 與 services/market_intel/deployment_readiness.py 行數；本次新增 endpoint 已拆到 routes/market_intel_mcp_run_routes.py，主 Blueprint 只新增 extension import，後續 MCP route 應延續此模式。
• 2026-05-24 追記：同步市場情報 MCP fetch run readiness gate 後的 services/market_intel/deployment_readiness.py 行數；本次新增 endpoint 延續 routes/market_intel_mcp_run_routes.py route extension，新增邏輯放在獨立 services/market_intel/mcp_fetch_run_readiness.py。
• 2026-05-31 追記：同步市場情報 MCP fetch candidate queue review gate 後的 services/market_intel/deployment_readiness.py 行數；本次新增邏輯維持在獨立 services/market_intel/mcp_fetch_candidate_queue_review.py，route 延續 routes/market_intel_mcp_run_routes.py extension。
• 2026-05-31 追記：同步市場情報 MCP fetch candidate queue writer preflight gate 後的 services/market_intel/deployment_readiness.py 行數；本次新增邏輯維持在獨立 services/market_intel/mcp_fetch_candidate_queue_writer_preflight.py，route 延續 routes/market_intel_mcp_run_routes.py extension。
• 2026-05-31 追記：services/market_intel/mcp_fetch_candidate_queue_writer_preflight.py 目前 628 行，略過 600 行提醒門檻；暫不拆分的理由是 gate 條件、sample payload 與 side-effect blocklist 需留在單一 preview module 便於審核，下一個 writer CLI review gate 若共用相同常數再抽 mcp_fetch_candidate_queue_writer_policy.py。
• 2026-05-31 追記：同步市場情報 MCP fetch candidate queue writer CLI review gate 後的 services/market_intel/deployment_readiness.py 行數；本次新增 services/market_intel/mcp_fetch_candidate_queue_writer_cli_review.py 為 591 行，仍低於 600 行提醒門檻。
• 2026-05-31 追記：同步市場情報 MCP fetch candidate queue writer run package review gate 後的 services/market_intel/deployment_readiness.py 行數；本次新增 services/market_intel/mcp_fetch_candidate_queue_writer_run_package_review.py 為 660 行，略過 600 行提醒門檻。暫不拆分的理由是 run package gate 需要把 CLI review linkage、artifact manifest、operator shell command sequence 與 side-effect blocklist 放在單一 preview module 便於安全審核；若下一段 run readiness review 重複相同 policy，應抽出 writer policy helper。
• 2026-05-31 追記：同步市場情報 MCP fetch candidate queue writer run readiness gate 後的 services/market_intel/deployment_readiness.py 行數；本次新增 services/market_intel/mcp_fetch_candidate_queue_writer_run_readiness.py 為 640 行，略過 600 行提醒門檻。暫不拆分的理由是 readiness gate 需同時審核上一段 run package review linkage、operator artifact path policy、CLI-only/token-only confirmation 與 side-effect blocklist；若後續 run receipt gate 再重複 policy，應抽出 mcp_fetch_candidate_queue_writer_policy.py。
• 2026-05-24 追記：同步背景 Code Review 111 fallback 保護合併後的 services/code_review_pipeline_service.py 行數；此處只更新 inventory，不變更 Code Review 行為。
• 2026-05-21 追記：同步 PChome/LUDEYA 商品線名稱漂移比對更新後的 services/marketplace_product_matcher.py 行數；此處只更新 inventory，不變更模組化決策。
• 2026-05-21 追記：同步 MAC/Yuskin/AHC 名稱漂移與 bundle equivalent matcher 更新後的 services/marketplace_product_matcher.py 行數；此處只更新 inventory，不變更模組化決策。
• 2026-05-21 追記：同步 EDM 失效頁 alert guard 與 REJURAN 唇膏寬價差 exact-identity matcher 更新後的 scheduler.py、services/marketplace_product_matcher.py 行數；此處只更新 inventory，不變更模組化決策。
• 2026-05-21 追記：同步過期 EDM / seasonal promo crawler 排程改為 opt-in、NIVEA/OPI 搜尋 noise 與 identity anchor 補強後的 run_scheduler.py、services/marketplace_product_matcher.py 行數；此處只更新 inventory，不變更模組化決策。
• 2026-05-21 追記：同步 Recipe Box 多效提亮防曬霜同款漂移比對補強後的 services/marketplace_product_matcher.py 行數；此處只更新 inventory，不變更模組化決策。
• 2026-05-21 追記：同步 browse.sh 診斷計畫寫入 competitor_match_attempts 後的 services/competitor_price_feeder.py 行數；此處只更新 inventory，不變更模組化決策。
• 2026-05-24 追記：同步背景 PChome 近門檻身份回收與 focused identity 系列更新後的 services/marketplace_product_matcher.py 行數；此處只更新 inventory，不變更商品比對行為。
• 2026-05-24 追記：同步 111 fallback circuit breaker、NemoTron 決策信封與 Telegram template governance 後的 run_scheduler.py、services/ollama_service.py、services/nemoton_dispatcher_service.py、services/telegram_templates.py 行數；此處只更新 inventory，不變更模組化決策。
• 2026-05-24 追記：同步 PChome 覆核頁 fast-count、輕量 render 與重算可採用指標後的 routes/dashboard_routes.py 行數；此處只更新 inventory，不變更 dashboard 行為。
• 2026-05-24 追記：同步 PChome rescore audit 最新狀態口徑與單位價 multiplier 修正後的 services/marketplace_product_matcher.py 行數；此處只更新 inventory，不變更拆分策略。
• 2026-05-24 追記：同步 PChome review queue 決策信封合併後的 services/competitor_intel_repository.py 行數；此處只更新 inventory，不變更拆分策略。
• 2026-05-25 追記：同步背景 embedding 讀取 host_health_probes skip guard 後的 services/ollama_service.py 行數；此處只更新 inventory，不變更 Ollama 路由決策。
• 2026-05-29 追記：同步 PChome near-threshold / focused identity 回收系列後的 services/marketplace_product_matcher.py 行數；此處只更新 inventory，不變更拆分策略。

達到或超過 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/
2973	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
2154	services/nemoton_dispatcher_service.py	P1 NemoTron service	NIM client / tool-call parser / action dispatcher
2535	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 對齊
2149	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
1250	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
1071	services/telegram_templates.py	P2 Telegram templates	alert template groups / channel-specific formatting / reusable render helpers
867	services/token_report_service.py	P2 token report service	query / aggregation / chart payload / notification formatting
4865	services/marketplace_product_matcher.py	P2 marketplace matcher	identity parsing / unit-comparable scoring / search term quality / persistence normalization
865	routes/daily_sales_routes.py	P2 Daily Sales Blueprint	route glue / export helpers / daily query and formatting service
1266	services/ollama_service.py	P2 Ollama client	host health / request client / fallback policy / response parsing
849	services/pchome_crawler.py	P2 PChome crawler	search fetch / parsing / fallback source handling / rate limit policy
1100	services/code_review_pipeline_service.py	P2 Code review pipeline service	scan orchestration / finding normalization / persistence adapter
953	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 分離
2149	services/competitor_price_feeder.py	P2 competitor price feeder	crawler scheduling / price normalization / retryable candidate recovery / cache strategy
1535	services/competitor_intel_repository.py	P2 competitor intel repository	review queue query / cache shaping / formatting helpers
805	routes/bot_api_routes.py	P2 Bot API Blueprint	route glue / bot action service
1319	routes/market_intel_review_report_routes.py	P2 market intel review report Blueprint	review report route glue / export payload / phase handoff orchestration
917	routes/market_intel_routes.py	P2 market intel Blueprint	page route / API route glue / MCP gate route registration helper
1260	services/market_intel/deployment_readiness.py	P2 market intel deployment readiness	preflight gates / readiness payload / route contract helpers
846	services/market_intel/candidate_queue_review_ai_summary_persistence_telegram_dispatch_report_catalog_record_run_receipt.py	P2 market intel review receipt pipeline	AI summary / persistence / Telegram dispatch / report catalog run receipt orchestration

市場情報開發前置禁區

• 不得把跨平台活動頁、商品池、比對審核 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 行，可從本清單移除並同步更新測試。