wooo/ewoooc
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity
Files
dev
ewoooc/docs/memory/frontend_v3_handoff_20260512.md
OoO 754dc60695 記錄 V10.117 觀測台點陣契約
2026-05-13 18:57:14 +08:00

9.3 KiB
Raw Permalink Blame History

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。
Reference in New Issue View Git Blame Copy Permalink