Frontend V3 responsive production update

docs/adr/ADR-036-fastapi-strangler-not-frontend-prerequisite.md

@@ -0,0 +1,50 @@
+# ADR-036: FastAPI Strangler Migration，不作為前端 V3 前置條件
+
+Status: Accepted
+Date: 2026-05-12
+
+## Context
+
+前端 V3 視覺包已進入落地評估，同時出現「既然前端要一次到位，後端也應同步從 Flask 改為 FastAPI」的建議。
+
+現有系統的重資產集中在 Python：爬蟲、AI 學習鏈、Telegram bot、APScheduler、SQLAlchemy models、pgvector、AutoHeal 與多個 service 模組。FastAPI 若被定位為 HTTP layer 轉換，理論上可沿用大部分 Python 業務邏輯；但目前 `app.py`、`routes/` 與 Jinja 頁面仍承接大量 HTTP glue、template context、CSRF/session、錯誤處理與部分業務邏輯。
+
+同時，前端 V3 包內部分頁面仍有正式資料接線風險：若只為了視覺更新直接替換，就可能移除現有 PChome 比價、AI 挑品、歷史價格、AI 觀測台等真實功能，違反 CONSTITUTION 第 14.1 條。
+
+## Decision
+
+FastAPI 是可接受的中期目標，但不得作為前端 V3 落地的前置條件，也不得與前端視覺更新綁成同一個大爆炸工程。
+
+採用以下順序：
+
+1. 前端 V3 先在現有 Flask runtime 內落地，僅替換已確認接上真實資料、既有 route/API 與行為不退化的頁面。
+2. 對於會移除現有功能的 V3 prototype 頁，先拒絕替換，保留現行正式頁。
+3. 後端重構優先做 HTTP-agnostic service extraction：把 route 內資料組裝、查詢、匯出、狀態診斷逐步搬到 `services/`，讓 Flask route 變薄。
+4. FastAPI 僅能以 strangler pattern 漸進引入：新 API 或已抽乾的 API 可掛在新 app，經 OpenAPI contract、測試與 Nginx path split 驗證後再切流。
+5. 不採用 Node 重寫後端。Next.js 前端若需要型別，未來由 OpenAPI 產生 client/types，不以「前後端同語言」作為重寫理由。
+
+## Alternatives Considered
+
+### A. 前端 V3 與 FastAPI Phase 1 同時執行
+
+拒絕。這會同時改動 template/rendering、API boundary、auth/session、CSRF、Nginx、Docker、health check 與 deploy rollback。對目前生產系統而言，風險面過大，也會把原本可獨立驗收的 UI 工作變成跨層遷移。
+
+### B. 維持 Flask 永久不動
+
+拒絕作為長期結論。Flask 可繼續承接現有 Jinja/route，但 OpenAPI、型別 client、async API 與新前端資料邊界確實更適合用 FastAPI 承接。問題不是是否能換，而是何時、以什麼切面換。
+
+### C. Node/Next API 重寫
+
+拒絕。核心業務與自動化資產都在 Python，改 Node 等同重寫爬蟲、AI、排程、Telegram 與資料層，收益不足以抵銷風險。
+
+## Consequences
+
+- 前端 V3 可以立即繼續落地，但每頁必須通過真實資料與行為不退化檢查。
+- FastAPI migration 的第一步不是開新框架，而是清 route、補 contract、抽 services。
+- 若未來建立 `momo-fastapi` service，必須先有：
+  - endpoint inventory 與 owner mapping；
+  - auth/session/CSRF 或 token strategy；
+  - OpenAPI contract test；
+  - `/health`、production smoke、rollback plan；
+  - Nginx path split 只切已驗證 path。
+- Flask、Jinja 與 `templates/` 的刪除只能在所有對應頁面完成遷移並通過 smoke 後進行。

docs/adr/README.md

@@ -57,6 +57,7 @@
 | [033](ADR-033-rag-three-guardrails.md) | RAG 治理三護欄 — Promotion Gate / Firecrawl 資源 / BGE-M3 一致性（Owen v5.0 鐵律） | Accepted | 2026-05-03 |
 | [034](ADR-034-dynamic-model-router.md) | Caller × Context 動態 Model Router（短文 gemma3 / 複雜 SKU qwen3:14b / 重構 coder:32b） | Accepted | 2026-05-04 |
 | [035](ADR-035-cross-platform-market-campaign-intelligence.md) | 跨平台市場活動情報系統 | Accepted | 2026-05-06 |
+| [036](ADR-036-fastapi-strangler-not-frontend-prerequisite.md) | FastAPI Strangler Migration，不作為前端 V3 前置條件 | Accepted | 2026-05-12 |
 
 ## 規範
 

docs/memory/README.md

