================================================================================
              前端 V3 守門落地 + FastAPI 重新評估 (2026-05-12) [IN PROGRESS]
================================================================================

【已完成】
   - V10.284 關閉 Code Review Hermes LLM scan 預設路徑：Step 2 改 deterministic fast static scan，不再讓部署後先卡三段 Ollama timeout；若需要 LLM scan 可用 `CODE_REVIEW_HERMES_LLM_SCAN_ENABLED=true` 顯式開啟，仍只走本地矩陣、不走 Gemini。
   - V10.283 將 Code Review Hermes scan 收斂為 fast compact prompt：預設 2 檔 × 900 字、輸出 384 tokens，仍走 GCP-A → GCP-B → 111 本地矩陣，避免部署後 code_review_hermes 先卡三段 timeout。
   - V10.282 補齊 Code Review Hermes scan 本地模型矩陣：掃描階段也走 GCP-A `qwen2.5-coder:7b` → GCP-B `gemma3:4b` → 111 `hermes3:latest`，避免 `hermes3` 在三主機各卡 35s 後只留下 error；Hermes scan 不會啟用 Gemini。
   - V10.281 強化 Code Review OpenClaw 本地備援矩陣：主機順序仍為 GCP-A → GCP-B → 111，但改成 GCP-A `qwen2.5-coder:7b`、GCP-B `gemma3:4b`、111 `hermes3:latest`，三段本地 Ollama 全失敗後才允許 Claude/Gemini 備援。
   - V10.279 收斂 Code Review Ollama-first 路徑：OpenClaw assessment 預設改 `qwen2.5-coder:7b` + 45s/host timeout，Hermes scan 改 compact snippet + 35s/host timeout，避免三主機各卡 120s 後被迫觸發 Gemini 備援。
   - V10.278 補 PChome 競價摘要 30 分鐘共享快取與 feeder/backfill 主動清除，並新增市場情報 `candidate_queue_review_ai_summary_preflight` 預覽 gate；API 只檢查未來摘要輸入與 Ollama-first/Gemini-backup-only policy，不呼叫 LLM、不派 Telegram、不寫 DB、不掛 scheduler。
   - V10.276 修正 ElephantAlpha 價格類 Hermes prefetch timeout：`price_drop` / `market_opportunity` trigger 直接把 SQL 命中的 MOMO / PChome 價差實證轉成 HITL action lines，完整 Hermes LLM prefetch 預設關閉；無 DB 實證仍只記 suppressed telemetry / cooldown，不寫 `human_review`、不發空 Telegram。
   - V10.266 強化核心 MOMO/PChome 比價鏈路：新增 `marketplace_product_matcher.py` 身份比對、只讓 `identity_v2` 且分數 ≥ 0.76 的高信心配對進 Dashboard/AI/Excel/Daily/Growth/PPT，並建立 `competitor_intel_repository.py` 統一圖表與簡報資料出口；同品牌但不同型號、不同組數、套組/單品或多品項不一致會進待審，不進正式比價。
   - V10.267 專業化 ElephantAlpha `resource_optimization` 告警：不再讓 LLM 生成「48 小時預期效益 / 已執行」敘事，改由程式量測 action queue、P1/P2、pending_review、逾時項目與 CPU load；單純 backlog 不發 Telegram，只有可行動資源壓力才寫 `ai_insights(resource_pressure)` 並發送量測型告警。
   - V10.254 續補 `/growth_analysis` 快取命中效能：PostgreSQL source fingerprint 加 60 秒短 TTL，匯入 realtime_sales_monthly 後同步清除 growth shared cache 與短快取，避免快取命中仍頻繁掃大表 COUNT。
   - V10.253 修正 Elephant Alpha L3 HITL 空告警：價格類與資源調配低信心事件若沒有 Hermes/實證資料，只記 suppressed telemetry 與 cooldown，不寫 pending human_review、不發 Telegram；`resource_optimization` 會保留 queue/load 原始指標供追查。
   - V10.251 修正 OpenClaw Q&A 備援遙測：Ollama 主路徑仍為 GCP-A → GCP-B → 111，Gemini 只記為 `openclaw_qa_gemini_fallback`，NIM 只記為 `openclaw_qa_nim`；AI Calls 會把 legacy `openclaw_qa + gemini` 標成 Gemini 備援，避免再次誤判 Gemini-first。
   - V10.251 穩定 `/growth_analysis` 正式站速度：成長分析快取從單 worker memory 擴充為 `data/growth_analysis_cache.pkl` 跨 worker 共享快取，避免 Gunicorn 冷 worker 偶發掃明細表造成 5 秒級 TTFB；補 `tests/test_cache_manager.py` 覆蓋 shared file roundtrip 與清除行為。
   - V10.249 收斂 `/observability/ppt_audit_history` 手機與平板第一屏密度：將 4 個產線訊號從 hero 內移出成獨立狀態列，手機版維持 2 欄狀態卡並降低 hero 卡片間距；本機 10 個 AI 觀測台頁面 rendered visual contract 全數通過，PPT 頁 hero 高度 desktop/tablet/mobile 為 214/361/398px。
   - V10.246 強化 `/observability/ppt_audit_history` 視覺 QA runtime 可讀性：功能開關、轉檔器與視覺模型改成中文 checklist，Vision QA 狀態卡直接顯示 runtime 就緒資訊，DB 產出狀態統一為「已產出」。
   - V10.245 重整 `/observability/ppt_audit_history` 首屏資訊階層：改成簡報操作摘要、最新可預覽簡報、下一步動作與自適應報表類型 segmented grid；產線覆蓋矩陣改為下方驗收明細，避免一進頁只看到大量「產線狀態」或類型按鈕右側溢出。
   - V10.242 修正 `/metabase`、`/grist` 外部工具入口：全域導覽固定回 momo-pro 內部橋接頁，避免資料協作錯連其他專案站；入口頁補路由狀態、設定診斷與可用替代分析入口，降低空白頁誤判。
   - V10.221 補 `/observability/ppt_audit_history` AiderHeal 背景任務可見性：正在修復中的簡報會顯示於產線頁，並提供 JSON 狀態端點讓派工後即時刷新，避免重新整理後不知道是否已在修。
   - V10.218 補 `/observability/ppt_audit_history` AiderHeal 去重鎖：同一份簡報已在背景修復時，再次點擊會回「已在執行中」，避免重複開 SSH / 模型 / git 修復流程。
   - V10.217 讓 `/observability/ppt_audit_history` 的 AiderHeal 派工改為非阻塞背景任務：頁面立即回「已排入」，修復工作在背景執行，避免瀏覽器與 Gunicorn worker 等 SSH、模型與 git push 到超時。
   - V10.216 修正 `/observability/ppt_audit_history` 的 AiderHeal 派工斷點：失敗簡報即使只有 `issues_found` 診斷摘要也能一鍵送修，並修正 `execute_code_fix` 參數與 dict 回傳解析，避免按鈕 400/500。
   - V10.215 強化 `/observability/ppt_audit_history` 視覺問題追蹤：將 `issues_found` 拆成投影片、問題類型、問題文字與回放入口，新增「視覺問題追蹤」面板，讓問題簡報能直接定位與預覽。
   - V10.213 補 `/observability/ppt_audit_history` 視覺 QA 診斷摘要：審核歷史與 Action Queue 直接顯示 `ppt_audit_results.issues_found` 的投影片問題，讓「有問題」可追查，不再只剩問題數或空白錯誤欄。
   - V10.212 修正 PPT 視覺 QA 的 Ollama 三主機 fallback：當 Primary/Secondary request timeout 超過 unhealthy TTL 時，第三輪仍強制打 111 final fallback；PPT 截圖送模型前轉輕量 JPEG、縮小輸出 token，降低單檔審核耗時。
   - V10.211 補 `/observability/ppt_audit_history` 全類型視覺 QA：審核歷史不再限 daily，頁面新增「立即視覺 QA」非阻塞補跑，結果寫入 `ppt_audit_results`；模型失敗時也保留 slide error，避免產線狀態只剩空白。
   - V10.210 補 `/observability/ppt_audit_history` 審核歷史同頁回放：每筆 daily 視覺審核紀錄的動作欄新增「回放」按鈕，沿用 PDF 預覽抽屜並保留下載/開新頁，讓問題追查不必再回檔案表找簡報。
   - V10.208 修正 `/observability/ppt_audit_history` 同頁預覽抽屜 selector：Modal 標題改用獨立 `data-ppt-preview-modal-title`，避免與多個預覽連結的資料屬性衝突。
   - V10.207 強化 `/observability/ppt_audit_history` 同頁線上預覽：所有可預覽簡報按鈕改為開啟頁內 PDF 預覽抽屜，保留開新頁與下載，降低產線頁來回跳轉成本並改善手機操作。
   - V10.205 補 `/observability/ppt_audit_history` 本頁批次 PDF 預熱：Preview Workbench 可一鍵預熱頁面上尚未快取的 PPTX，沿用單檔 JSON 端點逐一建立 PDF 快取並即時更新狀態。
   - V10.203 補 `/observability/ppt_audit_history` 單檔 PDF 預熱操作：未快取的可預覽 PPTX 會顯示「預熱 PDF」，透過 JSON 端點建立 PDF 快取並即時更新頁面狀態。
   - V10.201 強化 `/observability/ppt_audit_history` 線上預覽可診斷性：產線清單不觸發轉檔即可顯示 PDF 預覽快取狀態，Pipeline Health、Preview Workbench 與已產檔案表同步標記「PDF 快取 / 首次轉檔」。
   - V10.199 讓 `/observability/ppt_audit_history` Action Queue 可直接處理異常：待補齊與異常優先項目新增單一報表「重跑」按鈕，透過既有非阻塞背景產線排入指定 report_type。
   - V10.197 強化 `/observability/ppt_audit_history` Action Queue：新增「異常優先」lane，將產出失敗、PPTX 檔案異常、視覺 QA 失敗拉到最前面，並顯示錯誤訊息與可預覽入口。
   - V10.196 補 `/observability/ppt_audit_history` Action Queue：把待補齊、可預覽、視覺 QA、DB 寫入集中成工作隊列，讓使用者不用在多張卡與表格間找下一個處理點。
   - V10.194 重整 `/observability/ppt_audit_history` 產線資訊階層：新增 Pipeline Health、五段式流程階段、排程/覆蓋/DB/預覽/視覺 QA 狀態摘要，讓「已產生」改為可判斷的目標產生、其他版本、待排程補齊等狀態。
   - V10.192 補 `/observability/ppt_audit_history` 最近可預覽簡報 workbench：最新 4 份 PPT 直接在控制台下方提供線上預覽與下載，降低使用者找檔案的操作成本；完整檔案清單仍保留在下方表格。
   - V10.190 補 `/observability/ppt_audit_file/<filename>` 站內線上預覽：PPTX 由 LibreOffice 轉 PDF 快取後以 iframe 預覽，保留原始 PPTX 下載；Dockerfile 加 `libreoffice-impress`，compose 預設啟用 `PPT_VISION_ENABLED=true`，PPT 產線頁新增視覺 QA 停用原因與更精簡的控制台式排版。
   - V10.188 補強 `/observability/ppt_audit_history` PPT 視覺 QA 產線：頁面明確呈現每日、每週、每月、每季、每半年、每年定期產出節奏，並顯示 `ppt_generation_runs` DB 寫入紀錄；保留自動補齊缺漏與資料庫/檔案覆蓋狀態。
   - V10.187 修正 `/daily_sales`、`/growth_analysis` 圖表空白：Chart JSON 改從 `<template>.content.textContent` 讀取，補空資料診斷狀態；成長分析改用 realtime 明細新鮮度覆蓋過期月結摘要，並為 growth cache 加入資料指紋。
   - V10.151 接續前端 V3 全站 UI/UX：廠商缺貨 `/vendor-stockout/vendor-management`、`/vendor-stockout/send-email`、`/vendor-stockout/history` 改走新版 `ewoooc_base.html` shell 與 `page-vendor-tools.css`，移除舊紫藍 navbar/live route。
   - V10.151 補 `/abc_analysis/detail` 新版 ABC 詳情頁與安全 loading state，移除 raw HTML fallback，資料表維持正式快取資料來源與匯出連結。
   - V10.151 補 `/login` 新版登入頁：暖紙背景、點陣視覺、EwoooC 品牌、手機版 390px 無水平 overflow。
   - V10.151 本機全站 responsive overflow guard 通過 147/147；`?ui=legacy` 入口已不再回到舊 `dashboard.html` / `edm_dashboard.html` / vendor legacy templates。
   - 新版設計系統資產已落到正式 Flask static path：`web/static/css/ewoooc-tokens.css`、`web/static/css/ewoooc-shell.css`、`web/static/css/ewoooc-dotmatrix.css`、`web/static/css/page-*.css` 與對應 `web/static/js/page-*.js`。
   - V3 page-level 資產已補做設計規範清理：移除 UI 表面殘留 radial-gradient / pure-white rgba / `bg-white` header，AI 推薦頁 keyword 狀態改用語意 class。
   - `ewoooc_base.html` 補 `extra_head` / `content` / `extra_scripts` 相容 block，支援新版包混用 block 命名，避免頁面空白或互動 JS 不輸出。
   - Base CSS 載入順序已補齊 `ewoooc-tokens-v2-alias.css`，符合 V3 spec 的 tokens → alias → shell → dotmatrix 順序。
   - `_ewoooc_shell.html` 更新為 V3 側欄結構，保留正式路由連結與 AI 觀測台完整導覽 label。
   - 高風險替換已退回：`dashboard_v2.html` 與 `templates/admin/*` 觀測台頁保留現行真實功能版，拒絕使用會移除 PChome / AI 挑品 / 歷史價格 / 觀測台真實資料的 prototype 空殼。
   - AI 觀測台 CSS canonical 與 Flask mirror 已通過同步檢查：`./scripts/quick_review.sh --check-observability-css`。
   - AI 觀測台 UI guard 已更新為 V3 token 化規範，不再要求舊版 sidebar 漸層片段，並通過 `./scripts/quick_review.sh --observability-ui`。
   - 新增 ADR-036：FastAPI 可作為 strangler migration 中期方向，但不得作為前端 V3 前置條件；後端重構先抽 service 與補 contract，不做 Flask→FastAPI 大爆炸。
   - `/sales_analysis` 修正 V3 首次進頁 JSON context 合約：`category_data` 與模板 fallback 補齊，避免 Jinja `Undefined` 進入 `tojson` 造成 error handler。
   - 本機瀏覽器 QA 完成：`/sales_analysis`、`/daily_sales`、`/monthly_summary_analysis`、`/ai_recommend`、`/auto_import`、`/vendor-stockout/*` 均載入 V3 shell、無錯誤 banner、console error 0。
   - 正式環境已推版：白名單同步 55 個 V3 runtime 檔案與 `config.py` 版本號，僅 recreate `momo-app`，未碰 `momo-db`、未使用 `--remove-orphans`；`https://mo.wooo.work/health` 回報 V10.91，V3 頁面 smoke 與觀測台 production QA 均通過。
   - 版本同步至 V10.91。
   - 依使用者截圖回饋修正 `/daily_sales`：KPI 改為首屏摘要格、日曆密度提升、桌機 1440 與手機 390 均無整頁水平 overflow。
   - 依使用者截圖回饋修正 `/edm`：寬螢幕內容最大寬度調整至 1600px、活動表格限制在局部 scroll container、手機版無整頁水平 overflow。
   - 新增 `scripts/check_v3_responsive_ui.js`，覆蓋 23 個主要 route 的 desktop/mobile responsive smoke；本機通過 46/46。
   - 移除 V3 主要頁面 CSS 內殘留負字距，符合新版排版規範。
   - 版本同步至 V10.92。
   - 正式環境 V10.92 已白名單部署：備份 `/tmp/codex_v3_1092_predeploy_20260512_164549.tgz`，只 recreate `momo-app`，未碰 `momo-db`、未使用 `--remove-orphans`。
   - 正式驗證通過：`https://mo.wooo.work/health` 回報 V10.92，觀測台 production QA PASS，23 個主要 route 的 desktop/mobile responsive smoke 46/46 PASS。
   - 人工視覺 QA 追修 `/growth_analysis` 手機 KPI 可讀性：KPI 卡片改為暖墨文字、左側 accent、明確數字層級，避免淡底反白造成首屏不可讀。
   - 版本同步至 V10.93。

