ewoooc/TODO_NEXT_STEPS.txt

================================================================================
                      AI 自動化閉環治理同步 (2026-04-29) [DONE]
================================================================================

【已完成】
   - ADR-018：四 AI Agent 自動化控制面立案。
   - Memory：新增 `docs/memory/ai_automation_closure_20260429.md`。
   - Guide/Skills 替代：新增 `docs/guides/ai_automation_session_sop.md`。
   - SOT：更新 `docs/AI_INTELLIGENCE_MODULE_SOT.md` 至 V10.11 AI Automation Metrics Scrape 架構。
   - Codex 規則：更新 `AGENTS.md`、`CONSTITUTION.md`、ADR/memory 索引。
   - Prometheus 指標化：新增 EventRouter / AutoHeal / safe action / replay in-process metrics，並接入 `/metrics`。
   - 線上 smoke dashboard：新增 `/ai_automation_smoke` 與 `/api/ai-automation/smoke`，覆蓋 EventRouter、AutoHeal、NemoTron fallback、OpenClaw embedding queue、ElephantAlpha HITL。
   - Smoke 趨勢保存：`/api/ai-automation/smoke` 每次快檢追加 JSONL 精簡紀錄，dashboard 顯示最近趨勢。
   - Smoke 趨勢管理：新增 JSONL 匯出、清理與每日摘要。
   - Smoke 每日摘要：新增 Telegram 手動推播 API 與 momo-scheduler 每日 09:10 排程入口。
   - Grafana 視覺化：新增 `MOMO AI Automation Overview` provisioning dashboard，覆蓋 EventRouter、safe action、replay、AutoHeal 指標。
   - Grafana 線上部署：188 active Grafana 已載入 4 個 dashboard，`MOMO AI Automation Overview` provisioning 成功。
   - Prometheus scrape 修復：active monitoring stack 新增 `momo-app` scrape job，目標 `momo-pro-system:80/metrics`。
   - Gunicorn preload 修復：`post_fork` 略過 Flask/Werkzeug request-bound LocalProxy，避免 worker boot fail。
   - CD 健康檢查強化：改為 internal container health + external `mo.wooo.work` 雙檢查，重試窗延長到約 3 分鐘。
   - CD Sync reload 修復：rsync 後明確 `docker compose restart momo-app scheduler telegram-bot`，避免檔案已同步但 process 仍跑舊版。
   - CD Gunicorn 掛載強化：`momo-app` 明確掛載 `./gunicorn.conf.py:/app/gunicorn.conf.py:ro`，避免重啟後吃到 image 內舊版設定。
   - Metrics schema drift 降噪：`realtime_sales_monthly` 總筆數改用 raw `COUNT(*)`，避免 ORM 欄位 drift 造成 Prometheus scrape warning。
   - CD Rebuild 切換強化：rebuild 模式改為先 `docker compose build --no-cache momo-app` 成功，再 stop/rm/recreate 三應用容器，避免長時間 502。
   - ElephantAlpha NIM fallback 強化：預設改用 production 可呼叫的 `nvidia/llama-3.3-nemotron-super-49b-v1.5`，Ultra 253B 權限 404 時自動 fallback。
   - DatabaseManager 連線池收斂：PostgreSQL 每 worker pool 調整為 `pool_size=2/max_overflow=3`，避免多 route 重複 new manager 時吃滿連線。
   - Ollama embedding 強化：改為優先 `/api/embed`，舊節點才 fallback `/api/embeddings`，並新增 `EMBEDDING_TIMEOUT`。
   - Scheduler 例外記錄強化：清除 `scheduler.py` 靜默 `except/pass`，資源清理、EDM 可選欄位、備份 insight/通知失敗全改為可診斷 log。
   - AI metrics baseline 觀測：`/metrics` 在尚無 AI 自動化事件時仍輸出 `momo_ai_*` zero-baseline series，避免重啟後 Grafana/Prometheus 看不到 metric names。
   - ElephantAlpha transient fallback：NVIDIA NIM timeout、connection error、429 與 5xx 會嘗試下一個 fallback model；400 等非暫時性請求錯誤不重試。
   - 模組化治理守門：新增 `docs/guides/modularization_governance.md`、`docs/memory/code_modularization_inventory_20260430.md` 與 `tests/test_modularization_governance.py`，盤點並鎖住 15 個 >800 行 Python 大檔。
   - Legacy 5888 入口清理：刪除 `tests/main_test.py` standalone Flask 死碼，測試與自動匯入文件改用 Port 80 入口。
   - OpenClaw Bot 第一刀拆分：Telegram API send/retry/file upload helper 已移至 `services/openclaw_bot/telegram_api.py`，避免 Blueprint 持續承接 delivery glue。

【下次待辦】
   - 繼續依 inventory 拆 `routes/openclaw_bot_routes.py`：下一刀優先拆 menu keyboard 或 report formatting。
   - 觀察 Prometheus scrape 後 `momo_ai_*` baseline 與非 baseline 事件序列是否持續穩定。
   - Superset panel 設定與 Smoke 摘要成效觀察。

================================================================================
                      品牌資產最終處理與維護 (Phase 7) [DONE]
================================================================================

26. [已完成] 品牌圖檔格式轉換：
    - 使用 `convert_assets.py` 生成多種格式。
    - 產出格式：TIFF, JPG, EPS, AI (PDF), SVG (x3 款 Logo)。
    - 位置：/Users/ogt/momo_pro_system/export_assets
    - 已部署至伺服器並建立品牌資產庫頁面：https://momo.wooo.work/brand_assets

27. [已完成] 維護頁面文案更新與部署：
    - 文案已更新為：「正在進行系統升級，為了提供更穩定的網站服務，系統正在進行必要的維護與優化，造成不便，敬請見諒」
    - 已同步至 GCP 生產環境。

================================================================================
                      WOOO TECH 公司入口網站 (Phase 8) [NEW PROJECT]
================================================================================

