# 程式碼模組化盤點（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。
- 目前工作樹仍有 42 個 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-31 追記：同步市場情報 MCP fetch candidate queue writer run receipt review gate 後的 `services/market_intel/deployment_readiness.py` 行數；本次新增 `services/market_intel/mcp_fetch_candidate_queue_writer_run_receipt_review.py` 為 688 行，略過 600 行提醒門檻。暫不拆分的理由是 receipt gate 需同時審核 readiness linkage、receipt identity、artifact path policy、operator confirmation、token redaction 與 side-effect blocklist；若下一段 closeout gate 重複相同 path/side-effect policy，應抽出 `mcp_fetch_candidate_queue_writer_policy.py`。
- 2026-05-31 追記：同步市場情報 MCP fetch candidate queue writer run closeout review gate 後的 `services/market_intel/deployment_readiness.py` 行數；本次新增 `services/market_intel/mcp_fetch_candidate_queue_writer_run_closeout_review.py` 為 724 行，略過 600 行提醒門檻。暫不拆分的理由是 closeout gate 需同時審核 receipt review linkage、artifact manifest preservation、rollback note、read-only inventory next-step、lightweight preview sample 與 side-effect blocklist；若下一段 post-closeout inventory gate 重複 path/side-effect policy，應抽出 `mcp_fetch_candidate_queue_writer_policy.py`。
- 2026-05-31 追記：同步市場情報 MCP fetch candidate queue writer post-closeout inventory review gate 後的 `services/market_intel/deployment_readiness.py` 行數；本次新增 `services/market_intel/mcp_fetch_candidate_queue_writer_post_closeout_inventory_review.py` 為 649 行，略過 600 行提醒門檻。暫不拆分的理由是 inventory gate 需同時審核 closeout linkage、read-only inventory 摘要、artifact path policy、operator boundary confirmation 與 side-effect blocklist；後續若 candidate queue review handoff 再複用同一套 path/side-effect policy，應抽出 `mcp_fetch_candidate_queue_writer_policy.py`。
- 2026-05-31 追記：同步市場情報 MCP fetch candidate queue writer review handoff gate 後的 `services/market_intel/deployment_readiness.py` 行數；本次將 sample payload 抽到 `services/market_intel/mcp_fetch_candidate_queue_writer_review_handoff_sample.py`（105 行），主 gate `services/market_intel/mcp_fetch_candidate_queue_writer_review_handoff.py` 降為 571 行，低於 600 行提醒門檻；後續若 candidate queue review inventory 繼續複用 path/side-effect policy，應抽出 `mcp_fetch_candidate_queue_writer_policy.py`。
- 2026-05-31 追記：同步市場情報 MCP fetch candidate queue writer review inventory gate 後的 `services/market_intel/deployment_readiness.py` 行數；本次新增 `services/market_intel/mcp_fetch_candidate_queue_writer_review_inventory.py`（462 行）、`services/market_intel/mcp_fetch_candidate_queue_writer_review_inventory_gates.py`（183 行）與 `services/market_intel/mcp_fetch_candidate_queue_writer_review_inventory_sample.py`（107 行），全部低於 600 行提醒門檻；`routes/market_intel_mcp_run_routes.py` 目前 717 行，仍低於 800 行但後續新增 MCP gate 應持續評估拆第二個 route extension。
- 2026-05-31 追記：同步市場情報 MCP fetch candidate queue writer review decision gate 後的 `services/market_intel/deployment_readiness.py` 行數；本次新增 `services/market_intel/mcp_fetch_candidate_queue_writer_review_decision.py`（498 行）、`services/market_intel/mcp_fetch_candidate_queue_writer_review_decision_gates.py`（241 行）與 `services/market_intel/mcp_fetch_candidate_queue_writer_review_decision_sample.py`（118 行），全部低於 600 行提醒門檻；`routes/market_intel_mcp_run_routes.py` 目前 772 行，仍低於 800 行但已接近門檻，下一段 MCP route 應優先拆第二個 route extension。
- 2026-05-31 追記：同步市場情報 MCP fetch candidate queue writer review decision approval gate 後的 `services/market_intel/deployment_readiness.py` 行數；本次新增 `services/market_intel/mcp_fetch_candidate_queue_writer_review_decision_approval.py`（560 行）、`services/market_intel/mcp_fetch_candidate_queue_writer_review_decision_approval_gates.py`（255 行）、`services/market_intel/mcp_fetch_candidate_queue_writer_review_decision_approval_sample.py`（140 行）與 `routes/market_intel_mcp_review_routes.py`（64 行），全部低於 600 行提醒門檻；`routes/market_intel_mcp_run_routes.py` 維持 770 行，本次未再加 endpoint，改以第二個 MCP review route extension 承接。
- 2026-06-01 追記：同步市場情報 Professional Source Governance gate 後的 `services/market_intel/deployment_readiness.py` 行數；本次新增 `services/market_intel/mcp_professional_source_governance.py`（391 行）、`services/market_intel/mcp_professional_source_governance_gates.py`（266 行）、`services/market_intel/mcp_professional_source_governance_sample.py`（175 行）與 `routes/market_intel_mcp_review_routes.py`（165 行），全部低於 600 行提醒門檻；`services/market_intel/deployment_readiness.py` 仍是既有 P2 大檔，只加 preview-safe check 與 smoke target，後續需延續小 service + route extension 模式。
- 2026-06-03 追記：新增 `services/market_intel/mcp_fetch_target_source_governance_review.py`（237 行），並將 `mcp_professional_source_governance_sample.py` 擴為 307 行、`routes/market_intel_mcp_review_routes.py` 擴為 207 行；新增服務仍低於 600 行提醒門檻。`services/market_intel/deployment_readiness.py` 擴為 2010 行，仍屬既有 P2 大檔，後續應優先拆 readiness smoke/check registration。
- 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，不變更拆分策略。
- 2026-06-29 追記：同步 AI 自動化例外決策、PChome mapping backlog 與 market intel alias work 後的 >800 行檔案清單；此處只更新 inventory，不變更拆分策略。
- 2026-06-29 追記：同步 market intel AI-controlled canonical route aliases 後的 route extension 行數；`routes/market_intel_mcp_run_routes.py` 與 `routes/market_intel_review_post_routes.py` 進入 800 行治理清單，下一步新增 route alias 應優先抽 route registration helper，避免 extension 檔繼續膨脹。
- 2026-06-29 追記：同步 market intel review/report endpoint compatibility migration 後的 route extension 行數；`routes/market_intel_review_routes.py` 進入 800 行治理清單，下一步應抽 `market_intel_review_route_registration.py` 或 declarative endpoint map，避免 decorator 重複擴張。
- 2026-07-14 追記：`services/pchome_revenue_growth_service.py` 因新增可稽核比價覆蓋契約與 active-catalog scope 增至 1,366 行；此輪先完成 P0 正確性，後續 `ARCH-P1-001` 應拆出 catalog coverage query 與 metric-contract builder，主 service 保留 orchestration。
- 2026-07-15 追記：`services/pchome_growth_same_item_reconciliation.py` 已達 880 行；同商品 identity verifier、exact DB readback、coverage post-verifier 與 durable receipt persistence 應在 `ARCH-P1-001` 拆成獨立 policy/verifier/repository，主模組只保留 bounded orchestration。

