ewoooc/docs/memory/frontend_v3_handoff_20260512.md

# 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` 通過。

## 2026-05-13 V10.115 main 追更

- main 已補 AI 觀測台 V3 responsive / overflow 守門：
  - `scripts/check_responsive_overflow.js` 會把 visual overflow offenders 視為失敗。
  - 表格與圖表允許在 `.obs-table-shell`、`.obs-chart-frame` 等局部容器內滾動，避免整頁水平外溢。
- `observability-system.css` 與 Flask mirror `web/static/css/observability-system.css` 已同步補強：
  - bounded table/chart/mobile containment。
  - badge / pill / nested surface 對比規範。
  - hero / panel 密度收斂，避免 inline legacy template 保留裝飾空白。
- 本機 QA 已通過：
  - `python3 scripts/sync_observability_css.py --check`
  - `./scripts/quick_review.sh --observability-ui`
  - `./scripts/quick_review.sh --observability-qa --skip-production`
  - focused frontend / Phase 3f pytest。
- 本段只記錄 main repo 推版與本機 QA；未在本段宣稱正式環境已完成 V10.115 部署驗證。

## 2026-05-13 V10.116 main 追更

- main 已補 AI 觀測台 rendered visual contract：
  - `scripts/check_observability_visual_contract.js`
  - `scripts/check_observability_visual_contract.sh`
  - `./scripts/quick_review.sh --observability-visual`
  - `scripts/check_observability_suite.sh` 在 production smoke 後有第 4 步；`--skip-production` 時會明確 skip rendered visual contract。
- 觀測台手機密度與商業情報頁 title/chip 對比已補強，`templates/admin/business_intel.html` 的 H1 已有 `biz-title` class，V10.116 main 版的 local rendered contract 已覆蓋 10 頁 × desktop/tablet/mobile 30 項 PASS。
- 本機 SQLite visual QA 曾因 `/observability/host_health` GET 頁嘗試寫 `host_health_probes` 而噴 BIGINT autoincrement warning；main 已改為 SQLite session 下略過 probe persistence，正式 Postgres 路徑仍保留寫入。
- 本段只記錄 main repo 推版與本機 QA；未在本段宣稱正式環境已完成 V10.116 部署驗證。

## 2026-05-13 V10.117 main 追更

- AI 觀測台已改成 tokenized dot-matrix 背景語彙，`scripts/check_observability_visual_contract.js` 會檢查 hero/signal/panel surface 的 rendered `background-image` 必須是 `radial-gradient`，並防止 legacy `linear-gradient` 或 `background-image: none` 回流。
- `static/css/observability-system.css` 檔尾保留 terminal dot-matrix layer；不要把它移回 v3.4/v3.5 neutralizer 之前，否則 computed style 會被後段 `background-image: none !important` 覆蓋。
- 本機 `http://127.0.0.1:5017` 已重跑 rendered visual contract，10 頁 × desktop/tablet/mobile 共 30 項 PASS。

## 重要使用提醒

- 不要用 `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`。