wooo/ewoooc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
032ba2bbd3bd53daa88ea24d7ce1e7ea0e3db222
ewoooc/TODO_NEXT_STEPS.txt
OoO 6fc064cd9a
All checks were successful
CD Pipeline / deploy (push) Successful in 1m12s
Details
新增市場情報 AI summary persistence preflight
2026-05-19 23:10:32 +08:00

1075 lines
90 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
================================================================================
前端 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 匯出。
Reference in New Issue View Git Blame Copy Permalink