28. [待辦] 公司入口網站開發 (wooo.work)：
    - 將使用 **Flutter Web** 開發。
    - 需在獨立專案中進行（非 momo_pro_system）。
    - 詳細規劃文件：implementation_plan_wooo_website.md

    【網站定位】
    - 新創公司 WOOO TECH 的數位門面
    - 整合各子系統產品的導航與介紹
    - 一級域名：wooo.work
    - 子系統：momo.wooo.work, [未來產品].wooo.work

    【頁面結構】
    - 首頁：Hero Section + 產品卡片
    - 產品介紹頁：各系統功能詳情
    - 公司介紹：願景、使命
    - 聯繫我們：表單或 Email

    【視覺風格】
    - 延續 WOOO 品牌：漸變紫藍 + 深色科技感 + 玻璃質感
    - 動態流暢的互動效果

    【待確認】
    - DNS 託管商 (wooo.work)
    - 公司簡介文案
    - 是否需要多語言支援




【環境區分】

1. 開發/測試環境（本機 VS Code）：
   - 位置：macOS 本機 (/Users/ogt/momo_pro_system)
   - 用途：開發新功能、測試、除錯
   - 啟動方式：`python app.py`
   - 訪問：http://localhost:5000 或 http://127.0.0.1:5000
   - 資料庫：data/momo_database.db (本機 SQLite)

================================================================================
                         完整部署流程 (2026-01-13)
================================================================================

【部署完成狀態】
   ✅ 網站：https://momo.wooo.work
   ✅ 響應時間：1.7-2 秒
   ✅ SSL 有效期：2026-04-13
   ✅ Google Drive 自動匯入：每 30 分鐘
   ✅ 爬蟲任務：每小時執行
   ✅ 自動備份：已配置

================================================================================
                          日常開發工作流程
================================================================================

【本機開發流程】

1. 啟動開發環境：
   cd /Users/ogt/momo_pro_system
   python app.py
   # 訪問：http://localhost:5000

2. 開發新功能：
   - 編輯程式碼
   - 本機測試
   - 確認功能正常

3. 測試資料庫變更：
   - 修改 database/models.py
   - 執行 python init_db.py
   - 驗證資料庫結構

4. 版本控制（如果使用 Git）：
   git add .
   git commit -m "描述變更內容"

【版本同步檢查】

⚠️  重要：每次更新後確認本機和 GCP 版本一致

1. 檢查關鍵文件的修改時間和大小：
   # 本機
   ls -lh /Users/ogt/momo_pro_system/app.py
   ls -lh /Users/ogt/momo_pro_system/dashboard.html

   # GCP
   gcloud compute ssh momo-server --zone=asia-east1-a \
     --command="ls -lh ~/momo_pro_system/app.py ~/momo_pro_system/dashboard.html"

2. 比對檔案 MD5 雜湊值（確保內容完全一致）：
   # 本機
   md5 /Users/ogt/momo_pro_system/app.py

   # GCP
   gcloud compute ssh momo-server --zone=asia-east1-a \
     --command="md5sum ~/momo_pro_system/app.py"

3. 檢查最近更新的文件：
   # 本機（最近 1 天內修改的 Python 和 HTML 文件）
   find /Users/ogt/momo_pro_system -type f \( -name "*.py" -o -name "*.html" \) -mtime -1 -ls

   # GCP
   gcloud compute ssh momo-server --zone=asia-east1-a \
     --command="find ~/momo_pro_system -type f \( -name '*.py' -o -name '*.html' \) -mtime -1 -ls"

4. 版本追蹤建議：
   ✅ 每次更新後記錄更新時間和文件清單
   ✅ 使用 Git 進行版本控制（未來可考慮）
   ✅ 重大更新前先備份 GCP 當前版本
   ✅ 更新後測試關鍵功能確認正常

【常用維護命令】

# 查看服務狀態
gcloud compute ssh momo-server --zone=asia-east1-a \
  --command="sudo systemctl status momo"

# 查看即時日誌
gcloud compute ssh momo-server --zone=asia-east1-a \
  --command="sudo journalctl -u momo -f"

# 重啟服務
gcloud compute ssh momo-server --zone=asia-east1-a \
  --command="sudo systemctl restart momo"

# 停止服務
gcloud compute ssh momo-server --zone=asia-east1-a \
  --command="sudo systemctl stop momo"

# 啟動服務
gcloud compute ssh momo-server --zone=asia-east1-a \
  --command="sudo systemctl start momo"

# 查看 Nginx 狀態
gcloud compute ssh momo-server --zone=asia-east1-a \
  --command="sudo systemctl status nginx"

# 重新載入 Nginx 配置
gcloud compute ssh momo-server --zone=asia-east1-a \
  --command="sudo nginx -t && sudo systemctl reload nginx"

# 檢查 SSL 證書狀態
gcloud compute ssh momo-server --zone=asia-east1-a \
  --command="sudo certbot certificates"

# 手動更新 DuckDNS IP
gcloud compute ssh momo-server --zone=asia-east1-a \
  --command="~/duckdns/duck.sh && cat ~/duckdns/duck.log"

# 查看資源使用狀況
gcloud compute ssh momo-server --zone=asia-east1-a \
  --command="free -h && df -h && top -bn1 | head -n 15"

【維護模式管理】

# 啟用維護模式（顯示維護頁面，停止應用服務）
gcloud compute ssh momo-server --zone=asia-east1-a \
  --command="./enable_maintenance.sh"

# 禁用維護模式（恢復正常服務）
gcloud compute ssh momo-server --zone=asia-east1-a \
  --command="./disable_maintenance.sh"

# 維護模式說明：
# - 維護模式會將網站切換到靜態維護頁面
# - 顯示「系統維護中」訊息和即時時鐘
# - SSL/HTTPS 持續運作
# - 適用於系統更新、資料庫維護等需要暫停服務的場景
# - 維護頁面位置：~/momo_pro_system/maintenance.html

================================================================================
                            系統備份策略
================================================================================

