# 路由模組說明

`app.py` 直接註冊所有 Flask Blueprint；`USE_MODULAR_ROUTES`、`register_blueprints()`、
`MODULAR_ENDPOINTS` 與 duplicate cleanup 開關已在 ADR-017 Phase 3f-1 移除。

## 啟動防線

`app.py` 會在啟動時檢查 `app.url_map`，同一組 `(URL, HTTP methods)` 不允許被兩個 endpoint
重複註冊；若發現衝突會直接 `SystemExit`。

## 模組清單

| 模組 | 說明 | 主要路由 |
|------|------|----------|
| `dashboard_routes.py` | 商品看板首頁 | `/` |
| `sales_routes.py` | 業績分析與 ABC 明細 | `/sales_analysis`, `/growth_analysis`, `/abc_analysis/detail`, `/api/sales_analysis/*` |
| `system_public_routes.py` | 無 prefix 公開系統頁與監控 | `/health`, `/metrics`, `/ai_automation_smoke`, `/api/ai-automation/smoke*`, `/settings`, `/system_settings`, `/logs`, `/api/logs`, `/api/backup` |
| `system_routes.py` | 內部系統維護 API | `/api/system/*` |
| `edm_routes.py` | EDM 與節慶儀表板 | `/edm`, `/festival` |
| `monthly_routes.py` | 月結分析 | `/monthly_summary_analysis`, `/api/monthly_summary_data` |
| `daily_sales_routes.py` | 當日業績 | `/daily_sales`, `/daily_sales/export*` |
| `market_intel_routes.py` | 市場情報 Phase 104 主路由、AI-controlled sample 相容路由與基礎 preview API | `/market_intel`, `/market_intel/*`, `/api/market_intel/status`, `/api/market_intel/schema`, `/api/market_intel/schema_smoke`, `/api/market_intel/schema_db_probe`, `/api/market_intel/platform_seed_db_diff`, `/api/market_intel/legacy_source_bridge`, `/api/market_intel/mcp_readiness`, `/api/market_intel/mcp_tool_contract`, `/api/market_intel/mcp_deploy_preflight`, `/api/market_intel/mcp_activation_runbook`, `/api/market_intel/mcp_fetch_gate`, `/api/market_intel/scheduler_plan`, AI-controlled sample compatibility family, candidate queue writer family, `/api/market_intel/match_review_plan`, `/api/market_intel/opportunity_plan`, `/api/market_intel/opportunity_scoring_plan`, `/api/market_intel/opportunity_evidence_plan`, `/api/market_intel/opportunity_alert_plan`, `/api/market_intel/adapters`, `/api/market_intel/dry_run_plan`, `/api/market_intel/discovery_plan`, `/api/market_intel/candidate_preview`, `/api/market_intel/platform_seed_plan`, `/api/market_intel/platform_seed_write_guard`, `/api/market_intel/platform_seed_writer_plan`, `/api/market_intel/migration_blueprint`, `/api/market_intel/migration_apply_drill`, `/api/market_intel/migration_catalog_review`, `/api/market_intel/migration_live_smoke`, `/api/market_intel/live_db_inventory`, `/api/market_intel/seed_writer_cli_status`, `/api/market_intel/write_approval_runbook`, `/api/market_intel/deployment_readiness` |
| `market_intel_review_routes.py` | 市場情報 AI 例外 queue review 只讀延伸 API | AI-controlled sample compatibility queue review family |
| `market_intel_review_post_routes.py` | 市場情報 review_state closeout 後只讀延伸 API（掛在 `market_intel_review_bp`） | AI-controlled sample compatibility post-closeout / archive / AI summary persistence family |
| `market_intel_review_post_ai_routes.py` | 市場情報 AI summary persistence / Telegram dispatch 後續只讀延伸 API（掛在 `market_intel_review_bp`） | AI summary persistence run / Telegram dispatch compatibility family |
| `market_intel_review_report_routes.py` | 市場情報 report input / report run package / report run readiness / report run receipt / report closeout / report archive / report catalog handoff 後續只讀延伸 API（掛在 `market_intel_review_bp`） | AI summary persistence Telegram report compatibility family |
| `api_routes.py` | 通用任務與查詢 API | `/api/run_task`, `/api/history/*` |
| `ai_routes.py` | AI 推薦、競情儀表板與 PChome 成長作戰 API | `/ai_recommend`, `/ai_intelligence`, `/api/ai/status`, `/api/ai/icaim/dashboard`, `/api/ai/pchome-growth/opportunities`, `/api/ai/pchome-growth/mapping-backlog`, `/api/ai/pchome-growth/mapping-backlog/operator-preview`, `/api/ai/pchome-growth/mapping-backlog/direct-mapping-auto-search-package`, `/api/ai/pchome-growth/mapping-backlog/direct-mapping-candidate-decision-package`, `/api/ai/pchome-growth/ai-automation-readiness`, `/api/ai/pchome-growth/mapping-backlog/evidence-enrichment-preview`, `/api/ai/pchome-growth/mapping-backlog/evidence-source-preview`, `/api/ai/pchome-growth/mapping-backlog/evidence-fetch-gate`, `/api/ai/pchome-growth/mapping-backlog/evidence-merge-preview`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-receipt-gate`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-persistence-gate`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-schema-migration-preview`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-migration-file-preview`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-apply-readiness-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-migration-file-generation-request`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-migration-apply-gate-preview`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-request-gate-preview`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-execution-preflight`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-authorization-package`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-verifier-artifact-preview`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-final-handoff-package`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-shell-preview`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-shell-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-authorization-request-intake`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-authorization-request-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-authorization-lane-guard`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-authorization-decision-preflight`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-authorization-decision-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-authorization-issuer-gate`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-authorization-signing-decision-preflight`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-authorization-signing-decision-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-authorization-signing-issuer-guard`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-authorization-signing-issuer-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-authorization-signing-execution-preflight`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-authorization-signing-execution-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-authorization-signed-receipt-preflight`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-authorization-signed-receipt-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-authorization-signed-receipt-evidence-intake`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-authorization-detached-verification-evidence-validation`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-authorization-verifier-receipt-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-authorization-evidence-execution-preflight`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-authorization-evidence-execution-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-apply-final-preflight`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-package`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-receipt-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-runner-readiness`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-execution-plan-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-command-artifact-closeout`, `/api/ai/pchome-growth/backfill-momo-candidates`, `/api/ai/pchome-growth/source-contract`, `/api/ai/pchome-growth/external-offers/csv-dry-run` |
| `ai_routes.py` | PChome DB apply controlled dry-run 補充索引 | `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-runner-execution-receipt-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-post-receipt-parser-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-no-apply-enforcement-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-final-executor-guard-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-pre-apply-replay-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-apply-executor-readiness-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-invocation-receipt-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-no-write-invocation-package-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-execution-preflight-guard-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-runner-invocation-boundary-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-no-execution-receipt-handoff-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-final-no-runner-execution-proof-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-controlled-executor-quarantine-proof-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-execution-envelope-freeze-proof-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-frozen-envelope-verifier-handoff-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-verifier-invocation-lock-proof-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-verifier-no-execution-receipt-proof-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-verifier-receipt-persistence-guard-proof-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-receipt-persistence-storage-boundary-proof-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-storage-boundary-no-write-ledger-proof-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-no-write-ledger-retention-proof-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-retention-boundary-no-write-archive-proof-closeout`, `/api/ai/pchome-growth/mapping-backlog/auto-policy-db-apply-controlled-dry-run-archive-retention-sealed-handoff-proof-closeout` |
| `export_routes.py` | 匯出功能 | `/api/export/*` |
| `import_routes.py` | 匯入功能 | `/api/import_excel`, `/api/import/monthly_summary` |

新增 route 時請優先放入對應 Blueprint，並用本機 `app.url_map` duplicate check 驗證。
若 route 內開始出現大量資料處理、SQL、AI prompt 或外部 API 呼叫，請依
`docs/guides/modularization_governance.md` 抽到 `services/` 或 `utils/`，不要讓 Blueprint 變成新巨檔。