【下次待辦】
   - V10.93 白名單部署後補正式 health 與 responsive smoke 結果。
   - 為 FastAPI strangler 補 endpoint inventory：先列 route owner、資料來源、auth/CSRF/session 需求與 smoke URL，再決定第一批可遷移 API。
   - `production_v3 3/templates/dashboard.html` 與 `production_v3 3/templates/observability/*` 不得直接覆蓋正式頁；需先補回真實資料功能後才可進入替換候選。

================================================================================
                 跨平台市場情報模組 (ADR-035 / 2026-05-06) [IN PROGRESS]
================================================================================

【已完成】
   - ADR-035：定義跨平台市場活動情報系統、feature flags、market_* schema、爬蟲安全邊界與分階段 rollout。
   - 模組化盤點：更新 `docs/memory/code_modularization_inventory_20260430.md`，標記市場情報不可塞回 `app.py`、`scheduler.py`、`routes/sales_routes.py` 等大檔。
   - Phase 1 安全骨架：新增 `routes/market_intel_routes.py`、`services/market_intel/`、`templates/market_intel/disabled.html`，預設只顯示 disabled 狀態。
   - Phase 2 schema 骨架：新增 `database/market_intel_models.py`，定義 `market_platforms`、`market_campaigns`、`market_campaign_snapshots`、`market_campaign_products`、`market_product_price_history`、`market_product_matches`、`market_crawler_runs`。
   - Metadata 守門：`database/manager.py` 顯式 import market_intel models，`app.py` expected metadata tables 已同步。
   - 安全開關：`.env.example` 補 `MARKET_INTEL_ENABLED=false`、`MARKET_INTEL_CRAWLER_ENABLED=false`、`MARKET_INTEL_WRITE_ENABLED=false`。
   - Phase 3 read-only adapter 骨架：新增 `services/market_intel/adapters/`，目前註冊 MOMO 與 PChome，僅回傳 discovery plan，不發 HTTP request、不寫 DB、不掛 scheduler。
   - Phase 4 手動 dry-run discovery：新增 `services/market_intel/discovery_runner.py` 與 `/api/market_intel/manual_discovery`。預設 `fetch=false` 只回 planned；`fetch=true` 也必須在 `MARKET_INTEL_ENABLED` 與 `MARKET_INTEL_CRAWLER_ENABLED` 同時開啟時才允許 HTTP，且仍不寫 DB、不掛 scheduler。
   - Phase 5 parser 診斷層：新增 `services/market_intel/html_diagnostics.py`，手動 fetch 成功後只萃取 title、page_hash、link count、campaign link candidates，不建立正式 campaign/product。
   - Phase 6 平台別 scorer：MOMO/PChome adapter 提供 URL/text 加權規則，diagnostics 同時輸出 generic_score 與 platform_score，仍只用於候選排序與人工診斷。
   - Phase 7 confidence bands：diagnostics 將候選標成 `high` / `medium` / `low`，並輸出 `confidence_reason`；只作人工審核提示，不自動建立活動。
   - Phase 8 candidate preview API：新增 `/api/market_intel/candidate_preview`，把本次 discovery diagnostics 候選合併排序，支援 `min_band` 與 `limit`，只供人工預覽，不入庫。
   - Phase 9 UI preview panel：`templates/market_intel/disabled.html` 讀取 `/api/market_intel/candidate_preview?fetch=false`，顯示安全空狀態與 flags，不做自動外部 fetch。
   - Phase 10 platform seed plan：新增 `/api/market_intel/platform_seed_plan`，只產生 adapter registry 對應的 `market_platforms` seed rows 與 gate 狀態，不寫 DB。
   - Phase 11 Coupang read-only adapter：新增 Coupang 酷澎 adapter，以官方台灣站與火箭跨境入口作為公開 discovery 起點，預設不發 request、不寫 DB、不掛 scheduler。
   - Phase 12 Shopee read-only adapter：新增 Shopee 蝦皮 adapter，以公開首頁與 Shopee Mall 入口作為 discovery 起點；不得登入、碰會員券、購物車、帳號池或反爬繞過。
   - Phase 13 platform seed write guard：新增 `/api/market_intel/platform_seed_write_guard`，只回報寫入前 gate 與阻擋原因，預設永遠不寫 DB。
   - Phase 14 platform seed writer dry-run：新增 `/api/market_intel/schema_smoke` 與 `/api/market_intel/platform_seed_writer_plan`，實際檢查 ORM metadata 並產生 parameterized upsert preview，不建立 session、不 commit。
   - Phase 15 writer preview panel：`templates/market_intel/disabled.html` 讀取 `/api/market_intel/platform_seed_writer_plan`，顯示 schema smoke、upsert preview 與 blocked reasons，仍不寫 DB。
   - Phase 16 deployment readiness panel：新增 `/api/market_intel/deployment_readiness` 與 UI「推版準備檢查」，明確回報尚未正式推版、尚未 commit/push、部署 SOP 與 production smoke 尚待人工執行。
   - Phase 17 deployment handoff checklist：`/api/market_intel/deployment_readiness` 補人工步驟、備援方案、安全部署邊界、production smoke targets 與 `python backup_system.py` 備份要求；UI 直接顯示，不執行任何 git/部署/DB 操作；版本同步至 V10.87。
   - Phase 18 write approval runbook：新增 `/api/market_intel/write_approval_runbook` 與 UI「正式寫入批准檢查」，列出 schema smoke、備份、migration review、feature flag、人工批准、rollback 等 gate；預設 `ready_for_real_write=false`、`database_session_created=false`、`database_commit_executed=false`；版本同步至 V10.88。
   - Phase 19 migration blueprint：新增 `/api/market_intel/migration_blueprint` 與 UI「Schema migration 草案」，產生 `migrations/032_market_intel_core_schema.sql` 建議內容、migration apply command shape 與 seed writer command design；預設 `file_created=false`、`migration_executed=false`、`database_commit_executed=false`，且 forward SQL 只允許 additive DDL；版本同步至 V10.89。
   - Phase 20 migration file draft：新增本地草稿檔 `migrations/032_market_intel_core_schema.sql`，blueprint API 會檢查檔案存在且內容與 blueprint 相符；仍然 `migration_executed=false`、`database_session_created=false`、`database_commit_executed=false`；版本同步至 V10.90。
   - Phase 21 seed writer CLI skeleton：新增 `scripts/market_intel_seed_writer.py`、`services/market_intel/seed_writer_cli.py` 與 `/api/market_intel/seed_writer_cli_status`；CLI 可輸出 seed writer blocked plan，但即使帶 `--execute` 與 approval token 也會拒絕真寫入，維持 `database_session_created=false`、`database_commit_executed=false`；版本同步至 V10.94。
   - Phase 22 app-only release gate：`/api/market_intel/deployment_readiness` 改為區分「安全檢查已可進 app-only 推版」與「API 不執行部署動作」；新增 `mode=app_only_release_gate`、`execution_boundary`，維持 `api_runs_migration=false`、`api_writes_database=false`、`production_deployed=false`；版本同步至 V10.95。
   - 正式環境 V10.95 已白名單部署：備份 `/tmp/codex_market_intel_v1095_predeploy_20260512_194041.tgz` 與 compose 備份 `/tmp/docker-compose.market-intel-v1095-mount-20260512_194827.yml`，同步 market_intel runtime 檔案並補 app-only `scripts/`、`migrations/` mount 後僅 recreate `momo-app`，未碰 `momo-db`、未使用 `--remove-orphans`；`https://mo.wooo.work/health` 回報 V10.95，market_intel schema/writer/readiness/migration/seed execute-block smoke 通過。
   - Phase 23 seed transaction preview：`/api/market_intel/seed_writer_cli_status` 內新增 `transaction_preview`，輸出 `market_platforms` idempotent upsert SQL template、parameter hash、diff 狀態與 runtime order；UI 新增「Seed CLI 交易預覽」panel；仍維持 `database_session_created=false`、`transaction_opened=false`、`database_commit_executed=false`；版本同步至 V10.96。
   - 正式環境 V10.96 已白名單部署：備份 `/tmp/codex_market_intel_v1096_predeploy_20260512_211619.tgz`，僅同步 market_intel runtime/docs/test 檔案並 recreate `momo-app`，未碰 `momo-db`、未使用 `--remove-orphans`；`https://mo.wooo.work/health` 回報 V10.96，`seed_writer_cli_status` dry-run/execute-block、deployment readiness 與正式頁 UI smoke 均通過。
   - Phase 24 read-only DB schema probe：新增 `/api/market_intel/schema_db_probe` 與 UI「正式 DB Schema 探針」panel；預設 `execute=false` 只回 planned、不連 DB，人工 smoke 才可用 `execute=true` 查正式 DB catalog；不使用 `DatabaseManager()`、不呼叫 `create_all()`、不建立 ORM session、不寫入、不 commit；版本同步至 V10.97。
   - 正式環境 V10.97 已白名單部署：備份 `/tmp/codex_market_intel_v1097_predeploy_20260512_214226.tgz`，僅同步 market_intel runtime/docs/test 檔案並 recreate `momo-app`，未碰 `momo-db`、未使用 `--remove-orphans`；`https://mo.wooo.work/health` 回報 V10.97，`schema_db_probe` planned/read-only execute、seed execute-block、deployment readiness 與正式頁 UI smoke 均通過。
   - Phase 25 platform seed DB diff probe：新增 `/api/market_intel/platform_seed_db_diff` 與 UI「平台 Seed DB 差異探針」panel；預設 `execute=false` 只回 planned、不連 DB，人工 smoke 才可用明確只讀參數比對 adapter seed 與 `market_platforms` 既有 rows；不使用 `DatabaseManager()`、不建立 ORM session、不寫入、不 commit；版本同步至 V10.98。
   - 正式環境 V10.98 已白名單部署：備份 `/tmp/codex_market_intel_v1098_predeploy_20260512_220309.tgz`，僅同步 market_intel runtime/docs/test 檔案並 recreate `momo-app`，未碰 `momo-db`、未使用 `--remove-orphans`；`https://mo.wooo.work/health` 回報 V10.98，`platform_seed_db_diff` planned/read-only execute、seed execute-block、deployment readiness 與正式頁 UI smoke 均通過；正式 DB 只讀 diff 顯示 `market_platforms` 目前 0 筆，四平台 seed 仍 missing，符合未正式寫入狀態。
   - Phase 26 platform seed CLI writer：`scripts/market_intel_seed_writer.py` 支援 CLI-only 受控寫入，必須同時帶 `--execute`、`--apply-real-write` 與確認 token 才會以 SQLAlchemy Core 短 transaction upsert `market_platforms`；API 仍不執行寫入，不建立 ORM session、不連外、不掛 scheduler；V10.101 補強 insert 顯式寫入 `created_at` / `updated_at`，避免正式 schema 無 default 時觸發 not-null rollback。
   - 正式環境 V10.101 已白名單部署：備份 `/tmp/codex_market_intel_v10100_predeploy_20260513_103809.tgz`、`/tmp/codex_market_intel_v10101_predeploy_20260513_104053.tgz` 與 seed 前快照 `/tmp/codex_market_platforms_v10100_before_20260513_103809.json`；僅 recreate `momo-app`，未碰 `momo-db`、未使用 `--remove-orphans`。CLI seed 首次因 timestamp not-null rollback，V10.101 修正後成功 insert `momo/pchome/coupang/shopee` 四筆 seed；read-only diff 顯示 existing=4、missing=0、matching=4，正式頁 console error 0。
   - 2026-05-13 Codex 只讀複核：`https://mo.wooo.work/health` 回報 V10.111；`/api/market_intel/status` 仍為 `enabled=false`、`crawler_enabled=false`、`write_enabled=false`、`dry_run_only=true`、phase 26；`/api/market_intel/platform_seed_db_diff?execute=true&platform=all` 只讀確認 `market_platforms` 已有 `momo/pchome/coupang/shopee` 四筆，`existing_seed_count=4`、`missing_codes=[]`、`database_write_executed=false`。
   - 注意：正式端 `/api/market_intel/seed_writer_cli_status?execute=true&platform=all` 仍回傳舊版 `approval_token_hint=APPROVED_MARKET_INTEL_SEED_WRITE_V1` 與固定 token gate 文案，與 main 已入庫的一次性環境 token hardening 不一致；下次正式白名單部署需優先同步 `services/market_intel/seed_writer_cli.py`、`services/market_intel/service.py`、`scripts/market_intel_seed_writer.py`，並 smoke 確認不再回吐 `approval_token_hint`。
   - Phase 27 legacy source bridge preview：新增 `services/market_intel/legacy_source_bridge.py` 與 `/api/market_intel/legacy_source_bridge`，只讀盤點既有 `promo_products`、`competitor_prices`、`competitor_price_history`，產生導入 `market_*` 的 mapping / dedupe / blocked operation preview；預設 `execute=false` 不連 DB，`execute=true` 也只做 read-only query，不寫 DB、不建立 ORM session、不連外、不掛 scheduler；UI 新增「既有資料橋接預覽」panel；版本同步至 V10.182。
   - Phase 45 migration live smoke preview：新增 `/api/market_intel/migration_live_smoke` 與 UI「正式 DB 只讀 smoke」panel；預設 `execute=false` 只回 planned，人工 smoke 才可用 `execute=true` 整理 catalog / seed diff 結果，不執行 migration、不寫 DB、不跑 rollback、不掛 scheduler；版本同步至 V10.207。
   - Phase 46 live DB inventory preview：新增 `/api/market_intel/live_db_inventory` 與 UI「正式 DB 庫存總覽」panel；預設 `execute=false` 不連 DB，人工 smoke 才可用 `execute=true` 對 `market_*` tables 做只讀 count / group by，建立平台、活動、商品、比對、告警與 crawler run 基準；版本同步至 V10.209。
   - Phase 47 manual sample fetch plan：新增 `/api/market_intel/manual_sample_plan` 與 UI「人工樣本 Fetch 計畫」panel；預設只輸出平台順序、每平台 1 個公開入口、MCP gate、操作員步驟與備援，不抓外站、不寫 DB、不建立 crawler run、不掛 scheduler；版本同步至 V10.214。
   - Phase 48 manual sample acceptance contract：新增 `/api/market_intel/manual_sample_acceptance` 與 UI「樣本結果驗收契約」panel；定義 sample result 必要欄位、diagnostics 欄位、驗收門檻、拒收條件、人工決策與升級順序，不載入 sample result、不抓外站、不允許候選導入、不寫 DB；版本同步至 V10.215。
   - Phase 49 manual sample result review：新增 `services/market_intel/manual_sample_review.py`、`/api/market_intel/manual_sample_review` 與 UI「樣本結果審核預覽」panel；以純函式評估人工 sample result 是否可進候選預覽，預設不載入結果、不抓外站、不存檔、不寫 DB、不允許候選導入、不掛 scheduler；版本同步至 V10.216。
   - Phase 50 manual sample review evaluate：新增 `/api/market_intel/manual_sample_review/evaluate` POST 與 UI JSON 審核入口，允許操作員貼入單筆 sample result 即時回傳 PASS/BLOCK；不保存 payload、不回吐完整 HTML、不寫 DB、不建立候選活動、不允許候選導入、不掛 scheduler；版本同步至 V10.219。
   - V10.220 補 Phase 50 UI POST CSRF header：`manual_sample_review/evaluate` 保持 CSRF 保護，頁面 fetch 送出 `X-CSRFToken`，不豁免安全檢查。
   - Phase 51 manual sample candidate handoff：新增 `/api/market_intel/manual_sample_review/candidate_handoff` POST 與 UI handoff 按鈕，將已通過審核的 sample result 轉成只讀候選活動 preview payload；不保存 handoff、不建立 review queue、不寫 market_*、不允許候選導入、不掛 scheduler；版本同步至 V10.222。
   - Phase 52 manual sample candidate queue draft：新增 `services/market_intel/manual_sample_candidate_queue.py`、`/api/market_intel/manual_sample_review/candidate_queue_draft` POST 與 UI queue 草案按鈕，將 handoff 候選轉成只讀人工審核 queue draft；不建立正式 queue、不保存草案、不寫 market_*、不自動核准候選、不掛 scheduler；版本同步至 V10.223。
   - V10.224 補 PPT 報表覆蓋矩陣：`/observability/ppt_audit_history` 將每個定義簡報同列串起 DB 寫入、線上預覽、視覺 QA 與交付狀態，並提供預覽、預熱、重跑操作，避免只顯示「目標已產生」。
   - Phase 53 manual sample candidate queue approval：新增 `/api/market_intel/manual_sample_review/candidate_queue_approval` POST 與 UI 送審 gate 按鈕，將 queue draft row preview 對齊既有 `market_alert_review_queue` 契約，檢查必填欄位、寫入 flags、備份與人工批准 gate；不建立 approval record、不寫 review queue、不開 DB transaction、不掛 scheduler；版本同步至 V10.225。
   - V10.226 補 PPT 視覺 QA runtime checklist：`/observability/ppt_audit_history` 在視覺模型未就緒時顯示 Feature Flag、LibreOffice、Vision Model 三段檢查與下一步操作，避免只看到「停用」而不知道卡在哪。
   - Phase 54 manual sample candidate queue transaction：新增 `/api/market_intel/manual_sample_review/candidate_queue_transaction` POST 與 UI transaction preview 按鈕，將 queue row preview 轉成 `market_alert_review_queue` idempotent insert statement、payload hash 與 rollback plan；不開 DB connection、不開 transaction、不 commit、不建立 approval record；版本同步至 V10.227。
   - V10.228 補 PPT 視覺 QA 背景狀態卡：新增 `/observability/ppt_audit/vision_status` 與頁面 Vision QA 狀態卡，讓立即視覺 QA 排入後可看 queued/running/completed/error 與最近審核摘要，不必刷新猜測。
   - V10.229 修正 PPT 視覺 QA 多 worker 狀態漂移：將 queued/running/completed/error 寫入 `/app/data/ppt_vision_audit_status.json` runtime state，所有 Gunicorn worker 共用同一份狀態並阻擋重複排入。
   - Phase 55 candidate queue writer CLI gate：新增 `/api/market_intel/manual_sample_review/candidate_queue_writer_status` POST、`scripts/market_intel_candidate_queue_writer.py` 與 UI writer gate 按鈕，定義 `MARKET_INTEL_QUEUE_WRITE_APPROVAL` 一次性 token、execute/apply flags、備份、migration smoke 與 rollback gate；本階段仍不開 DB connection、不寫 `market_alert_review_queue`、不 commit、不掛 scheduler；版本同步至 V10.230。
   - Phase 56 candidate queue writer preflight：新增 `/api/market_intel/manual_sample_review/candidate_queue_writer_preflight` POST 與 `services/market_intel/candidate_queue_writer_preflight.py`，檢查 transaction payload key 到 `market_alert_review_queue` 欄位映射、缺欄與 dedupe unique index；頁面預設 execute=false 不連 DB，CLI 可明確 `--read-only-preflight` 只讀 catalog；版本同步至 V10.232。
   - Phase 57 candidate queue writer CLI transaction：`scripts/market_intel_candidate_queue_writer.py` 在 CLI-only 情境支援受控 transaction，必須同時通過 transaction payload、read-only preflight、`--execute`、`--apply-real-write`、一次性 token、備份確認與 migration live smoke 才會以 SQLAlchemy Core idempotent insert `market_alert_review_queue`；API/UI 仍不傳 token、不連 DB、不寫 queue、不掛 scheduler；版本同步至 V10.234。
   - V10.235 補 PPT 視覺 QA stale recovery：背景狀態寫入 worker PID；若部署 reload 後舊 PID 已不存在，`/observability/ppt_audit/vision_status` 會自動把 running 轉為可診斷 error 並允許重新排入，避免人工清 runtime state。
   - Phase 58 candidate queue writer post-write smoke：新增 `services/market_intel/candidate_queue_writer_postwrite_smoke.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_writer_postwrite_smoke` 與 UI smoke 按鈕，依 transaction preview 的 dedupe key 只讀查詢 `market_alert_review_queue`，讓 CLI 真寫入後可驗證 row 是否存在；頁面預設 execute=false 不連 DB、不寫 queue、不 commit、不掛 scheduler；版本同步至 V10.236。
   - Phase 59 candidate queue writer operator drill：新增 `services/market_intel/candidate_queue_writer_operator_drill.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_writer_operator_drill` 與 UI drill 按鈕，組裝 reviewed sample、備份、read-only preflight、CLI writer、post-write smoke 的操作員順序；API/UI 不讀 approval token、不執行 CLI、不連 DB、不寫 queue、不 commit、不掛 scheduler；版本同步至 V10.237。
   - V10.238 補業績圖表 runtime QA 與分析 tabs 窄版修正：新增 `quick_review --sales-charts` 檢查 `/daily_sales`、`/growth_analysis` 的 Chart.js ready、可繪製資料集與 canvas 非空白；同時把分析報表 tabs 手機版改為自適應 grid，避免 Metabase/Grist 外部連結超出右側。
   - Phase 60 candidate queue writer run package：新增 `services/market_intel/candidate_queue_writer_run_package.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_writer_run_package` 與 UI run package 按鈕，整理正式 CLI 小流量寫入前的 payload manifest、required artifacts、command bundle、operator signoff 與 rollback plan；API/UI 不產檔、不讀 approval token、不執行 CLI、不連 DB、不寫 queue、不 commit、不掛 scheduler；版本同步至 V10.240。
   - Phase 61 candidate queue writer run readiness：新增 `services/market_intel/candidate_queue_writer_run_readiness.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_writer_run_readiness` 與 UI readiness 按鈕，檢查 reviewed sample 檔案路徑、備份路徑、preflight 輸出、migration live smoke、shell-only token acknowledgement 與禁止 token 進 API；API/UI 不產檔、不讀 approval token、不執行 CLI、不連 DB、不寫 queue、不 commit、不掛 scheduler；版本同步至 V10.245。
   - Phase 62 candidate queue writer run receipt：新增 `services/market_intel/candidate_queue_writer_run_receipt.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_writer_run_receipt` 與 UI receipt 按鈕，審核 CLI 寫入後的 writer output、post-write smoke、dedupe key 一致性與 artifact 路徑；API/UI 不回吐 receipt 原文、不讀 approval token、不執行 CLI、不連 DB、不寫 queue、不掛 scheduler；版本同步至 V10.247。
   - Phase 63 candidate queue writer run closeout：新增 `services/market_intel/candidate_queue_writer_run_closeout.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_writer_run_closeout` 與 UI closeout 按鈕，在 receipt 通過後檢查 closeout artifact、操作員人工 queue review/read-only inventory 確認與安全 promotion gate；API/UI 不回吐原始 receipt、不讀 approval token、不執行 CLI、不連 DB、不寫 queue、不掛 scheduler；版本同步至 V10.248。
   - Phase 64 candidate queue review handoff：新增 `services/market_intel/candidate_queue_review_handoff.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_review_handoff` 與 UI handoff 按鈕，將 writer closeout 轉成人工 queue review / read-only inventory 交接契約；API/UI 不讀 approval token、不查 DB、不更新 review_state、不補寫 queue、不掛 scheduler；版本同步至 V10.251。
   - Phase 65 candidate queue review inventory：新增 `services/market_intel/candidate_queue_review_inventory.py`、`routes/market_intel_review_routes.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_review_inventory` 與 UI inventory 按鈕，把 handoff、post-write smoke、live DB inventory 合併成只讀人工審核庫存檢查；預設不連 DB，人工只讀查詢仍不更新 review_state、不補寫 queue、不讀 token、不掛 scheduler；版本同步至 V10.252。
   - Phase 66 candidate queue review decision：新增 `services/market_intel/candidate_queue_review_decision.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_review_decision` 與 UI decision 按鈕，將通過 inventory 的 queue row 整理成人工決策草案；API/UI 不更新 review_state、不寫 decision record、不讀 token、不掛 scheduler；版本同步至 V10.254。
   - Phase 67 candidate queue review decision approval：新增 `services/market_intel/candidate_queue_review_decision_approval.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_review_decision_approval` 與 UI approval gate 按鈕，檢查人工決策草案是否可進入下一個 CLI-only transaction preview；API/UI 不更新 review_state、不寫 decision record、不建立 approval record、不讀 token、不掛 scheduler；版本同步至 V10.255。
   - Phase 68 candidate queue review decision transaction：新增 `services/market_intel/candidate_queue_review_decision_transaction.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_review_decision_transaction` 與 UI transaction preview 按鈕，將 approval update preview 轉成 `review_state` update statement、payload hash 與 rollback plan；API/UI 不更新 review_state、不開 DB connection、不執行 CLI、不讀 token、不掛 scheduler；版本同步至 V10.256。
   - Phase 69 candidate queue review decision writer CLI gate：新增 `services/market_intel/candidate_queue_review_decision_writer_cli.py`、`scripts/market_intel_review_decision_writer.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_review_decision_writer_status` 與 UI writer gate 按鈕，先建立 shell-only review_state writer gate 與 command bundle；writer implementation 本階段保持 disabled，API/UI 不讀 token、不執行 CLI、不連 DB、不更新 review_state、不掛 scheduler；版本同步至 V10.257。
   - Phase 70 candidate queue review decision writer preflight：新增 `services/market_intel/candidate_queue_review_decision_writer_preflight.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_review_decision_writer_preflight` 與 UI preflight 按鈕，檢查 writer status、review_state update payload、狀態轉換與禁止 token 進 API；API/UI 即使收到 execute/apply_real_write 也不連 DB、不執行 CLI、不更新 review_state、不 commit、不讀 token、不掛 scheduler；版本同步至 V10.258。
   - V10.259 補 Phase 70 preflight 合約與 OCLearn queue 時區：preflight 補 planned/read-only catalog probe 欄位、dedupe unique index 檢查與 route 重複註冊清理；OCLearn embedding queue 的 created_at/updated_at/stale cutoff 改為台北 naive，避免 UTC/台北時間差讓 processing 任務卡住。
   - Phase 71 candidate queue review decision writer post-write smoke：新增 `services/market_intel/candidate_queue_review_decision_writer_postwrite_smoke.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_review_decision_writer_postwrite_smoke` 與 UI smoke 按鈕，人工 CLI 更新 review_state 後可用 dedupe key 只讀驗證 row 是否存在且 state 符合預期；API/UI 預設不連 DB，execute=true 也只讀查詢，不更新 review_state、不 commit、不讀 token、不掛 scheduler；版本同步至 V10.260。
   - Phase 72 candidate queue review decision writer operator drill：新增 `services/market_intel/candidate_queue_review_decision_writer_operator_drill.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_review_decision_writer_operator_drill` 與 UI drill 按鈕，將 review_state CLI 更新前後的 transaction JSON、備份、preflight、CLI writer、post-write smoke 與 rollback plan 組成可稽核操作順序；API/UI 不讀 token、不執行 CLI、不連 DB、不更新 review_state、不 commit、不掛 scheduler；版本同步至 V10.261。
   - Phase 73 candidate queue review decision writer run package：新增 `services/market_intel/candidate_queue_review_decision_writer_run_package.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_review_decision_writer_run_package` 與 UI package 按鈕，將 review_state transaction、preflight、operator drill、writer gate、post-write smoke、必要 artifact 與 rollback plan 組成正式 CLI 更新前的可稽核 run package；API/UI 不寫檔、不讀 token、不執行 CLI、不連 DB、不更新 review_state、不 commit、不掛 scheduler；版本同步至 V10.262。
   - Phase 74 candidate queue review decision writer run readiness：新增 `services/market_intel/candidate_queue_review_decision_writer_run_readiness.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_review_decision_writer_run_readiness` 與 UI readiness 按鈕，檢查 review_state CLI 更新前的 transaction JSON、備份、preflight、shell-only token 與 post-write smoke 計畫是否齊備；API/UI 不寫檔、不讀 token、不執行 CLI、不連 DB、不更新 review_state、不 commit、不掛 scheduler；版本同步至 V10.264。
   - Phase 75 candidate queue review decision writer run receipt：新增 `services/market_intel/candidate_queue_review_decision_writer_run_receipt.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_review_decision_writer_run_receipt` 與 UI receipt 按鈕，審核 review_state CLI 更新後的 writer output、post-write smoke、dedupe key 一致性、artifact 路徑與 token 外洩風險；API/UI 不回吐 receipt 原文、不讀 token、不執行 CLI、不連 DB、不更新 review_state、不 commit、不掛 scheduler；版本同步至 V10.266。
   - Phase 76 candidate queue review decision writer run closeout：新增 `services/market_intel/candidate_queue_review_decision_writer_run_closeout.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_review_decision_writer_run_closeout` 與 UI closeout 按鈕，在 review_state receipt 通過後整理 closeout gate、操作員 closeout artifact、post-closeout read-only inventory 確認與 promotion 摘要；API/UI 不回吐 receipt 原文、不讀 token、不執行 CLI、不連 DB、不更新 review_state、不 commit、不掛 scheduler；版本同步至 V10.268。
   - Phase 77 candidate queue review decision post-closeout inventory：新增 `services/market_intel/candidate_queue_review_decision_post_closeout_inventory.py`、`routes/market_intel_review_post_routes.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_review_decision_post_closeout_inventory` 與 UI inventory 按鈕，在 review_state closeout 後整理 post-write smoke、live inventory、dedupe key 與 review_state 結果；API/UI 不讀 token、不執行 CLI、不更新 review_state、不寫 DB、不 commit、不掛 scheduler；版本同步至 V10.270。
   - Phase 78 candidate queue review completion archive：新增 `services/market_intel/candidate_queue_review_completion_archive.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_review_completion_archive` 與 UI archive 按鈕，在 post-closeout inventory 通過後整理 receipt、closeout、inventory、dedupe key、review_state row snapshot 與 artifact path manifest；API/UI 不寫檔、不讀 token、不執行 CLI、不更新 review_state、不寫 DB、不 commit、不掛 scheduler；版本同步至 V10.273。
   - Phase 79 candidate queue review archive summary：新增 `services/market_intel/candidate_queue_review_archive_summary.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_review_archive_summary` 與 UI summary 按鈕，在 review completion archive 後整理可供摘要/報表審核的結構化輸入；API/UI 不呼叫 LLM、不派送 Telegram、不寫檔、不讀 token、不執行 CLI、不更新 review_state、不寫 DB、不 commit、不掛 scheduler；版本同步至 V10.276。
   - Phase 80 candidate queue review AI summary preflight：新增 `services/market_intel/candidate_queue_review_ai_summary_preflight.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_review_ai_summary_preflight` 與 UI preflight 按鈕，在 archive summary 後檢查 Ollama-first 三主機級聯與 Gemini 備援邊界；API/UI 不呼叫 LLM、不派送 Telegram、不寫檔、不讀 token、不執行 CLI、不更新 review_state、不寫 DB、不 commit、不掛 scheduler；版本同步至 V10.278。
   - Phase 81 candidate queue review AI summary run package：新增 `services/market_intel/candidate_queue_review_ai_summary_run_package.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_review_ai_summary_run_package` 與 UI package 按鈕，在 AI summary preflight 後整理手動 Ollama 摘要任務包、prompt contract 與輸出 schema；API/UI 不呼叫 LLM、不派送 Telegram、不寫 run package、不讀 token、不執行 CLI、不更新 review_state、不寫 DB、不 commit、不掛 scheduler；版本同步至 V10.280。
   - Phase 82 candidate queue review AI summary output receipt：新增 `services/market_intel/candidate_queue_review_ai_summary_output_receipt.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_review_ai_summary_output_receipt` 與 UI receipt 按鈕，在 run package 後驗收人工 Ollama 摘要輸出的 schema、evidence_refs 與 model_route；API/UI 不呼叫 LLM、不派送 Telegram、不寫 receipt、不讀 token、不執行 CLI、不更新 review_state、不寫 DB、不 commit、不掛 scheduler；版本同步至 V10.285。
   - Phase 83 candidate queue review AI summary persistence preflight：新增 `services/market_intel/candidate_queue_review_ai_summary_persistence_preflight.py`、POST `/api/market_intel/manual_sample_review/candidate_queue_review_ai_summary_persistence_preflight` 與 UI preflight 按鈕，在 output receipt 後整理 future CLI-only `market_alert_review_queue.metadata_json.ai_summary_review` persistence contract、payload hash 與 metadata patch preview；API/UI 不呼叫 LLM、不派送 Telegram、不寫 preflight、不寫 summary record、不寫 metadata_json、不讀 token、不執行 CLI、不更新 review_state、不寫 DB、不 commit、不掛 scheduler；版本同步至 V10.286。
   - V10.248 補市場情報 390px preview panel QA：sample review 工具列改為 textarea + 可換行 action rail，移除舊的硬編 8 欄 grid；`check_responsive_overflow` 新增 `--screenshot-all`，本機 390x844 `/market_intel` 真頁面 QA 通過且 overflow=0。
   - V10.250 補 Code Review Gemini 備援遙測護欄：Ollama 主路徑失敗時 `fallback_to` 明確指向 `code_review_openclaw_gemini`，測試鎖住「Gemini 不得記成 `code_review_openclaw` 主 caller」；AI Calls 觀測台會把 legacy `code_review_openclaw + gemini` 顯示成 Gemini 備援，避免誤判 Gemini-first。
   - Schema smoke：`tests/test_market_intel_skeleton.py` 檢查 `Base.metadata` 內含 ADR-035 八張 `market_*` tables。
   - Desktop UI QA：本機只註冊 `market_intel_bp` 的 Flask harness 載入 `/market_intel`，確認 Phase 15、候選預覽、writer preview、安全 flags、點陣暖紙視覺正常，console error 0。
   - API QA：`/api/market_intel/schema_smoke` 通過 7 張表與 `market_platforms` 必要欄位檢查；`/api/market_intel/platform_seed_writer_plan` 回傳 4 筆 dry-run upsert preview，`writes_executed=false`，四平台皆 `blocked_dry_run_only`。
   - Narrow viewport UI QA：in-app browser 窄版畫面確認側欄收合、卡片不水平爆版、候選狀態顯示 `momo/pchome/coupang/shopee:planned`。
   - 測試：新增 `tests/test_market_intel_skeleton.py`，確認預設 flags 全關、adapter 不允許 network/write/scheduler，手動 discovery / candidate preview 預設不發 request，parser/scorer/confidence 診斷只輸出 JSON，UI 只使用 `fetch=false`，platform seed plan 只讀且需 gate。

【下次待辦】
   - 正式端 seed writer token-hardening drift：優先白名單同步 main 的一次性環境 token 版本，避免 API 暴露固定 approval token hint。
   - 正式推版前需實際執行 worktree scope review、`python backup_system.py`、commit/push 目標變更、讀 deployment SOP 與 ADR-011，且只跑 `/health` 與市場情報頁 smoke。
   - 下一步才可在明確批准且具備真實 reviewed sample JSON 後做正式 DB 的 queue writer CLI 小流量 operator run；先用 run readiness、run package、operator drill、post-write smoke、run receipt、run closeout 與 queue review handoff 做順序與只讀驗證，預設 API/UI 不得寫 DB，也不得執行 migration。
   - 市場情報 UI 後續頁面必須沿用 V2 暖紙、暖墨、等寬數字與點陣風格，禁止複製巨型分析頁 template 模式。

================================================================================
                      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 匯出。