【本機備份】
- 執行：python backup_system.py
- 或在系統設定頁面點擊「系統備份」按鈕
- 位置：backups/ 目錄
- 最新備份：momo_pro_system_backup_20260113_111011_V9.4.zip (261 MB)

【生產環境備份】

✅ 已設置每日自動備份（每天凌晨 2:00）

1. 自動備份配置：
   - 執行時間：每天 02:00（台北時間 10:00）
   - 備份腳本：~/daily_backup.sh
   - 備份位置：~/momo_backups/
   - 保留期限：最近 7 天
   - 備份內容：
     * 資料庫（momo_database.db）
     * 配置文件（config/）
     * Google Drive 憑證
     * 系統配置（Nginx, systemd）
     * DuckDNS 配置
     * 最近 7 天日誌

2. 查看備份狀態：
   gcloud compute ssh momo-server --zone=asia-east1-a \
     --command="ls -lh ~/momo_backups/*.tar.gz | tail -5"

3. 查看備份日誌：
   gcloud compute ssh momo-server --zone=asia-east1-a \
     --command="tail -50 ~/momo_backups/backup.log"

4. 手動執行備份：
   gcloud compute ssh momo-server --zone=asia-east1-a \
     --command="~/daily_backup.sh"

5. 下載備份到本機：
   gcloud compute scp momo-server:~/momo_backups/momo_production_backup_*.tar.gz \
     /Users/ogt/momo_pro_system/backups/ --zone=asia-east1-a

6. 恢復備份：
   # 解壓備份檔
   tar -xzf momo_production_backup_YYYYMMDD_HHMMSS.tar.gz
   # 恢復資料庫
   cp momo_production_backup_*/momo_database.db ~/momo_pro_system/data/
   # 重啟服務
   sudo systemctl restart momo

================================================================================
                           故障排除指南
================================================================================

【問題：網站無法訪問】
1. 檢查服務狀態：
   gcloud compute ssh momo-server --zone=asia-east1-a \
     --command="sudo systemctl status momo nginx"

2. 檢查防火牆：
   gcloud compute firewall-rules list --filter="name:allow-http*"

3. 檢查 DNS 解析：
   nslookup momo.wooo.work

【問題：網站速度慢】
1. 檢查資源使用：
   gcloud compute ssh momo-server --zone=asia-east1-a \
     --command="free -h && df -h && ps aux | grep python"

2. 檢查 Gunicorn workers：
   gcloud compute ssh momo-server --zone=asia-east1-a \
     --command="ps aux | grep gunicorn"

3. 查看應用日誌：
   gcloud compute ssh momo-server --zone=asia-east1-a \
     --command="sudo journalctl -u momo -n 100 --no-pager"

【問題：SSL 證書過期】
1. 檢查證書狀態：
   gcloud compute ssh momo-server --zone=asia-east1-a \
     --command="sudo certbot certificates"

2. 手動續期：
   gcloud compute ssh momo-server --zone=asia-east1-a \
     --command="sudo certbot renew"

【問題：Google Drive 自動匯入失敗】
1. 檢查日誌：
   gcloud compute ssh momo-server --zone=asia-east1-a \
     --command="sudo journalctl -u momo | grep -i 'google drive' | tail -n 20"

2. 檢查憑證檔案：
   gcloud compute ssh momo-server --zone=asia-east1-a \
     --command="ls -lh ~/momo_pro_system/config/google_*.{json,pickle}"

3. 手動測試：
   gcloud compute ssh momo-server --zone=asia-east1-a
   cd ~/momo_pro_system
   source venv/bin/activate
   python -c "from services.google_drive_service import GoogleDriveService; g=GoogleDriveService(); print(g.list_files())"

【問題：504 Gateway Timeout】
原因：某些頁面（如 sales_analysis）需要處理大量數據（31 萬+ 筆記錄），
      超過 Nginx 預設的 60 秒 timeout。

解決方案（已修復 2026-01-13）：
1. 增加 Nginx proxy timeout 到 300 秒：
   - proxy_read_timeout 300s;
   - proxy_connect_timeout 300s;
   - proxy_send_timeout 300s;

2. 如需調整 timeout，編輯 Nginx 配置：
   gcloud compute ssh momo-server --zone=asia-east1-a
   sudo nano /etc/nginx/sites-available/momo
   # 修改 location / { 區塊內的 proxy_*_timeout 值
   sudo nginx -t && sudo systemctl reload nginx

3. 如問題持續，考慮：
   - 查詢優化（已添加 11 個索引）
   - 增加 Gunicorn timeout（目前 120 秒）
   - 實作分頁或快取機制
   - 升級 VM 規格（✅ 已升級：e2-standard-2, 8GB RAM）

效能優化歷程：
   - 2026-01-13: Nginx timeout 增加到 300 秒
   - 2026-01-13: VM 記憶體從 4GB 升級到 8GB（解決 OOM 問題）
   - 記憶體使用率：從 94% 降至 7.5%，可用記憶體 6.9GB

【VM 規格升級方法】
如需再次升級 VM 規格：
1. 停止實例：gcloud compute instances stop momo-server --zone=asia-east1-a
2. 更改類型：gcloud compute instances set-machine-type momo-server --machine-type=e2-standard-4 --zone=asia-east1-a
3. 啟動實例：gcloud compute instances start momo-server --zone=asia-east1-a
4. 驗證升級：gcloud compute ssh momo-server --zone=asia-east1-a --command="free -h"

可用機器類型：
- e2-standard-2: 2 vCPU, 8GB RAM (當前)
- e2-standard-4: 4 vCPU, 16GB RAM
- e2-standard-8: 8 vCPU, 32GB RAM

================================================================================
                            重要檔案位置
================================================================================

【本機環境】
- 專案根目錄：/Users/ogt/momo_pro_system/
- 資料庫：data/momo_database.db
- 配置檔：config.py, .env
- Google Drive：config/google_credentials.json, config/google_token.pickle
- 備份目錄：backups/
- 日誌目錄：logs/

