# 程式碼模組化盤點（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-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 追記：同步 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，不變更模組化決策。

## 達到或超過 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 |
| 1936 | `services/nemoton_dispatcher_service.py` | P1 NemoTron service | NIM client / tool-call parser / action dispatcher |
| 2026 | `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 |
| 1124 | `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 |
| 933 | `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 |
| 2323 | `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 |
| 961 | `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 |
| 1042 | `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 分離 |
| 1733 | `services/competitor_price_feeder.py` | P2 competitor price feeder | crawler scheduling / price normalization / retryable candidate recovery / cache strategy |
| 1327 | `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 |
| 833 | `routes/market_intel_routes.py` | P2 market intel Blueprint | page route / API route glue / MCP gate route registration helper |
| 912 | `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 行，可從本清單移除並同步更新測試。