@@ -22,6 +22,7 @@
 | `project_phase3f_cleanup_roadmap.md` | ADR-017 執行矩陣與階段紅線 | 正在做 3f 模組化收尾時 |
 | `code_modularization_inventory_20260430.md` | Python 大檔盤點、分層規範與拆分工作項目 | 新增功能、拆大檔、審查是否違反模組化治理時 |
 | `schema_inventory_baseline.md` | DB 表分類與 drift 基線 | 要收斂 migration / ORM / raw SQL 真相時 |
+| `frontend_v3_handoff_20260512.md` | 前端 V3 守門落地、正式部署、UI/UX 響應式缺口與接續順序 | 新 session 接續前端 V3 全站 UI/UX、手機版確認、`/daily_sales` 或 `/edm` 修正與部署時 |
 
 ## 關聯 Guide
 

docs/memory/frontend_v3_handoff_20260512.md

@@ -0,0 +1,142 @@
+# Frontend V3 Handoff 2026-05-12
+
+## 目的
+
+這份 handoff 給下一個 Codex session 接續「前端 V3 全站 UI/UX 與響應式修正」使用。
+
+## 已完成
+
+- 已閱讀並遵守專案入口規則：`AGENTS.md`、`CONSTITUTION.md`、ADR-011 部署紅線、部署 SOP。
+- 已評估 Claude Code 的「立刻 Flask → FastAPI」建議，結論改為：
+  - FastAPI 可作為 strangler migration 中期方向。
+  - 不作為前端 V3 落地前置條件。
+  - 不做大爆炸式後端重寫。
+- 已新增 `docs/adr/ADR-036-fastapi-strangler-not-frontend-prerequisite.md`，並更新 `docs/adr/README.md`。
+- 已把 V3 shell/tokens/page assets 落到 Flask runtime：
+  - `templates/ewoooc_base.html`
+  - `templates/components/_ewoooc_shell.html`
+  - `web/static/css/ewoooc-tokens.css`
+  - `web/static/css/ewoooc-shell.css`
+  - `web/static/css/ewoooc-dotmatrix.css`
+  - `web/static/css/ewoooc-tokens-v2-alias.css`
+  - 多個 `web/static/css/page-*.css`
+  - 多個 `web/static/js/page-*.js`
+- 已保留真實功能頁，拒絕直接用 `production_v3 3/templates/dashboard.html` 與 observability prototype 覆蓋正式頁，因為會移除 PChome、AI 挑品、歷史價格、觀測台真實資料。
+- 已修 `/sales_analysis` 首次進頁錯誤：
+  - `routes/sales_routes.py` 補 `category_data=cat_data`。
+  - `templates/sales_analysis.html` 對 chart JSON payload 補 default fallback，避免 Jinja `Undefined` 進 `tojson`。
+- 已同步版本：
+  - `app.py` `SYSTEM_VERSION = "V10.91"`
+  - `config.py` `SYSTEM_VERSION = "V10.91"`
+- 已更新 `TODO_NEXT_STEPS.txt`，記錄 V3 守門落地、正式推版與後續 FastAPI inventory。
+
+## 已部署到正式環境
+
+- 正式 URL：`https://mo.wooo.work`
+- 部署方式：白名單 tarball 同步 55 個 V3 runtime 檔案，再單獨同步 `config.py`。
+- 正式端只 recreate `momo-app`：
+  - `docker compose up -d --no-deps --force-recreate momo-app`
+- 未碰 `momo-db`。
+- 未使用 `--remove-orphans`。
+- 正式回滾備份：
+  - runtime files：`/tmp/codex_v3_predeploy_20260512_144835.tgz`
+  - config：`/tmp/config.py.pre_v3_20260512_145111`
+
+## 已通過驗證
+
+- 本機 focused pytest：`75 passed, 1 warning`。
+- `git diff --check` 通過。
+- `./scripts/quick_review.sh --check-observability-css` 通過。
+- `./scripts/quick_review.sh --observability-ui` 通過。
+- `./scripts/quick_review.sh --observability-qa --skip-production` 通過。
+- 正式：
+  - `https://mo.wooo.work/health` 回報 `V10.91`。
+  - `momo-pro-system`、`momo-scheduler`、`momo-telegram-bot`、`momo-db` 全部 healthy。
+  - `./scripts/quick_review.sh --observability-qa --base-url https://mo.wooo.work` 通過。
+  - V3 smoke 200：`/sales_analysis`、`/daily_sales`、`/monthly_summary_analysis`、`/ai_recommend`、`/auto_import`、`/vendor-stockout/*`、`/growth_analysis`、`/settings`、`/logs`、`/`。
+
+## 2026-05-12 V10.92 追更
+
+- 已完成 `/daily_sales` 本機 route 驗證與 responsive 修正。
+- 已完成 `/edm` 桌機外溢與 mobile responsive containment 修正。
+- 已將 V3 內容最大寬度調整為 `1600px`，改善寬螢幕活動頁與資料表使用空間。
+- 已移除 V3 主要頁面 CSS 中殘留的負字距。
+- 已新增全頁 responsive overflow 自動化：
+  - `scripts/check_v3_responsive_ui.js`
+- 本機全頁 responsive audit 已通過，覆蓋 23 個主要 route，desktop 1440 與 mobile 390 共 46 項皆 PASS。
+- 本機 observability QA 已通過：
+  - focused pytest `75 passed, 1 warning`
+  - `git diff --check`
+  - `scripts/check_v3_responsive_ui.js`
+- 已白名單部署到正式環境 `https://mo.wooo.work`，版本升至 `V10.92`。
+- 正式端只 recreate `momo-app`：
+  - `docker compose up -d --no-deps --force-recreate momo-app`
+- 未碰 `momo-db`，未使用 `--remove-orphans`。
+- 正式回滾備份：
+  - `/tmp/codex_v3_1092_predeploy_20260512_164549.tgz`
+- 正式驗證已通過：
+  - `/health` 回報 `V10.92`。
+  - `momo-pro-system`、`momo-scheduler`、`momo-telegram-bot`、`momo-db` 全部 healthy。
+  - `scripts/check_v3_responsive_ui.js` 對 `https://mo.wooo.work` 通過：23 route × desktop/mobile = 46/46 PASS。
+  - `./scripts/quick_review.sh --observability-qa --base-url https://mo.wooo.work` 通過。
+
+## 重要使用提醒
+
+- 不要用 `file://.../templates/*.html` 預覽 Jinja 模板。它需要 Flask route 注入 `url_for()`、context 與 session。
+- 正確本機預覽方式：
+  - 啟動 Flask：`LOGIN_PASSWORD=codex-local-password SECRET_KEY=codex-local-secret USE_POSTGRESQL=false .venv/bin/flask --app app:app run --host 127.0.0.1 --port 5003`
+  - 用瀏覽器開：`http://127.0.0.1:5003/daily_sales`、`http://127.0.0.1:5003/edm` 等 route。
+- 使用 Browser plugin 時，應導到 localhost route，不要開 template 檔。
+
+## 未完成
+
+- 使用者指出「很多頁面排版都有問題，且必須全部確認手機版」。
+- `/daily_sales`、`/edm`、全頁 responsive overflow 自動化與 V10.92 正式部署已完成。
+- 尚未完成所有頁面的人工 desktop/mobile 視覺逐頁設計審查；目前完成的是自動化 overflow guard 與重點頁抽看。
+- 若下一輪繼續 UI/UX，建議從「自動化已過但人工視覺仍需精修」的頁面開始，例如長表格密度、空狀態、文案層級與 mobile 互動細節。
+
+## 下一個 session 建議順序
+
+1. 啟動本機 Flask server，導 in-app browser 到目標 route。
+2. 用 desktop 與 mobile 寬度檢查：
+   - 1365/1440 desktop
+   - 390 mobile
+   - 不得有 body horizontal overflow。
+   - text 不得重疊或被裁切。
+   - 表格/日曆若需要橫向滾動，必須有明確容器與提示，不能讓整頁外溢。
+3. 每輪 UI 變更後跑全頁 responsive overflow guard：`scripts/check_v3_responsive_ui.js`，至少覆蓋：
+   - `/`
+   - `/edm`
+   - `/sales_analysis`
+   - `/daily_sales`
+   - `/monthly_summary_analysis`
+   - `/growth_analysis`
+   - `/ai_recommend`
+   - `/auto_import`
+   - `/vendor-stockout/`
+   - `/vendor-stockout/import`
+   - `/vendor-stockout/list`
+   - `/settings`
+   - `/logs`
+   - `/observability/*` 10 頁
+4. 全頁本機 QA 通過後，才按部署 SOP 白名單同步正式。
+
+## 當前工作樹注意事項
+
+- 工作樹很髒，混有多批未提交變更與大量 untracked 原型/文件/前端資料夾。
+- 不要整包 rsync 或整包 commit。
+- 不要 revert 使用者或其他 session 的變更。
+- 部署只能用白名單。
+- 特別避免同步：
+  - `.claude/`
+  - `production_v3*/`
+  - `frontend/`
+  - `MOMO Pro/uploads/`
+  - `data/dashboard_full_cache.pkl`
+  - 未確認的 docs/design dump
+
+## 已知本機/正式 warning
+
+- 本機 Python 3.9 / LibreSSL 會有 urllib3 warning。
+- 本機 SQLite 缺 `embedding_retry_queue` 時 OCLearn worker 會 warning。
+- 正式 compose 會警告 `momo-db` orphan，這是 ADR-011 已知狀態，禁止 `--remove-orphans`。