【生產環境 (VM)】
- 專案目錄：/home/ogt/momo_pro_system/
- 虛擬環境：/home/ogt/momo_pro_system/venv/
- 資料庫：/home/ogt/momo_pro_system/data/momo_database.db
- 配置檔：/home/ogt/momo_pro_system/.env
- Systemd 服務：/etc/systemd/system/momo.service
- Nginx 配置：/etc/nginx/sites-available/momo
- SSL 證書：/etc/letsencrypt/live/momo.wooo.work/
- DuckDNS 腳本：/home/ogt/duckdns/duck.sh
- Gunicorn 日誌：
  - Access: /home/ogt/momo_pro_system/logs/gunicorn-access.log
  - Error: /home/ogt/momo_pro_system/logs/gunicorn-error.log
- 系統日誌：sudo journalctl -u momo

================================================================================
                      系統重啟後待辦事項清單
================================================================================

【本機開發環境重啟】

1. 啟動系統：
   cd /Users/ogt/momo_pro_system
   python app.py

2. 驗證匯入功能 (關鍵)：
   - 進入「系統設定」頁面，匯入 Excel 報表。
   - 觀察終端機日誌，確認出現「自動去重」或「已建立新資料表」的訊息。
   - 若重複匯入相同檔案，應顯示「發現 X 筆重複資料，已忽略」。

3. 檢查資料顯示：
   - 進入「業績分析」頁面 (/sales_analysis)。
   - 確認 '狀態' 欄位是否正確顯示 'F' (目前系統處於原始匯入模式，未執行強制轉 0)。

4. 決定清理策略：
   - 目前 app.py 中的「智慧資料清理」邏輯已被註解掉 (約第 1160 行)。
   - 若確認資料無誤且不需要自動轉型，可維持現狀。
   - 若需要恢復清理功能，請取消註解並重啟 app.py。

5. 系統備份：
   - 確認一切正常後，點擊「系統備份」按鈕或執行 `python backup_system.py`。

【進階報表與策略分析規劃 (Phase 2)】

6. [已完成] 營運成長報表 (Growth Strategy):
   - 建立獨立頁面 `growth_analysis.html`。
   - 實作 MoM (月增率) / YoY (年增率) 雙軸趨勢圖。
   - 實作 YTD (年初至今) 累計達成率。
   - 實作 客單價 (AOV) 趨勢分析。

7. [已完成] BCG 矩陣分析 (波士頓矩陣):
   - 已在業績分析頁加入散佈圖，並自動計算中位數劃分四象限。
   - 視覺化顯示：明星(黃)、金牛(綠)、問題(藍)、瘦狗(灰)。

8. [已完成] ABC 分析 (帕累托法則):
   - 已實作 A/B/C 類商品佔比計算與視覺化。
   - 已加入 Excel 匯出功能，包含 ABC 分類欄位。

9. [已完成] 廠商獲利能力排行:
   - 已在業績分析頁新增廠商排行表格。
   - 顯示總業績、毛利額、毛利率、SKU 數與平均單品產值。

10. [已完成] 淡旺季熱力圖:
    - 已實作 Month x Category 熱力圖。
    - 透過氣泡大小與顏色深淺，視覺化呈現各分類在不同月份的業績表現。

【系統優化與維護 (Phase 3)】

11. [已完成] 業績分析頁面效能優化:
    - 實作 Server-side AJAX 載入列表資料，解決頁面卡頓問題。
    - 優化篩選邏輯與快取機制。

12. [已完成] 淡旺季熱力圖匯出:
    - 實作點擊氣泡匯出該月份分類明細的功能。

13. [已完成] 廠商排行與詳細列表優化:
    - 廠商排行：新增佔比、銷量、ASP 欄位，並優化版面高度。
    - 詳細列表：改為多維度聚合 (商品+品牌+廠商+分類)，新增品牌、均價、退貨率欄位。

14. [已完成] ABC 分析列表增加商品ID欄位:
    - 在 ABC 詳細報表頁面與匯出 Excel 中增加「商品ID」欄位。

【待辦功能與驗證 (Phase 4)】

15. [待辦] 廠商排行互動優化:
    - 實作點擊廠商名稱，自動跳轉並篩選該廠商的所有商品。

16. [待辦] 商品看板庫存顯示:
    - 研究是否能從爬蟲抓取一般商品的庫存量 (目前僅 EDM/Festival 有抓取)。
    - 若可行，在商品看板列表加入庫存欄位。

