first commit

docs/frontend/FRONTEND_ARCHITECTURE_SPEC.md

@@ -0,0 +1,51 @@
+# Frontend Architecture Spec
+
+## 目標
+
+定義 `mkt.ose.tw/frontend` 的主線架構，讓實驗管理與 Visual Editor 可長期維護。
+
+## 技術基底
+
+- Vue 3
+- Element Plus
+- Vuex
+- Vite
+
+## 分層原則
+
+### app / shell
+
+- 路由骨架、layout、全域導航
+
+### module
+
+- 依業務模組切分：dashboard、experiment、variant、release、editor
+
+### service / api client
+
+- 集中 API 呼叫邏輯
+- 不在頁面內直接寫散落請求
+
+### state
+
+- 僅放跨頁狀態與 session
+- 頁面暫存留在模組內
+
+## 主線與 legacy 邊界
+
+- `experiment / variant / release / editor` 為主線
+- `ose-card / conutdown-timer` 為 legacy 過渡模組
+- 新功能不再掛到 legacy 路徑
+
+## API 邊界
+
+- Frontend 主入口為 FastAPI
+- Directus 保留在登入與既有相容路線
+- 不再新增頁面直接耦合 Directus raw response
+
+## 近期重點
+
+- Editor 穩定化（選取、編輯、結構、history）
+- 管理流補齊（create/edit/build/publish/rollback）
+- 逐步收斂語言與操作流程（流程化、簡單化、中文化）
+

docs/frontend/FRONTEND_ENV_SETUP.md

@@ -0,0 +1,48 @@
+# Frontend Env Setup
+
+## 目前 frontend 主線
+
+- `mkt.ose.tw/frontend` 為主線前端
+- 技術棧：`Vue 3 + Element Plus + Vuex + Vite`
+- API 正在由 Directus 逐步收斂到 FastAPI
+
+## env 來源
+
+```text
+frontend/env/.env.development
+frontend/env/.env.production
+frontend/env/.env.local
+```
+
+`vite.config.js` 目前允許：
+
+- `VITE_*`
+- `_*`（相容用途）
+
+## 建議欄位
+
+```env
+VITE_DIRECTUS_BASE_URL=https://mktcms.ose.tw
+VITE_MKTAPI_BASE_URL=https://mktapi.ose.tw
+VITE_DIRECTUS_DEBUG_TOKEN=
+```
+
+## local 建議
+
+```env
+VITE_DIRECTUS_BASE_URL=https://mktcms.ose.tw
+VITE_MKTAPI_BASE_URL=http://127.0.0.1:8011
+VITE_DIRECTUS_DEBUG_TOKEN=
+```
+
+## 舊欄位相容
+
+仍相容舊欄位：
+
+```env
+_API_URL
+_API_TOKEN
+```
+
+但新程式應以統一 config 與 service 層讀取，不在頁面直接散讀 env。
+

docs/frontend/LEGACY_MODULES_PLAN.md

@@ -0,0 +1,28 @@
+# Legacy Modules Plan
+
+## 目標
+
+定義 legacy 模組的過渡策略，避免影響主線「銷售實驗 + visual editor」進度。
+
+## 目前定位
+
+- `ose-card`：保留運作，延後深重構
+- `conutdown-timer`：保留運作，延後深重構
+
+## 原則
+
+- 主線開發不再往 legacy 模組新增核心能力
+- 新功能優先掛到 experiment / variant / release / editor 主線
+- legacy 僅做必要修補與相容調整
+
+## 遷移策略
+
+1. 先抽規則，不先大搬資料表
+2. 舊模組能力逐步以 FastAPI 主線接口承接
+3. 最後再做資料歸屬與 UI/UX 大重構
+
+## 何時啟動深重構
+
+- 當 editor 主幹、管理流、runtime 主線穩定後
+- 有明確商業需求才開新一輪 legacy 深拆
+

docs/frontend/VISUAL_EDITOR_SPEC.md

@@ -0,0 +1,68 @@
+# Visual Editor Spec
+
+## 目標
+
+提供行銷可直接操作的同頁編輯體驗，對齊 Google Optimize / Optimize99 的使用感。
+
+## 核心互動規則
+
+### 1. 選取回饋
+
+- hover 顯示藍色虛線框
+- selected 顯示藍色實線框
+- 滑鼠移動時可快速預覽可選區域
+
+### 2. 直接編輯
+
+- 點選元素後可直接開啟編輯泡泡
+- 支援文字、按鈕文字、按鈕連結、圖片來源、樣式
+- 編輯為即時同步（不用再按套用）
+
+### 3. 結構操作
+
+- 上移 / 下移 / 拖移
+- 隱藏 / 顯示
+- 複製 / 刪除
+- 前插 / 後插
+
+### 4. 歷史機制
+
+- 內容編輯與結構操作都必須可 undo/redo
+- restore 後畫布狀態、選取狀態、泡泡狀態要一致
+
+## 編輯泡泡規格
+
+- 可拖拉、可關閉、固定於視窗可用位置
+- Header 保持簡潔：拖拉點 + 關閉
+- 內容區為可捲動區塊
+- icon hover 要有 tooltip（清楚告知作用）
+
+## Bridge Protocol（頁面與 editor）
+
+### page -> editor
+
+- ready
+- hover/selection 變更
+- structure change 結果
+- history 狀態更新
+
+### editor -> page
+
+- focus selector
+- start inline edit
+- set text / attr / style
+- structure actions
+- restore state
+
+## Selector 與定位策略
+
+- 頁面載入時補唯一 `data-mkt-selector`
+- 插入與複製後重建 selector，避免衝突
+- 相似兄弟節點必須可各自選取
+
+## 不做事項（此階段）
+
+- 不走 Chrome Extension 路線
+- 不增加大型資訊面板干擾畫面
+- 不先做自由版面拖拉排版（以區塊重排為主）
+