## 達到或超過 800 行檔案清單

| 行數 | 檔案 | 分類 | 拆分方向 |
|---:|---|---|---|
| 9424 | `routes/openclaw_bot_routes.py` | P0 巨型 Blueprint | route / bot command service / report service / scheduler hook；禁止再新增市場情報入口 |
| 8689 | `services/pchome_mapping_backlog_service.py` | P0 PChome mapping backlog service | mapping backlog / evidence receipt / controlled apply package 分拆到 `services/pchome_mapping/` |
| 5865 | `services/marketplace_product_matcher.py` | P2 marketplace matcher | identity parsing / unit-comparable scoring / search term quality / persistence normalization |
| 5513 | `services/ppt_generator.py` | P0 報表生成巨型 service | deck orchestration / slide builders / chart builders / report type registry |
| 4398 | `routes/ai_routes.py` | P1 AI Blueprint | route glue / AI orchestration service / prompt builders |
| 4152 | `routes/admin_observability_routes.py` | P0 觀測台巨型 Blueprint | `services/observability_query_service.py` / `services/observability_action_service.py` / route glue |
| 3763 | `services/competitor_price_feeder.py` | P2 competitor price feeder | crawler scheduling / price normalization / retryable candidate recovery / cache strategy |
| 3290 | `routes/sales_routes.py` | P0 巨型 Blueprint | page routes / API routes / chart query service / calendar service；分析頁新增功能先抽 `services/sales/` |
| 3125 | `routes/dashboard_routes.py` | P1 Dashboard Blueprint | competitor decision overview / dashboard query service；首頁資料整併需抽 service |
| 3107 | `scheduler.py` | P0 排程總管 | task registry / crawler jobs / report jobs / notification jobs；市場情報只能透過獨立 job module 掛入 |
| 2961 | `services/openclaw_strategist_service.py` | P0 OpenClaw service | prompt builders / report composer / strategy rules |
| 2383 | `services/competitor_intel_repository.py` | P2 competitor intel repository | review queue query / cache shaping / formatting helpers |
| 2332 | `services/elephant_alpha_autonomous_engine.py` | P1 ElephantAlpha engine | AI exception policy / executor / planning policy |
| 2166 | `services/nemoton_dispatcher_service.py` | P1 NemoTron service | NIM client / tool-call parser / action dispatcher |
| 2017 | `services/market_intel/deployment_readiness.py` | P2 market intel deployment readiness | preflight gates / readiness payload / route contract helpers |
| 1956 | `services/external_market_offer_service.py` | P2 external offer service | offer ingestion / freshness / quality normalization 分離 |
| 1658 | `routes/market_intel_review_report_routes.py` | P2 market intel review report Blueprint | review report route glue / export payload / phase handoff orchestration |
| 1494 | `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` |
| 1456 | `services/ollama_service.py` | P2 Ollama client | host health / request client / fallback policy / response parsing |
| 1417 | `services/telegram_templates.py` | P2 Telegram templates | alert template groups / channel-specific formatting / reusable render helpers |
| 1394 | `services/telegram_bot_service.py` | P1 Telegram service | command handlers / message formatters / bot client |
| 1385 | `services/import_service.py` | P2 import service | validators / import writers / report builders |
| 1306 | `run_scheduler.py` | P2 scheduler entrypoint | observability jobs / token report jobs / task registration 分離 |
| 1271 | `services/code_review_pipeline_service.py` | P2 Code review pipeline service | scan orchestration / finding normalization / persistence adapter |
| 1255 | `app.py` | P1 bootstrap | 保持只做 app setup；繼續往 app_factory / extension setup 抽；Phase 42 只做 metadata table name 對齊 |
| 1188 | `services/ppt_auto_generation_service.py` | P2 PPT 自動產線 service | schedule resolver / generation queue / missing report planner |
| 1023 | `routes/cicd_routes.py` | P2 CI/CD Blueprint | route glue / CI query service / deployment action service |
| 1014 | `routes/daily_sales_routes.py` | P2 Daily Sales Blueprint | route glue / export helpers / daily query and formatting service |
| 1013 | `routes/export_routes.py` | P2 Export flow | export command/router glue / file path / download orchestration |
| 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 |
| 941 | `services/pchome_revenue_growth_service.py` | P2 PChome revenue growth service | growth aggregation / mapping backlog handoff / source adapter 分離 |
| 931 | `services/pchome_crawler.py` | P2 PChome crawler | search fetch / parsing / fallback source handling / rate limit policy |
| 920 | `routes/market_intel_routes.py` | P2 market intel Blueprint | page route / API route glue / MCP gate route registration helper |
| 906 | `services/competitor_match_attempt_rescore_audit.py` | P2 rescore audit service | audit query / matcher replay / summary payload 分離 |
| 895 | `routes/market_intel_review_routes.py` | P2 market intel review route extension | review decision route glue / canonical alias decorators / legacy endpoint compatibility |
| 867 | `services/token_report_service.py` | P2 token report service | query / aggregation / chart payload / notification formatting |
| 864 | `services/ppt_vision_service.py` | P2 PPT vision QA service | runtime state / queue status / model probe / audit execution 分離 |
| 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 |
| 826 | `routes/market_intel_mcp_run_routes.py` | P2 market intel MCP run route extension | route glue / canonical alias decorators / MCP run preview handoff |
| 861 | `routes/market_intel_review_post_routes.py` | P2 market intel review post route extension | review post route glue / canonical alias decorators / AI summary persistence preview handoff |
| 813 | `services/momo_crawler.py` | P2 MOMO crawler | targeted search / browser fallback / parsing 分離 |