17. [已完成] 當日業績看板 (Daily Sales Dashboard):
    【功能目標】
    - ✅ 建立新頁面 `/daily_sales`，用於每日業績快照的分析與追蹤。

    【資料表設計】
    - ✅ 新建資料表 `daily_sales_snapshot`。
    - ✅ 欄位結構與 `realtime_sales_monthly` 相同，並額外增加 `snapshot_date` (日期) 欄位。
    - ✅ 實作自動去重機制，避免重複匯入相同日期的資料。

    【Excel 匯入功能】
    - ✅ 提供 Excel 上傳功能，欄位對應 `realtime_sales_monthly` 結構。
    - ✅ 智慧匯入：從 Excel 的「日期」欄位自動拆分 snapshot_date（支援單檔多日）。
    - ✅ 匯入後自動記錄快照日期，保留歷史記錄供比較分析。

    【KPI 卡片顯示】
    - ✅ 6 個核心指標卡片，每個指標計算 DoD% 和 WoW%：
      1. 總業績 (DoD%, WoW%)
      2. 總成本 (DoD%, WoW%)
      3. 毛利 (DoD%, WoW%)
      4. SKU 數 (DoD%, WoW%)
      5. 客單價 (DoD%, WoW%)
      6. 總銷量 (DoD%, WoW%)
    - ✅ KPI 卡片文字對比度優化（白色文字 + 陰影）

    【分析圖表】
    - ✅ 每日業績趨勢圖（混合圖表：柱狀 + 折線）
    - ✅ DoD 成長率圖（條件著色）
    - ✅ WoW 成長率圖（前 7 天灰色 + 第 8 天起彩色 + 說明工具提示）
    - ✅ 商品 Top 10 排行（橫向柱狀圖）

    【業績行事曆視圖】（全新功能）
    - ✅ 完整月份行事曆，顯示每日業績、毛利、SKU、客單價、銷量
    - ✅ 星期標註（週一～週日）
    - ✅ 2026 年台灣國定假日標註（根據人事行政總處公佈）
    - ✅ DoD 顏色系統：紅色 = 正成長，綠色 = 負成長
    - ✅ DoD 百分比標籤顯示（右上角）
    - ✅ 行事曆文字對比度優化（彩色背景上的白色文字 + 陰影）
    - ✅ 點擊日期切換查看詳細業績
    - ✅ 月份切換按鈕（上個月/下個月）

    【詳細列表】
    - ✅ 顯示當日各分類的業績明細（分類層級聚合）
    - ✅ 支援 DataTables 排序、搜尋、分頁功能

    【日期選擇功能】
    - ✅ 下拉選單顯示所有可用日期
    - ✅ 切換日期時，KPI、圖表、列表同步更新
    - ✅ 行事曆與日期選擇器連動

    【UI/UX 優化】（2026-01-12 完成）
    - ✅ 行事曆視覺優化：移除彩色背景，改用白底黑字 + DoD 徽章（上漲紅色、下跌綠色）
    - ✅ 金額格式改為完整顯示（千分位）：$123,456 取代 $123K
    - ✅ 移除行事曆日期格中的重複星期顯示（標題列已有星期標註）
    - ✅ 國定假日標籤改為日期右側顯示（inline layout）
    - ✅ 響應式設計優化：
      • 手機版採用橫向滾動（min-width: 700px）
      • KPI 標籤改用 emoji 圖示（💰業績、📊毛利、📦SKU、🛒客單、📈銷量）
      • 平板與手機適配字體大小與間距
      • 新增滾動提示訊息

    【多維度分析強化】（2026-01-12 完成）
    - ✅ 每日趨勢圖：多 Y 軸顯示（業績/毛利、客單價、銷量）
    - ✅ DoD 圖表：4 條線（業績、毛利、客單價、銷量）
    - ✅ WoW 圖表：4 條線 + 前 7 天灰色顯示 + 工具提示說明
    - ✅ 行事曆每格顯示 5 項指標（業績、毛利、SKU、客單價、銷量）
    - ✅ 毛利計算修正：自動計算 (revenue - cost)

    【廠商維度增強】（2026-01-12 完成）
    - ✅ Top 10 商品：顯示格式改為「商品名稱 (廠商名稱)」
    - ✅ 分類業績明細：新增廠商欄位，顯示廠商名稱（非 ID）
    - ✅ 欄位優先順序修正：['廠商名稱', '廠商', 'Vendor', 'Supplier']

    【系統配置更新】（2026-01-12 完成）
    - ✅ 服務端口從 5888 改為 80
    - ✅ 資料庫路徑確認：data/momo_database.db

    【已完成測試】
    - ✅ 行事曆顯示 5 項指標（完整金額 + 千分位）
    - ✅ 2026 年國定假日正確標註
    - ✅ DoD 徽章顏色系統（紅色上漲、綠色下跌）
    - ✅ WoW 圖表灰色線條邏輯（前 7 天無對比資料）
    - ✅ 行事曆文字清晰可讀（白底黑字 + DoD 徽章）
    - ✅ 月份切換功能
    - ✅ 日期選擇功能
    - ✅ 手機版橫向滾動（行事曆、分類列表、Top 10 圖表）
    - ✅ 廠商名稱顯示（Top 10 + 分類明細）
    - ✅ 手機版 KPI 文字可見性優化（行事曆標籤由灰色改為深色）
    - ✅ 毛利率百分比顯示（顯示於毛利金額右側）
    - ✅ DoD/WoW 徽章對比度優化（改用深色背景白色文字）
    - ✅ 分類業績明細表格手機版滾動（min-width: 800px）
    - ✅ Top 10 商品圖表手機版滾動（min-width: 400-500px）

    【修正的檔案】
    - app.py (第 3376-3450 行)：多維度圖表數據準備（DoD/WoW 計算、毛利計算、廠商維度）
    - app.py (第 3416, 3459 行)：廠商欄位優先順序修正
    - app.py (第 3456-3492 行)：台灣國定假日資料
    - app.py (第 3548-3628 行)：行事曆數據計算（客單價、銷量、毛利）
    - app.py (第 3752-3791 行)：行事曆數據準備函式（margin_rate 計算）
    - app.py (多處)：服務端口從 5888 改為 80
    - daily_sales.html (第 42-287 行)：CSS 樣式重構（白底黑字、DoD 徽章、響應式設計）
    - daily_sales.html (第 106-114 行)：Top 10 圖表響應式滾動容器樣式
    - daily_sales.html (第 177-200 行)：行事曆 HTML（5 項指標完整顯示）
    - daily_sales.html (第 227-242 行)：行事曆 KPI 文字顏色與毛利率樣式
    - daily_sales.html (第 260-262, 277-279 行)：手機版 Top 10 圖表最小寬度設定
    - daily_sales.html (第 387 行)：毛利率百分比顯示（inline 於毛利右側）
    - daily_sales.html (第 408-521 行)：DoD/WoW 徽章改用深色背景
    - daily_sales.html (第 580-588 行)：Top 10 圖表容器結構（加入滾動提示與響應式容器）
    - daily_sales.html (第 605-640 行)：分類列表表格響應式容器（加入滾動提示）
    - daily_sales.html (第 644-896 行)：Chart.js 多維度圖表配置

【系統架構優化與重構 (Phase 5)】

