# Cut AI — Frontend Specification (Nuxt 4 · Gemini-First)

## 1. 專案定位
Cut AI 是一個「一站式 AI 影像製作工具」的前端應用。
本專案以 **真實 AI（Gemini）即時產出** 為核心，不使用 mock data。

核心原則：
- 真實 AI 結果優先
- 架構穩定、可長期演進
- 前端作為 AI Orchestrator，而非單純 UI

---

## 2. 既有技術基底（已鎖定）

```json
{
  "nuxt": "^4.2.2",
  "vue": "^3.5.x",
  "vue-router": "^4.x"
}
```

---

## 3. Dependency 使用政策（兩階段制）

### 3.1 規劃階段（Planning Phase）
- 允許「討論」是否需要新增 dependency
- 僅限提出建議與理由
- **不得實際安裝或引入**

### 3.2 實作階段（Execution Phase）
- ❌ 禁止新增任何 dependency
- ❌ 禁止隱性引入（UI library / helper library）
- ✅ 僅使用既有 dependency 與原生能力

> 一旦進入實作階段，dependency 清單視為「鎖定狀態」。

---

## 4. AI Provider 策略

### Primary
- **Gemini API**
- 預設唯一啟用

### Secondary（預留）
- Grok API
- 僅保留 client 與切換能力，不預設啟用

---

## 5. Token 管理（前端）

- Token 由使用者於設定頁手動輸入
- 儲存於 localStorage
  - `ai_token_gemini`
  - `ai_token_grok`
- 不 hardcode token
- 不驗證 token 正確性（由 API 回傳錯誤）

---

## 6. 專案目錄結構（建議）

```
/components
  /base
  /cards
  /layout

/pages
  index.vue
  /app
    dashboard.vue
    ai-storyboard.vue
    ai-camera.vue
    sora-director.vue
    cut-agent.vue
    settings.vue

/composables
/utils
/types
```

---

## 7. 鏡頭語言系統（Camera Language System）

鏡頭語言為 **AI 知識層**，非 UI 邏輯。
前端不硬編、不限制，僅結構化呈現 Gemini 的選擇。

### 7.1 鏡頭與景別（Shot Size & Lens）
- Extreme Long Shot (XLS / ELS)
- Long Shot (LS)
- Medium Shot (MS)
- Close-Up (CU)
- Extreme Close-Up (ECU)
- Over-the-Shoulder Shot (OTS)
- Point of View (POV)

### 7.2 運鏡（Camera Movement）
- Pan
- Tilt
- Dolly In / Dolly Out
- Truck / Tracking Shot
- Crane / Boom
- Handheld
- Dolly Zoom / Vertigo Effect

### 7.3 分鏡構圖（Composition & Storyboarding）
- Rule of Thirds
- Leading Lines
- Depth of Field（Shallow / Deep）
- Dutch Angle / Canted Angle
- Headroom / Look Room
- 180-degree Rule

### 7.4 光線（Lighting & Tone）
- Three-Point Lighting（Key / Fill / Back）
- High Key
- Low Key
- Hard Light
- Soft Light
- Practical Light

---

## 8. 頁面功能規格

### 8.1 Landing Page（/pages/index.vue）
- 專案介紹
- 功能卡片（靜態）
- CTA → Dashboard

### 8.2 Dashboard（/pages/app/dashboard.vue）
- 工具入口卡片
- 不顯示 AI 結果

### 8.3 Settings（/pages/app/settings.vue）
- Gemini API Key
- Grok API Key（optional）
- Provider 切換

### 8.4 AI 分鏡表
- 輸入故事、風格、節奏
- Gemini 回傳真實分鏡結果
- 以卡片顯示

### 8.5 AI 攝影機
- 上傳圖片
- Gemini 回傳鏡位與運鏡建議

### 8.6 Sora 導演
- 一句話 prompt
- Gemini 回傳影片規劃文字

### 8.7 Cut Agent
- 素材 + 劇情
- Gemini 回傳剪輯建議

---

## 9. UI 原則
- 卡片導向
- 可讀性優先
- 不追求動畫
- 結構穩定、可擴充