ewoooc/docs/guides/frontend_upgrade_roadmap.md

EwoooC 前端更版推進路線圖

建立日期：2026-04-30 依據：MOMO Pro/HANDOFF.md、MOMO Pro/design-tokens.css、MOMO Pro/app/*.jsx、現有 templates/ 與 routes/ 使用者確認：後續前端視覺呈現風格與 UI/UX，以 MOMO Pro/ 新版本為主要依據。

1. 目標

將 MOMO Pro/ 內的 EwoooC 後台原型落地到正式 Flask 系統，先完成使用者可感知的新版後台殼層與核心頁，再逐步整理 API 與模板結構。

本次更版的視覺方向以原型為準：

• 米色工作台背景、暖墨文字、焦糖橘 accent。
• 側邊欄 + 頂部工具列取代目前頂部橫向 navbar。
• 數字、ID、時間、價格使用等寬字體。
• Dashboard 採「監控總覽 / 焦點數據 / 商品列表」工作台結構。
• 表格改為安靜米色表頭，不延續舊紫藍漸層表頭。
• 新增或改版頁面不得再以舊紫藍 Bootstrap 後台作為主要視覺基準。
• 所有頁面內容必須使用真實資料來源；禁止用 mock data、假頁面或展示用 placeholder 冒充完成。

2. 現況判斷

目前正式系統不是 React / Next.js，而是 Flask + Jinja + Bootstrap：

• 主入口：app.py
• 核心路由：routes/dashboard_routes.py、routes/edm_routes.py、routes/vendor_routes.py
• 主要模板：templates/dashboard.html、templates/edm_dashboard.html、templates/base.html、templates/components/_navbar.html
• 廠商缺貨模板另在：web/templates/vendor_stockout/

重要限制：

• 多數頁面不是繼承 base.html，而是各自包含完整 HTML、CSS 與 navbar include。
• templates/dashboard.html、templates/edm_dashboard.html、templates/sales_analysis.html、templates/daily_sales.html 都是大型獨立頁。
• 因此不適合一開始就全站硬切 Next.js，也不適合只改 base.html 期待全站換版。

3. 技術路線

採「Flask 先落地、API 漸進抽離、React/Next.js 延後決策」：

1. 第一階段先在現有 Flask/Jinja 內實作新版 design tokens、shell 與 Dashboard。
2. 第二階段將活動看板、商品列表、廠商缺貨等核心頁搬到同一套 shell 與元件樣式。
3. 第三階段把頁面需要的資料整理成 JSON API，讓日後要切 React/Next.js 時已有清楚資料邊界。
4. 若正式引入 Next.js、TanStack Query、Tailwind 等新前端建置系統，需另立 ADR。

這樣做的好處是可以快速讓正式系統出現新版前端，同時避免一次改動部署架構、認證、API、模板與容器。

MOMO Pro/ 目錄定位為「最新前端原型來源」，不是正式 Flask runtime 依賴。正式落地時只抽取必要的設計 token、互動模式與版面結構到 web/static/css/、templates/、路由與測試；不把 prototype 的 React/Babel 工作檔直接部署成正式頁。待全站核心頁面同步完成後，再將 MOMO Pro/ 歸檔或移除，避免專案長期保留兩套前端真相來源。

4. 分階段工作

Phase 0：設計系統落地

目標：讓 Flask 模板可使用原型視覺語言。

建議檔案：

• 新增 static/css/ewoooc-tokens.css
• 新增 static/css/ewoooc-shell.css
• 新增 templates/components/_ewoooc_shell.html
• 保留 templates/components/_navbar.html 給尚未改版頁面使用

工作內容：

• 從 MOMO Pro/design-tokens.css 搬移 CSS variables。
• 定義 .momo-app、.momo-mono、.momo-label、button、badge、card、table、responsive 工具 class。
• 建立新版 sidebar/topbar Jinja 組件，對應現有路由：
  • 商品看板 /
  • 活動看板 /edm
  • 分析報表 /sales_analysis、/daily_sales、/growth_analysis、/monthly_summary_analysis
  • 廠商缺貨 /vendor-stockout
  • AI 助手 /ai_recommend、/ai_history
  • 雲端匯入 /auto_import
  • 系統管理相關頁

驗收：

• 桌面寬度 sidebar 固定，內容區可滾動。
• 手機寬度可折疊或轉為 drawer，不遮擋主要內容。
• 未改版頁面仍可正常載入。

Phase 1：Dashboard 第一版更版

目標：先替換使用頻率最高的商品看板。

建議檔案：

• 改造 templates/dashboard.html
• 視需要新增 templates/components/_product_table.html
• 視需要在 routes/dashboard_routes.py 補齊 template 欄位，不改既有價格邏輯

工作內容：

• 將原型 page-dashboard.jsx 轉成 Jinja + CSS：
  • 區塊 01：監控總覽 KPI
  • 區塊 02：焦點數據
  • 區塊 03：商品列表與篩選列
• 沿用現有後端篩選、排序、分頁參數：
  • q
  • category
  • filter
  • sort_by
  • order
  • page
• 商品圖片優先使用憲章規範的 CDN URL：
  • https://m.momoshop.com.tw/moscdn/goods/{i_code}_m.webp
• 保留既有通知、匯出、價格歷史 modal 或 API 行為。

驗收：

• / 在桌面與手機都可操作。
• 搜尋、分類、漲價、降價、新上架、下架篩選結果與舊版一致。
• 排序與分頁不退化。
• 價格漲跌邏輯不變，不碰 product.momo_id。

Phase 2：活動看板更版

目標：把促銷活動頁改為原型的 Campaigns 結構。

建議檔案：

• 改造 templates/edm_dashboard.html
• 視需要整理 routes/edm_routes.py 的頁面資料 shape

工作內容：

• 將五個活動頁整合成同一視覺：
  • 限時搶購 /edm
  • 1.1 狂歡 /festival
  • 母親節 /mothers_day
  • 520 情人節 /valentine_520
  • 勞動節 /labor_day
• 實作活動 segmented tabs、活動 hero、活動 KPI、限時搶購 timeline、分類 chips、商品列表。
• 手動更新、發送通知沿用既有 API，不改排程邏輯。

驗收：

• 五個活動入口都可進入。
• 現有 sort query 行為保留。
• 手動更新與通知按鈕不破壞 CSRF 與既有 API。

Phase 3：核心營運頁統一殼層

目標：讓常用營運頁進入新版 shell，但先不重寫全部細節。

推進順序：

1. templates/ai_intelligence.html / templates/ai_recommend.html / templates/ai_history.html
   • 原因：AI 挑品、PChome 比對、建議信心度與待補證據是目前商品看板下一步核心工作流。
   • 目標：新版 shell、AI 挑品清單、比對嘗試狀態、信心度證據缺口、操作回饋。
2. templates/auto_import_index.html
   • 原因：所有真實資料要完整入庫，匯入頁是營運資料進入系統的主要入口。
   • 目標：新版 shell、匯入批次狀態、錯誤列、最近匯入紀錄與資料表落點。
3. templates/sales_analysis.html / templates/daily_sales.html / templates/monthly_summary_analysis.html
   • 原因：AI 挑品信心度需要銷售額、銷量、成本、毛利等證據支撐。
   • 目標：保留原報表功能，改版為可掃描的營運分析工作台。
4. web/templates/vendor_stockout/index.html、list.html、import.html
   • 狀態：首頁、列表、匯入已先以 templates/vendor_stockout_*_v2.html 方式落地；後續補齊 history、vendor management、send email。
5. 系統管理相關頁：templates/settings.html、templates/system_settings.html、templates/user_management.html、templates/logs.html
   • 目標：新版 shell、設定群組化、狀態/權限/日誌統一呈現。
6. PChome / 趨勢 / 其他工具頁：templates/pchome_crawler.html、templates/price_comparison.html、templates/trends.html
   • 目標：接入新版 shell 與資料完整性狀態，不改核心爬蟲規則。

工作內容：

• 先移除各頁重複 navbar 與 body 背景，接入新版 shell。
• 表格、按鈕、badge 改用 tokens。
• 大型功能頁不要在同一 PR 同時重構 JS 行為。

驗收：

• 原本表單、匯入、寄信、批次操作可以正常執行。
• 手機版不出現文字重疊或表格爆版。

Phase 4：API 邊界整理

目標：為未來 React/Next.js 或更完整前端分離鋪路。

建議 API：

• GET /api/dashboard/summary
• GET /api/dashboard/focus
• GET /api/products
• GET /api/products/<i_code>
• GET /api/products/<i_code>/price-history
• GET /api/campaigns
• GET /api/campaigns/<campaign_id>
• GET /api/vendors/out-of-stock
• GET /api/schedule/status

注意：

• API 計算邏輯必須與 dashboard 現有 get_full_dashboard_data() / get_consolidated_data() 一致。
• 商品唯一識別使用 product.i_code。
• 不為了前端重寫而引入 N+1 查詢。

Phase 5：是否引入 React/Next.js 的決策

只有在以下條件成立時才啟動：

• Dashboard / Campaigns 已有穩定 JSON API。
• 認證與 CSRF 邊界已確認。
• Docker / CD pipeline 可承接 Node build。
• 已立 ADR，明確記錄 Flask-only、Hybrid、Next.js 分離三種方案取捨。

5. 首批建議任務

第一個實作批次建議控制在小而完整：

1. 新增 tokens 與 shell CSS。
2. 新增 _ewoooc_shell.html，但不替換舊 navbar。
3. 新增一份新版 dashboard template 草稿，先掛在內部測試路由或 feature flag。
4. 用同一份後端真實資料渲染新版 Dashboard，不建立假商品或假統計。
5. 本機以瀏覽器檢查桌面與手機 viewport。

完成後再決定是否將 / 切到新版。

6. 驗收清單

• 全 UI 文字使用繁體中文。
• 桌面、平板、手機三種寬度都能操作。
• 表格可橫向滾動，文字不重疊。
• 漲價、降價、下架、新品數字與舊版一致。
• 通知、手動更新、匯出、排序、分頁等既有行為不退化。
• 修改後檢查 logs/system.log 無新增錯誤。
• 重大更新前依憲章執行備份；正式部署遵守 ADR-011 與部署 SOP。

7. 不做事項

• 不在第一批直接引入 Next.js。
• 不在第一批重寫所有模板。
• 不在 UI 更版時改價格計算、爬蟲邏輯或資料庫 schema。
• 不使用 docker compose ... --remove-orphans。
• 不影響 momo-db 容器生命週期。