18. [已完成] 商品看板視覺優化 (V9.2)：
    【爬蟲效能優化】（2026-01-12 完成）
    - ✅ 商品圖爬取改用 i_code 直接構造 CDN URL
    - ✅ 格式：https://m.momoshop.com.tw/moscdn/goods/{i_code}_m.webp
    - ✅ 移除複雜 DOM 查詢（8+ CSS 選擇器），速度提升 20-30%
    - ✅ 提高圖片載入準確性與穩定性

    【UI/UX 全面升級】（2026-01-12 完成）
    - ✅ 統一紫色主題風格（#667eea, #764ba2）與 Daily Sales 一致
    - ✅ 現代化漸變效果（卡片、按鈕、表頭）
    - ✅ 商品卡片懸停動效（陰影、縮放）
    - ✅ 表格樣式優化（漸變表頭、hover 效果）
    - ✅ 商品圖片懸停效果（放大、邊框、陰影）
    - ✅ 分頁按鈕圓角與漸變設計

    【版面與排版修正】（2026-01-12 完成）
    - ✅ 修正按鈕群組排版（全部、新上架、漲價、跌價、下架）
    - ✅ 修正表格文字可見性（tbody 文字顏色 #2c3e50）
    - ✅ 修正商品列表標題區塊（增加 card-body 包裹）
    - ✅ 商品 ID 字體放大至 0.875rem（原 small class）
    - ✅ 商品 ID 改用紫色主題色（#667eea）

    【互動體驗增強】（2026-01-12 完成）
    - ✅ 價格顯示 hover 效果（背景漸變、放大、陰影）
    - ✅ 複製品號視覺回饋優化（✅ emoji + 縮放動畫）
    - ✅ 歷史圖表 Modal 視覺升級（漸變標題、圓角、陰影）
    - ✅ 圖表優化：漸變填充、平滑曲線、動態點樣式
    - ✅ Tooltip 優化：emoji 圖示、深色背景、紫色邊框
    - ✅ 圖表動畫：1 秒平滑動畫（easeInOutQuart）

    【修正的檔案】
    - scheduler.py (第 228-244 行)：商品圖 URL 構造邏輯
    - app.py (第 88 行)：版本號更新至 V9.2
    - dashboard.html (第 166-331 行)：完整 CSS 重構
    - dashboard.html (第 462-500 行)：商品列表標題區塊結構調整
    - dashboard.html (第 548-550 行)：商品 ID 樣式修正
    - dashboard.html (第 582-587 行)：價格顯示互動效果
    - dashboard.html (第 730-813 行)：圖表漸變與動畫配置
    - dashboard.html (第 777-789 行)：複製回饋動畫

19. [已完成] 商品看板 KPI 卡片重構與新增指標 (V9.3)：
    【需求整合】（2026-01-12 完成）
    - ✅ 將原有 4 張 KPI 卡片整合為 2 張卡片
    - ✅ 新增 7 個關鍵業務指標
    - ✅ 優化視覺層次與資訊密度
    - ✅ 提升使用者體驗與數據可讀性

    【卡片 1：商品監控概況】（2026-01-12 完成）
    - ✅ 監控商品總數（千分位格式化）
    - ✅ 今日新增商品數
    - ✅ 週增長（過去 7 天新增商品數）
    - ✅ 價格穩定商品數（7 天內無變價）

    【卡片 2：今日價格動態】（2026-01-12 完成）
    - ✅ 上排：漲價 / 降價 / 下架（3 個主要變動指標）
    - ✅ 中排：平均漲幅 / 平均跌幅 / 活躍度（價格分析）
    - ✅ 下排：最活躍分類 / 最大變動（關鍵商業指標）

    【新增 KPI 指標】（2026-01-12 完成）
    - ✅ 平均漲幅：漲價商品平均價格變動
    - ✅ 平均跌幅：降價商品平均價格變動
    - ✅ 今日活躍度：有價格變動的商品百分比
    - ✅ 週增長：過去 7 天新增商品數
    - ✅ 價格穩定商品數：7 天內價格無變化的商品數
    - ✅ 最活躍分類：今日變動商品數最多的分類
    - ✅ 最大變動：單一商品最大價格變動（含商品名稱）

    【後端數據計算】（2026-01-12 完成）
    - ✅ 平均漲跌幅計算邏輯（sum / count）
    - ✅ 活躍度百分比計算（變動商品 / 總商品 * 100）
    - ✅ 最大變動商品查找（絕對值比較）
    - ✅ 週增長查詢（7 天內 min(timestamp) 的商品數）
    - ✅ 價格穩定商品統計（7 天內 distinct(price) == 1）
    - ✅ 最活躍分類統計（category_activity 字典統計）

    【前端視覺優化】（2026-01-12 完成）
    - ✅ 新增 .kpi-grid CSS 樣式（3 欄網格佈局）
    - ✅ 新增 .kpi-item 樣式（漸變背景、hover 效果）
    - ✅ 顏色區分：increase (紅色) / decrease (綠色) / neutral (灰色)
    - ✅ 響應式設計：手機版改為單欄佈局
    - ✅ 卡片 1 藍色漸變背景（與 Daily Sales 風格一致）
    - ✅ 卡片 2 白色背景 + 網格佈局（清晰易讀）

    【修正的檔案】
    - app.py (第 494-554 行)：新增 KPI 計算邏輯
    - app.py (第 659-692 行)：render_template 傳遞新 KPI 數據
    - app.py (第 88 行)：版本號更新至 V9.3
    - dashboard.html (第 369-421 行)：新增 KPI 網格樣式
    - dashboard.html (第 440-448 行)：響應式設計更新
    - dashboard.html (第 477-585 行)：完整 2 張卡片 HTML 結構

20. [待辦] 爬蟲邏輯統一與效能優化 (Scheduler):
    - 將 run_momo_task 的優化邏輯 (批次寫入、無例外查找) 套用到 run_edm_task 與 run_festival_task。
    - 提升 EDM 與購物節爬蟲的穩定性與速度。

