feat: 新增三個促銷活動爬蟲支援（母親節、520情人節、勞動節）

- 新增通用促銷活動爬蟲函式 run_promo_event_task() - 更新 crawler_config_loader.py 新增三個活動配置 - 更新 run_scheduler.py 動態註冊促銷活動爬蟲 - 新增 API 端點 /api/run_promo_event_task - 新增三個前端儀表板路由（/edm/mothers_day, /edm/valentine_520, /edm/labor_day） - 更新所有儀表板頁籤列表 - 新增配置檔案 services/data/crawler_config.json - 新增使用文件 docs/guides/promo_event_crawler_guide.md - 更新 agent_actions.py 允許重試列表
2026-04-28 13:57:44 +08:00
parent 227b114101
commit af260c4a01
8 changed files with 756 additions and 4 deletions
--- a/docs/guides/promo_event_crawler_guide.md
+++ b/docs/guides/promo_event_crawler_guide.md
@@ -0,0 +1,177 @@
+# 促銷活動爬蟲配置指南
+
+## 概述
+
+本系統支援多種促銷活動的爬蟲監控，包括母親節、520情人節、勞動節等季節性活動。爬蟲系統採用通用架構，可輕鬆擴展支援新的活動類型。
+
+## 支援的活動類型
+
+| 活動類型 | page_type | 預設活動名稱 | 配置鍵值 |
+|---------|-----------|-------------|---------|
+| 母親節 | `mothers_day` | 母親節超值限時購 | `mothers_day_2026` |
+| 520情人節 | `valentine_520` | 520情人節限定購物 | `valentine_520_2026` |
+| 勞動節 | `labor_day` | 勞動節購物優惠 | `labor_day_2026` |
+| 1.1狂歡購物節 | `festival` | 1.1狂歡購物節 | `festival_11` |
+
+## 配置步驟
+
+### 1. 編輯配置文件
+
+編輯 `services/data/crawler_config.json`：
+
+```json
+{
+  "crawlers": {
+    "mothers_day_2026": {
+      "enabled": true,
+      "schedule_hours": 4,
+      "lpn_code": "YOUR_LPN_CODE_HERE",
+      "activity_name": "母親節超值限時購",
+      "page_type": "mothers_day",
+      "name": "2026 母親節促銷爬蟲"
+    }
+  }
+}
+```
+
+**重要參數說明：**
+- `enabled`: 設為 `true` 啟用爬蟲
+- `schedule_hours`: 執行頻率（小時）
+- `lpn_code`: MOMO 活動頁面的 LPN 代碼（必填）
+- `activity_name`: 活動名稱（用於通知和日誌）
+- `page_type`: 資料庫區分標識（不可重複）
+
+### 2. 取得 LPN 代碼
+
+LPN 代碼是 MOMO 活動頁面的唯一識別碼，格式如下：
+
+```
+https://www.momoshop.com.tw/edm/cmmedm.jsp?lpn=O1K5FBOqsvN
+                                                    ^^^^^^^^^^^^
+                                                    這就是 LPN 代碼
+```
+
+### 3. 重啟排程服務
+
+修改配置後，需重啟 `momo-scheduler` 容器使配置生效：
+
+```bash
+ssh wooo@192.168.0.110 "ssh ollama@192.168.0.188 \"\
+  cd /home/ollama/momo-pro && docker compose restart momo-scheduler\""
+```
+
+## 手動觸發爬蟲
+
+### 透過 Web API
+
+```bash
+curl -X POST http://localhost:5000/api/run_promo_event_task \
+  -H "Content-Type: application/json" \
+  -d '{
+    "page_type": "mothers_day",
+    "lpn_code": "O1K5FBOqsvN",
+    "activity_name": "母親節超值限時購"
+  }'
+```
+
+### 透過 Python
+
+```python
+import requests
+
+response = requests.post(
+    'http://localhost:5000/api/run_promo_event_task',
+    json={
+        'page_type': 'mothers_day',
+        'lpn_code': 'O1K5FBOqsvN',
+        'activity_name': '母親節超值限時購'
+    }
+)
+print(response.json())
+```
+
+## 資料庫結構
+
+所有促銷活動商品資料儲存在 `promo_products` 表，透過 `page_type` 欄位區分：
+
+```sql
+SELECT * FROM promo_products WHERE page_type = 'mothers_day';
+```
+
+## 爬蟲結構分析
+
+根據市場情報，各活動頁面結構如下：
+
+### 母親節（5月第2週）
+- **活動名稱**: 《愛在五月》母親節超值限時購
+- **主要商品**: OLAY 歐蕾系列、全酵肌泌賦活乳、時尚服飾
+- **活動時間**: 5月第2週
+
+### 520情人節（5/20-21）
+- **活動名稱**: 《你我在一起》情人節限定購物
+- **主要商品**: OLAY 歐蕾系列、OZIO 歐姬兒蜂王乳凝露EX
+- **活動時間**: 5月20日-21日
+
+### 勞動節（5/1-3）
+- **活動名稱**: 《勞動者福利》勞動節購物優惠
+- **主要商品**: OLAY 歐蕾系列、春季保養相關商品
+- **活動時間**: 5月1日-3日
+
+## 爬蟲功能
+
+系統會自動：
+1. 抓取活動頁面所有商品區塊
+2. 解析商品名稱、價格、圖片
+3. 偵測價格變動（漲價/跌價）
+4. 偵測新上架商品
+5. 偵測下架商品
+6. 發送 Telegram/Line 通知（附截圖）
+
+## 故障排除
+
+### 爬蟲未啟動
+檢查配置文件中的 `enabled` 是否為 `true`，且 `lpn_code` 已填寫。
+
+### 未抓取到商品
+1. 檢查 LPN 代碼是否正確
+2. 檢查活動頁面是否已上線
+3. 查看 `logs/system.log` 中的錯誤訊息
+4. 檢查 `logs/debug_htmls/` 中的偵錯截圖
+
+### 排程未執行
+確認 `momo-scheduler` 容器運行狀態：
+
+```bash
+ssh wooo@192.168.0.110 "ssh ollama@192.168.0.188 \"\
+  docker ps --format '{{.Names}} | {{.Status}}' | grep momo-scheduler\""
+```
+
+## 新增活動類型
+
+如需新增其他活動類型：
+
+1. 在 `services/data/crawler_config.json` 新增配置
+2. 在 `run_scheduler.py` 的 `promo_event_configs` 字典中新增對應
+3. 重啟排程服務
+
+範例：
+
+```json
+{
+  "mid_autumn_2026": {
+    "enabled": false,
+    "schedule_hours": 4,
+    "lpn_code": "",
+    "activity_name": "中秋節限定優惠",
+    "page_type": "mid_autumn",
+    "name": "2026 中秋節促銷爬蟲"
+  }
+}
+```
+
+```python
+promo_event_configs = {
+    # ... 現有配置
+    'mid_autumn_2026': {'lpn': '', 'page_type': 'mid_autumn', 'name': '中秋節限定優惠'}
+}
+```