### 2026-07-10 Live Addendum

下表是本次完整 review 的機械式行數回讀；同一路徑若也出現在上表，以下表較新的數字為準。
這份更新只修正 inventory truth，不把巨型檔案誤標成已完成重構。

| 行數 | 檔案 | 分類 | 拆分方向 |
|---:|---|---|---|
| 42881 | `services/pchome_mapping_backlog_service.py` | P0 gate 巨型 service、拆分進行中 | policy、AI exception contract、evidence parser、artifact guard、bounded executor、drift verifier、receipt replay、reporter 與 evidence enrichment/source preview 已移到 `services/pchome_mapping_backlog/`；下一步拆 fetch/merge orchestration |
| 14289 | `services/ai_automation_smoke_service.py` | P0 smoke 巨型 service | 拆 family registry、collectors、health projection、metrics adapter |
| 9383 | `routes/openclaw_bot_routes.py` | P0 巨型 Blueprint、拆分進行中 | scheduler hook 已移到 `services/openclaw_bot/scheduled_jobs.py`；下一步拆 report、command |
| 7641 | `routes/ai_routes.py` | P0 巨型 Blueprint | PChome growth、AI automation、recommendation route extension 分離 |
| 5865 | `services/marketplace_product_matcher.py` | P0 matcher 巨型 service | identity、variant、unit、scoring、explanation 分離 |
| 5513 | `services/ppt_generator.py` | P0 報表巨型 service | orchestration、slides、charts、registry 分離 |
| 4158 | `routes/admin_observability_routes.py` | P0 觀測台巨型 Blueprint | query、action、render context 與 route glue 分離 |
| 3763 | `services/competitor_price_feeder.py` | P0 feeder 巨型 service | acquisition、matching、refresh、persistence、receipt 分離 |
| 3322 | `routes/dashboard_routes.py` | P0 Dashboard Blueprint | query、decision projection、review action 分離 |
| 3290 | `routes/sales_routes.py` | P0 Sales Blueprint | chart、query、calendar、export 分離 |
| 3112 | `scheduler.py` | P0 排程總管 | task registry 與 domain jobs 分離 |
| 2961 | `services/openclaw_strategist_service.py` | P1 strategist | prompt、query、report、notification 分離 |
| 2383 | `services/competitor_intel_repository.py` | P1 repository | query、decision envelope、UI projection、cache 分離 |
| 2332 | `services/elephant_alpha_autonomous_engine.py` | P1 engine | trigger、planner、executor、notification 分離 |
| 2166 | `services/nemoton_dispatcher_service.py` | P1 dispatcher | model client、tool parser、decision、delivery 分離 |
| 2011 | `services/external_market_offer_service.py` | P1 market offers | source registry、normalizer、sync、review、readiness 分離 |
| 1917 | `services/market_intel/deployment_readiness.py` | P1 readiness | check registry、runtime probe、projection 分離 |
| 1658 | `routes/market_intel_review_report_routes.py` | P1 review route | report query、export、route glue 分離 |
| 1494 | `routes/vendor_routes.py` | P1 Vendor Blueprint | stockout mutation、email、route glue 分離 |
| 1456 | `services/ollama_service.py` | P1 AI runtime | routing、health、request、fallback 分離 |
| 1417 | `services/telegram_templates.py` | P1 templates | decision、incident、report renderer 分離 |
| 1409 | `services/import_service.py` | P1 import | acquisition、validation、writer、verifier 分離 |
| 1394 | `services/telegram_bot_service.py` | P1 bot | command、formatter、client 分離 |
| 1440 | `run_scheduler.py` | P1 scheduler entry、拆分進行中 | OpenClaw timed-job registry 已外移；下一步拆 task registration 與 runtime startup |
| 1306 | `routes/system_public_routes.py` | P1 public routes | health、metrics、public projection 分離 |
| 1269 | `app.py` | P1 bootstrap、拆分進行中 | web scheduler 相容層已移到 `services/web_scheduler_compat.py`；下一步拆 extension setup |
| 1272 | `services/code_review_pipeline_service.py` | P2 code review | scan、normalize、persist、report 分離 |
| 1366 | `services/pchome_revenue_growth_service.py` | P1 revenue growth | sales query、catalog coverage、metric contract、offer comparison、scoring、projection 分離 |
| 1188 | `services/ppt_auto_generation_service.py` | P2 PPT automation | resolver、queue、generator、catchup 分離 |
| 1121 | `services/pixelrag_crawler_integration_service.py` | P1 PixelRAG | capture routing、manifest、queue、readback 分離 |
| 1023 | `routes/cicd_routes.py` | P2 CI/CD Blueprint | query、deploy action、route glue 分離 |
| 1014 | `services/pchome_crawler.py` | P1 crawler | transport、parser、fallback、rate policy 分離 |
| 1014 | `routes/daily_sales_routes.py` | P2 Daily Sales Blueprint | query、format、export、route glue 分離 |
| 1017 | `routes/export_routes.py` | P2 Export Blueprint | command、path policy、download 分離；string dtype Excel sanitizer 已修正 |
| 989 | `routes/market_intel_routes.py` | P2 Market Intel Blueprint | page、API、MCP registration 分離 |
| 966 | `services/trend_crawler.py` | P2 trend crawler | adapters、parser、persistence 分離 |
| 880 | `services/pchome_growth_same_item_reconciliation.py` | P1 same-item reconciliation | identity policy、exact DB verifier、coverage post-verifier、receipt repository 分離 |
| 942 | `services/learning_pipeline.py` | P2 RAG learning | distill、promotion、persistence、telemetry 分離 |
| 906 | `services/competitor_match_attempt_rescore_audit.py` | P2 rescore audit | query、classifier、projection 分離 |
| 895 | `routes/market_intel_review_routes.py` | P2 review Blueprint | command、query、route glue 分離 |
| 867 | `services/token_report_service.py` | P2 token report | query、aggregate、chart、notify 分離 |
| 864 | `services/ppt_vision_service.py` | P2 vision QA | runtime、queue、probe、audit 分離 |
| 1005 | `services/security_governance_review_service.py` | P1 governance | inventory、controls、runtime receipt、scorecard 分離 |
| 861 | `routes/market_intel_review_post_routes.py` | P2 review POST routes | command handlers 與 verifier 分離 |
| 846 | `services/market_intel/candidate_queue_review_ai_summary_persistence_telegram_dispatch_report_catalog_record_run_receipt.py` | P2 receipt pipeline | AI summary、persistence、delivery、catalog 分離 |
| 843 | `services/pixelrag_vlm_replay_worker_service.py` | P1 VLM worker | route selection、inference、validation、receipt 分離 |
| 826 | `routes/market_intel_mcp_run_routes.py` | P2 MCP route extension | run command 與 receipt query 分離 |
| 813 | `services/momo_crawler.py` | P2 MOMO crawler | transport、parser、normalization 分離 |
| 801 | `services/ai_surface_html_readback_service.py` | P2 UI readback | contract registry、HTML probe、result projection 分離 |