21. [待辦] 首頁 (Dashboard) 效能優化:
    - 對 get_consolidated_data 實作短時間快取 (5-10分鐘)，減少資料庫全表掃描。
    - 評估改用 SQL 分頁取代記憶體分頁。

22. [待辦] 程式碼重構與模組化:
    - 將 app.py 的路由拆分為 Blueprints (dashboard, analysis, api)。
    - 將資料處理邏輯移至 services 層。

23. [待辦] 清理冗餘程式碼:
    - 移除 database/manager.py 中不再使用的 update_data 函式。

【系統安全強化 (Phase 6) - URGENT】

=== 重大安全風險 (Critical - 須立即修復) ===

24. [CRITICAL] 移除硬編碼敏感資訊:
    - 檔案: config.py (第 17, 22, 26, 35, 40, 173 行)
    - 問題: 所有 API 金鑰、密碼、Token 直接寫在程式碼中
      • LOGIN_PASSWORD = "0936223270"
      • TELEGRAM_BOT_TOKEN = "8075645931:AAH-EGKMo8ZC4QJs-Nc1_0s92xHrGdQvdpg"
      • LINE_CHANNEL_ACCESS_TOKEN = "nD6MSXjB2FyB111zpT6Yik5B275mi6olHjjf94VnqN..."
      • EMAIL_HOST_PASSWORD = "jopokbhdpnnborjd"
      • NGROK_AUTH_TOKEN = "36e27NM5V7sUJ8QxJIAAWCp7sUv_3brtcrBarYvcP3SbvFKhF"
    - 風險: 任何有權限看到程式碼的人都能取得所有帳密，可接管系統
    - 修復:
      1. 安裝 python-dotenv: pip install python-dotenv
      2. 建立 .env 檔案存放所有敏感資訊
      3. 將 .env 加入 .gitignore
      4. 更新 config.py 改用 os.getenv() 讀取環境變數
      5. **立即更換所有已外洩的密碼與 Token**

25. [CRITICAL] 修復 SQL Injection 漏洞 #1:
    - 檔案: app.py (第 2539, 3469 行)
    - 問題: 使用字串插值直接組合 SQL 查詢
      • df_existing = pd.read_sql(f"SELECT * FROM {table_name}", engine)
      • df = pd.read_sql(f"SELECT {', '.join(req_cols)} FROM {table_name}", db.engine)
    - 風險: 攻擊者可透過惡意表格名稱執行任意 SQL 命令，竊取或刪除資料
    - 修復: 使用參數化查詢，或建立白名單驗證表格/欄位名稱

26. [CRITICAL] 修復 SQL Injection 漏洞 #2:
    - 檔案: database/manager.py (第 43, 52, 57 行)
    - 問題: ALTER TABLE 語句使用字串插值組合 SQL
      • session.execute(text(f"ALTER TABLE products ADD COLUMN updated_at TIMESTAMP DEFAULT '{now_str}'"))
    - 風險: 若 now_str 包含單引號可導致 SQL injection
    - 修復: 使用 SQLAlchemy 的 literal() 或驗證輸入格式

=== 高風險漏洞 (High - 本週內修復) ===

27. [HIGH] 強化登入驗證機制:
    - 檔案: auth.py (第 30-41 行)
    - 問題:
      • 明文密碼比對 (input_password == LOGIN_PASSWORD)
      • 無登入失敗次數限制
      • 無帳號鎖定機制
      • 使用簡單電話號碼作為密碼
    - 風險: 易遭受暴力破解攻擊
    - 修復:
      1. 使用 werkzeug.security 的 generate_password_hash / check_password_hash
      2. 實作登入失敗計數 (IP-based)
      3. 5 次失敗後鎖定 5 分鐘
      4. 要求更換為強密碼 (8+ 字元，含英數符號)

28. [HIGH] 加入 CSRF 防護:
    - 檔案: app.py (多處 POST 路由)
    - 問題: 所有 POST/PUT/DELETE 端點皆無 CSRF Token 驗證
    - 風險: 攻擊者可偽造請求執行未授權操作 (如刪除資料、修改設定)
    - 修復:
      1. 安裝 Flask-WTF: pip install Flask-WTF
      2. 在 app.py 設定 app.config['WTF_CSRF_ENABLED'] = True
      3. 在所有表單加入 {{ csrf_token() }}
      4. 為 AJAX 請求設定 X-CSRFToken header

29. [HIGH] 修復路徑遍歷漏洞:
    - 檔案: app.py (第 2069-2070 行)
    - 問題: 未驗證檔案路徑是否超出允許目錄
      • potential_path = os.path.join(BASE_DIR, 'web/static/screenshots', filename)
    - 風險: 攻擊者可使用 ../../../etc/passwd 存取系統檔案
    - 修復: 使用 pathlib.Path.resolve() 確保路徑在合法目錄內

30. [HIGH] 檔案上傳驗證:
    - 檔案: app.py (第 2406-2422 行)
    - 問題: 上傳 Excel 檔案無驗證
      • 未檢查副檔名
      • 未檢查檔案大小
      • 未驗證 MIME type
    - 風險: 可上傳惡意檔案 (如 webshell, 病毒)，或透過大檔案導致 DoS
    - 修復:
      1. 白名單副檔名: ['xlsx', 'xls', 'csv']
      2. 限制檔案大小: 10MB
      3. 使用 werkzeug.utils.secure_filename() 清理檔名
      4. 驗證 MIME type

=== 中風險漏洞 (Medium - 本月內修復) ===

31. [MEDIUM] 缺少 HTTP 安全標頭:
    - 檔案: app.py (全域)
    - 問題: 未設定安全相關 HTTP headers
    - 風險: 易受 XSS、點擊劫持、MIME type sniffing 攻擊
    - 修復: 在 @app.after_request 加入以下 headers:
      • X-Content-Type-Options: nosniff
      • X-Frame-Options: DENY
      • X-XSS-Protection: 1; mode=block
      • Strict-Transport-Security: max-age=31536000
      • Content-Security-Policy: default-src 'self'

