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` 容器生命週期。