## 市場情報開發前置禁區

- 不得把跨平台活動頁、商品池、比對審核 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、Inline Keyboard builders 與 10 個 timed-job scheduler hook 已搬離巨型 Blueprint，下一步拆 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 行，可從本清單移除並同步更新測試。

### 2026-07-11 自動盤點

- `python3 scripts/ops/report_codebase_modularization_performance.py` 會為 Python 與前端大型資產建立穩定 work item ID、P0/P1、`in_progress/not_started` 狀態與拆分方向。
- `momo-scheduler` 每日 04:15 執行同一盤點，原子寫入 `data/ai_automation/codebase_inventory/latest.json`；失敗只記 degraded receipt，不得阻斷其他排程。
- 本次基線以 production image build context 為準；`.dockerignore` 排除的 `.claude`、data/logs、docs 與 infra sources 不計入 runtime coverage。V10.777 同版 scanner 為 443 個 production Python modules、259,764 行；48 個大模組、33 個大型前端資產、23 個 P0、6/6 runtime controls、program completion 69.1%、runtime closure partial。禁止手動沿用舊的 447-module 基線。
- `services/openclaw_learning_service.py` 已降至 789 行；embedding worker 的唯一 runtime owner 已移到 `momo-scheduler`，因此不再列入大檔債務，但仍需由 production worker/readback 驗證。