32. [MEDIUM] Session 安全性不足:
    - 檔案: auth.py (第 34 行)
    - 問題: Session cookie 設定不安全
    - 風險: Session 易被劫持或遭 CSRF 攻擊
    - 修復: 在 app.py 設定:
      • app.config['SESSION_COOKIE_SECURE'] = True  # HTTPS only
      • app.config['SESSION_COOKIE_HTTPONLY'] = True  # 防 XSS
      • app.config['SESSION_COOKIE_SAMESITE'] = 'Lax'  # 防 CSRF
      • app.config['PERMANENT_SESSION_LIFETIME'] = timedelta(hours=2)

33. [MEDIUM] 弱亂數產生器:
    - 檔案: app.py (第 720 行)
    - 問題: 使用時間戳生成 ID
      • new_id = int(time.time() * 1000)
    - 風險: ID 可預測，攻擊者可猜測其他資源 ID
    - 修復: 使用 secrets.randbits(64) 產生密碼學安全的隨機數

34. [MEDIUM] 敏感資訊洩漏:
    - 檔案: 多個日誌輸出
    - 問題: 日誌可能記錄敏感資料 (密碼、Token、個資)
    - 風險: 日誌檔若外洩會暴露機密資訊
    - 修復:
      1. 檢視所有 log.info / log.debug 輸出
      2. 實作密碼遮罩函式 (顯示前 2 後 2 碼，中間用 * 遮蔽)
      3. 避免記錄完整 Token 或信用卡資訊

35. [MEDIUM] SSRF / Open Redirect 風險:
    - 檔案: app.py (第 756-778 行)
    - 問題: 未驗證外部 URL 就發送請求
      • response = requests.get(url, headers=headers, timeout=10)
    - 風險: 攻擊者可探測內網服務或發動 SSRF 攻擊
    - 修復:
      1. 建立 URL 白名單或黑名單
      2. 禁止存取私有 IP (127.0.0.1, 10.0.0.0/8, 192.168.0.0/16)
      3. 使用 urllib.parse 驗證 URL 格式

36. [MEDIUM] 資源耗盡風險:
    - 檔案: app.py (多處查詢)
    - 問題:
      • 查詢結果無分頁限制
      • 無請求速率限制
      • 檔案上傳無大小限制
    - 風險: 攻擊者可發送大量請求或上傳大檔案導致服務中斷
    - 修復:
      1. 安裝 Flask-Limiter: pip install Flask-Limiter
      2. 設定 API 速率限制 (如 100 requests/min)
      3. 設定 app.config['MAX_CONTENT_LENGTH'] = 10 * 1024 * 1024  # 10MB
      4. 資料庫查詢加入 LIMIT 與分頁

37. [MEDIUM] 缺少授權檢查:
    - 檔案: app.py (多個路由)
    - 問題: 部分路由未加 @login_required 裝飾器
    - 風險: 未登入使用者可存取受保護功能
    - 修復: 檢視所有路由，確保需要登入的端點都有 @login_required

=== 後續安全維護建議 ===

38. [建議] 定期安全掃描:
    - 使用工具定期檢測漏洞:
      • bandit (Python 程式碼安全掃描): pip install bandit && bandit -r .
      • pip-audit (依賴套件漏洞掃描): pip install pip-audit && pip-audit
      • semgrep (進階程式碼分析): https://semgrep.dev/
    - 建議每月執行一次，或於部署前執行

39. [建議] 建立安全開發規範:
    - 制定 secure coding guidelines 文件
    - Code review 時檢查安全性
    - 使用 pre-commit hooks 執行安全掃描
    - 定期更新依賴套件至最新版本

40. [建議] 備份與災難復原計畫:
    - 確保資料庫定期備份
    - 建立系統還原 SOP
    - 測試備份還原流程
    - 考慮實作異地備份

================================================================================
                    【業績分析儀表板邏輯定義 (2026-01-15 修復確認)】
================================================================================
所有後續開發與維護，必須嚴格遵守以下邏輯與定義：

1. 數據聚合維度 (Aggregation Granularity):
   - Dashboard Top 3 卡片: 
     * 聚合鍵: `[商品ID, 商品名稱]` (不可僅用名稱，避免同名不同規商品混淆)。
     * 顯示名稱: 僅顯示 `商品名稱` (前端截斷)。
     * 目的: 確保卡片數值與詳細列表中的單品數值完全一致。
   - 詳細列表 (Modal): 
     * 聚合鍵: `[商品ID, 商品名稱, 品牌, 廠商名稱, 商品館(分類)]`。
     * 目的: 提供最完整的商品細節。

2. 利潤計算邏輯 (Profit Logic):
   - 通用公式: 
     * 若資料源存在「利潤」欄位 (`col_profit`): 優先使用 `SUM(col_profit)`。
     * 若無: 使用 `SUM(總業績) - SUM(總成本)`。
   - 應用範圍: 
     * 所有 KPI 卡片 (利潤、毛利率)。
     * 所有圖表 (BCG 矩陣)。
     * 詳細列表 SQL 查詢。
     * Excel 匯出功能。

3. 欄位映射與動態性 (Dynamic Column Mapping):
   - 機制: 必須優先從 `_SALES_PROCESSED_CACHE` 讀取 `cols_map`。
   - 禁止行為: 嚴禁在 SQL 查詢中硬編碼中文欄位名稱 (如 "商品館", "品牌", "總業績")。
   - 變數使用: 必須使用變數 (如 `col_category`, `col_amount`) 構建 SQL。

4. 篩選連動性 (Filter Consistency):
   - 全域連動: 任何全域篩選條件 (日期、分類、品牌、廠商、價格區間、毛利區間、關鍵字) 必須同時作用於：
     * 主畫面所有圖表 (趨勢圖、圓餅圖、長條圖)。
     * Top 3 商業洞察卡片。
     * 點擊卡片後的詳細列表 (Modal)。
     * 詳細列表的 Excel 匯出。