統一全站暖色視覺與市場情報骨架

docs/adr/ADR-035-cross-platform-market-campaign-intelligence.md

@@ -0,0 +1,181 @@
+# ADR-035: 跨平台市場活動情報系統
+
+- **狀態**: Accepted
+- **日期**: 2026-05-06
+- **觸發**: 使用者提出定期掌握 MOMO / 蝦皮 / 酷澎 / PChome 等電商活動檔期、活動商品、競品價格與資料庫保存需求
+- **相關 ADR**: ADR-011（跨專案資源隔離）、ADR-017（模組化收尾路線圖）、ADR-025（市場情報週報）
+- **相關 Memory**: `docs/memory/code_modularization_inventory_20260430.md`
+
+## Context
+
+EwoooC 目前已有 MOMO EDM / 節慶活動資料、`promo_products`、PChome 競品價格 feeder、PPT 市場情報週報與多個分析頁，但跨平台活動情報尚未形成獨立資料模型與可維護爬蟲框架。
+
+若直接把蝦皮、酷澎、PChome 等平台資料塞進既有 `promo_products`、`routes/sales_routes.py`、`scheduler.py` 或分析頁大型 template，會造成下列風險：
+
+1. 不同平台欄位語意不同，舊表無法承載活動檔期、平台商品 ID、折扣券、銷售訊號與價格歷史。
+2. 既有 `scheduler.py`、`routes/sales_routes.py`、`routes/dashboard_routes.py`、多個 crawler service 已達大檔治理門檻，新增功能會加劇技術債。
+3. 新爬蟲若直接上正式排程，可能造成 DB 寫入量、外部平台 rate limit、排程阻塞與告警噪音。
+4. 新市場情報頁若複製既有巨型 Jinja template 模式，會延續 UI token、字體、色彩與點陣風格不一致問題。
+
+## Decision
+
+建立新的 **跨平台市場活動情報系統**，採分階段落地、預設關閉、可獨立回退的方式推進。
+
+### 1. 模組邊界
+
+新功能必須使用獨立模組，不得塞回既有巨檔：
+
+- `services/market_intel/`：活動探索、商品爬取、正規化、商品比對、告警摘要。
+- `services/market_intel/adapters/`：各平台 adapter，例如 MOMO / PChome / Coupang / Shopee。
+- `database/market_intel_models.py`：`market_*` ORM models。
+- `routes/market_intel_routes.py`：市場情報頁面與 API route glue。
+- `templates/market_intel/`：市場情報 UI template。
+- `services/scheduler/` 或獨立 job module：市場情報排程掛載點。
+
+### 2. 資料模型
+
+新增 `market_*` schema 作為唯一主資料層：
+
+- `market_platforms`
+- `market_campaigns`
+- `market_campaign_snapshots`
+- `market_campaign_products`
+- `market_product_price_history`
+- `market_product_matches`
+- `market_crawler_runs`
+
+`promo_products` 只作為既有 MOMO 活動資料的相容來源或雙寫過渡，不再承接跨平台唯一真相。
+
+### 3. Feature Flag 與啟用策略
+
+市場情報第一階段必須預設關閉：
+
+- `MARKET_INTEL_ENABLED=false`
+- `MARKET_INTEL_CRAWLER_ENABLED=false`
+- `MARKET_INTEL_WRITE_ENABLED=false`
+
+初期允許 dry-run：建立 run log、解析活動與商品，但不大量寫入正式商品資料。正式入庫與排程啟用需另行通過 smoke test、rate limit 驗證與 rollback drill。
+
+### 4. 爬蟲安全邊界
+
+市場情報爬蟲只允許抓公開頁面或公開結構化資料，不做登入、不碰會員資料、不破解反爬、不使用帳號池、不繞付費牆。
+
+每平台 adapter 必須具備：
+
+- rate limit
+- timeout
+- retry ceiling
+- user-agent 與來源識別
+- run log
+- error classification
+- dry-run mode
+- 可單平台停用開關
+
+### 5. UI / UX 邊界
+
+市場情報 UI 不複製巨型分析頁模式，必須先抽共用元件與設計 token：
+
+- 活動檔期看板
+- 活動商品池
+- 商品比對審核
+- 市場機會與威脅
+
+所有新頁必須符合 V2 暖紙、暖墨、焦糖 accent、等寬數字、點陣紋理與真實資料規範。未串接資料時只能顯示可診斷空狀態，不得使用假商品或假 KPI。
+
+### 6. 上線與回退
+
+部署遵守 ADR-011：
+
+- 禁止 `docker compose ... --remove-orphans`
+- 禁止影響 `momo-db` 容器生命週期
+- 只用 `docker compose up -d --no-deps --force-recreate <service>` 精準重建
+- health check 只打 `/health`
+
+異常回退順序：
+
+1. 關閉 `MARKET_INTEL_*` feature flags。
+2. 停用市場情報 scheduler job。
+3. 保留 `market_*` 表與 run log，不刪資料。
+4. 回復上一版 route / service 程式碼。
+5. 僅重啟受影響應用容器，不動 DB。
+
+## Phased Rollout
+
+### Phase 0：Readiness Audit
+
+- 更新模組化 inventory。
+- 確認 `scheduler.py` 無 conflict marker 且可 py_compile。
+- 標記市場情報不可寫入的既有大檔。
+- 完成 ADR-035。
+
+### Phase 1：Skeleton Only
+
+- 新增 feature flags。
+- 新增 `market_intel` package skeleton。
+- 新增空 route / disabled page / dry-run service。
+- 不啟用正式排程，不大量入庫。
+
+### Phase 2：DB Schema
+
+- 新增 `market_*` ORM models。
+- 補 metadata import 與 schema smoke。
+- 寫入 crawler run log 與少量 dry-run snapshot。
+
+### Phase 3：MOMO / PChome Adapter
+
+- 先接成本最低且已有脈絡的平台。
+- 只抓公開活動入口與活動商品。
+- 建立活動與商品正規化規則。
+
+### Phase 4：Coupang / Shopee Adapter
+
+- Coupang 先做保守 adapter。
+- Shopee 因動態資料與反爬風險較高，最後做，並維持更嚴格節流。
+
+### Phase 5：Product Matching + HITL
+
+- 用品牌、規格、容量、關鍵字與現有商品資料計算 match score。
+- 低信心進人工審核，不自動合併。
+
+### Phase 6：AI Insight / Telegram
+
+- 只基於 DB 實證資料產生摘要與告警。
+- 不做空泛 LLM 建議。
+- 高風險告警需包含平台、活動、商品、價差、資料時間與可追溯 run id。
+
+## Alternatives Considered
+
+### 方案 A：直接擴充 `promo_products`
+
+不採用。`promo_products` 偏 MOMO 活動商品語境，無法乾淨承載跨平台活動、商品快照、價格歷史、比對審核與 crawler run log。
+
+### 方案 B：直接塞進 `scheduler.py` 與既有 crawler service
+
+不採用。`scheduler.py` 與多個 crawler service 已達大檔治理門檻，新增跨平台 adapter 會讓排程與錯誤隔離更脆弱。
+
+### 方案 C：先做完整 UI 再補資料
+
+不採用。違反真實資料與真實頁面規範，容易產生假 KPI、假商品與不可診斷狀態。
+
+## Consequences
+
+**正面**
+
+- 市場情報可以獨立演進，不污染業績分析、dashboard、scheduler 既有技術債。
+- 每平台 adapter 可單獨停用、測試與回退。
+- `market_*` schema 可保留歷史、做趨勢與商品比對。
+- AI 告警能基於可追溯 DB run log，降低空泛推論。
+
+**負面**
+
+- 初期開發量比「直接塞舊表」更高。
+- 需要新增 schema、service、route、UI 與 scheduler registry。
+- Shopee 等平台可能因公開資料穩定性與 rate limit 需要較長探索期。
+
+## Acceptance Criteria
+
+- Phase 0 完成後，不改 runtime 行為。
+- Phase 1 完成後，`MARKET_INTEL_ENABLED=false` 時所有新功能完全不影響既有頁面與排程。
+- 任一 crawler adapter 失敗不得阻塞既有 MOMO 排程。
+- 新市場情報 route 不新增到 `app.py`。
+- 任一新 Python 檔若超過 600 行需提出拆分理由，超過 800 行需更新模組化 inventory。

docs/adr/README.md

@@ -56,6 +56,7 @@
 | [032](ADR-032-rag-autonomous-learning-loop.md) | RAG 自主學習迴圈 — Distiller + PromotionGate + 反饋環（Phase 11） | Accepted | 2026-05-03 |
 | [033](ADR-033-rag-three-guardrails.md) | RAG 治理三護欄 — Promotion Gate / Firecrawl 資源 / BGE-M3 一致性（Owen v5.0 鐵律） | Accepted | 2026-05-03 |
 | [034](ADR-034-dynamic-model-router.md) | Caller × Context 動態 Model Router（短文 gemma3 / 複雜 SKU qwen3:14b / 重構 coder:32b） | Accepted | 2026-05-04 |
+| [035](ADR-035-cross-platform-market-campaign-intelligence.md) | 跨平台市場活動情報系統 | Accepted | 2026-05-06 |
 
 ## 規範