# 🌐 Web端組件架構設計指南

## 📋 文檔概述

**文檔名稱**: Drama Ling Web端組件架構設計指南  
**建立日期**: 2025-09-12  
**目標受眾**: 前端工程師、UI/UX設計師、產品經理  
**技術基礎**: HTML5 + CSS3 + Modern JavaScript

## 🎯 設計原則

### 🖥️ **桌面優先設計**
- **多任務並行**: 支援同時開啟多個學習模組
- **大螢幕利用**: 充分使用桌面螢幕空間
- **快捷鍵支援**: 提供完整的鍵盤操作體驗
- **即時回饋**: 無需頁面刷新的流暢互動

### 📐 **響應式策略**
- **桌面優先**: 1200px+ 主要設計目標
- **平板適配**: 768px-1199px 簡化佈局
- **手機兼容**: 320px-767px 降級體驗

## 🏗️ 組件架構層級

### 1️⃣ **佈局組件 (Layout Components)**

#### `WebLayout_Main`
```html
<div class="web-layout-main">
  <header class="web-header">
    <WebHeader_Navigation />
    <WebHeader_UserStatus />
  </header>
  
  <aside class="web-sidebar">
    <WebSidebar_Menu />
    <WebSidebar_Progress />
  </aside>
  
  <main class="web-content">
    <WebContent_Area />
  </main>
</div>
```

**設計特色**:
- **固定頭部**: 命條、通知、用戶資訊常駐
- **可摺疊側邊欄**: 學習進度、快速導航
- **主內容區**: 彈性佈局，支援多視窗

#### `WebLayout_Modal`
```html
<div class="web-modal-overlay">
  <div class="web-modal-container">
    <WebModal_Header />
    <WebModal_Content />
    <WebModal_Actions />
  </div>
</div>
```

### 2️⃣ **功能組件 (Feature Components)**

#### `WebLearning_VocabPanel`
```html
<div class="web-vocab-panel">
  <div class="vocab-stages-overview">
    <WebStage_Level1 status="completed" />
    <WebStage_Level2 status="current" />
    <WebStage_Level2Plus status="locked" />
    <WebStage_Level3 status="locked" />
  </div>
  
  <div class="vocab-current-content">
    <WebVocab_Display />
    <WebVocab_AudioControls />
    <WebVocab_Examples />
  </div>
</div>
```

**Web端特色**:
- **四關同屏**: 同時顯示所有關卡狀態
- **即時切換**: 無縫在關卡間切換
- **詳細資訊**: 顯示更多學習數據

#### `WebLearning_DialoguePanel`
```html
<div class="web-dialogue-panel">
  <div class="dialogue-character-info">
    <WebCharacter_Avatar />
    <WebCharacter_Details />
  </div>
  
  <div class="dialogue-conversation">
    <WebDialogue_Messages />
    <WebDialogue_InputArea />
  </div>
  
  <div class="dialogue-assistance">
    <WebAssistance_Panel />
    <WebAnalysis_Feedback />
  </div>
</div>
```

### 3️⃣ **交互組件 (Interactive Components)**

#### `WebInput_Smart`
```html
<div class="web-input-smart">
  <input class="smart-input-field" />
  <div class="smart-suggestions">
    <WebSuggestion_Item />
  </div>
  <div class="smart-shortcuts">
    <kbd>Tab</kbd> 接受建議
    <kbd>Ctrl+Enter</kbd> 送出
  </div>
</div>
```

**Web端增強**:
- **快捷鍵提示**: 顯示可用快捷鍵
- **智能建議**: 即時顯示輸入建議
- **多行支援**: 支援長段對話輸入

## 📊 組件狀態管理

### 🔄 **狀態架構**
```javascript
// Web端狀態管理
const WebStateManager = {
  // 學習狀態
  learning: {
    currentStage: 'vocab-level1',
    progress: { level1: 80, level2: 60, level3: 0 },
    activeWindows: ['vocab', 'dialogue']
  },
  
  // UI狀態  
  ui: {
    sidebarCollapsed: false,
    activeModals: [],
    shortcuts: true,
    theme: 'dark'
  },
  
  // 用戶狀態
  user: {
    lifePoints: 5,
    diamonds: 150,
    streak: 7
  }
}
```

### 📡 **數據流向**
```mermaid
flowchart TD
    A[用戶操作] --> B[組件事件]
    B --> C[狀態管理器]
    C --> D[API調用]
    D --> E[後端回應]
    E --> C
    C --> F[組件重渲染]
    F --> G[UI更新]
```

## 🎨 視覺設計標準

### 🖼️ **佈局網格**
```css
.web-container {
  display: grid;
  grid-template-columns: 280px 1fr; /* 側邊欄 + 主內容 */
  grid-template-rows: 80px 1fr;     /* 頭部 + 內容區 */
  min-height: 100vh;
}

.web-content-area {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(400px, 1fr));
  gap: var(--space-6);
  padding: var(--space-6);
}
```

### 🎯 **互動狀態**
```css
/* Web端特有的懸停效果 */
.web-interactive:hover {
  transform: translateY(-2px);
  box-shadow: 0 8px 25px rgba(0, 229, 204, 0.3);
  transition: all 0.3s ease;
}

/* 聚焦狀態 */
.web-focusable:focus {
  outline: 2px solid var(--primary-teal);
  outline-offset: 2px;
}
```

## ⌨️ 快捷鍵系統

### 🔤 **全域快捷鍵**
```javascript
const WebShortcuts = {
  'Ctrl+1': () => navigateToStage('vocab-level1'),
  'Ctrl+2': () => navigateToStage('vocab-level2'),  
  'Ctrl+3': () => navigateToStage('dialogue'),
  'Space': () => playAudio(),
  'Ctrl+Enter': () => submitAnswer(),
  'Escape': () => closeModal(),
  'Ctrl+/': () => showShortcutHelp()
}
```

### 📝 **上下文快捷鍵**
```javascript
// 詞彙學習專用
const VocabShortcuts = {
  '←/→': () => switchWord(),
  'R': () => repeatAudio(),
  '1-4': () => selectAnswer(),
  'N': () => nextQuestion()
}

// 對話練習專用  
const DialogueShortcuts = {
  'Ctrl+H': () => showHint(),
  'Ctrl+T': () => translateMessage(),
  'Ctrl+R': () => requestAssistance()
}
```

## 🔧 開發規範

### 📦 **組件命名**
```javascript
// 組件命名規範
WebComponent_功能名稱     // 主要組件
WebLayout_佈局類型       // 佈局組件  
WebModal_彈窗類型        // 彈窗組件
WebInput_輸入類型        // 輸入組件
```

### 🗂️ **檔案結構**
```
src/web/
├── components/
│   ├── layout/          # 佈局組件
│   │   ├── WebLayout_Main.js
│   │   └── WebLayout_Modal.js
│   ├── learning/        # 學習功能組件
│   │   ├── WebLearning_VocabPanel.js
│   │   └── WebLearning_DialoguePanel.js
│   └── common/          # 通用組件
│       ├── WebInput_Smart.js
│       └── WebButton_Action.js
├── styles/
│   ├── web-layout.scss  # 佈局樣式
│   ├── web-components.scss # 組件樣式
│   └── web-responsive.scss # 響應式樣式
└── utils/
    ├── web-shortcuts.js # 快捷鍵管理
    └── web-state.js     # 狀態管理
```

## 🎮 實際範例：詞彙學習頁面

### 📱 **Mobile版結構**
```html
<!-- 手機版：單一焦點，垂直流程 -->
<div class="mobile-vocab-page">
  <header>當前: 詞彙1/5</header>
  <main>
    <div class="vocab-card">單個詞彙展示</div>
  </main>
  <footer>
    <button>上一個</button>
    <button>下一個</button>
  </footer>
</div>
```

### 💻 **Web版結構**
```html
<!-- Web版：多資訊同屏，橫向佈局 -->
<div class="web-vocab-page">
  <aside class="stages-sidebar">
    <div class="stage stage-completed">第1關 ✓</div>
    <div class="stage stage-current">第2關 ⟲</div>
    <div class="stage stage-locked">第2+關 🔒</div>
    <div class="stage stage-locked">第3關 🔒</div>
  </aside>
  
  <main class="vocab-content">
    <div class="vocab-overview">
      <div class="vocab-list">5個詞彙預覽</div>
      <div class="progress-indicator">進度: 3/5</div>
    </div>
    
    <div class="vocab-detail">
      <div class="current-vocab">當前詞彙詳細資訊</div>
      <div class="audio-controls">音頻控制面板</div>
      <div class="examples">例句和語境</div>
    </div>
  </main>
  
  <aside class="tools-panel">
    <div class="shortcuts-help">快捷鍵提示</div>
    <div class="statistics">學習統計</div>
  </aside>
</div>
```

## 📏 響應式設計指南

### 🖥️ **桌面版** (1200px+)
- **三欄佈局**: 側邊欄 + 主內容 + 工具欄
- **豐富互動**: 懸停效果、快捷鍵提示
- **詳細資訊**: 完整統計、進度可視化

### 📱 **平板版** (768px-1199px)  
- **兩欄佈局**: 可摺疊側邊欄 + 主內容
- **簡化工具欄**: 整合到主內容區
- **觸控優化**: 增大點擊區域

### 📱 **手機版** (320px-767px)
- **單欄佈局**: 全螢幕主內容
- **底部導航**: Tab式導航
- **簡化功能**: 保留核心功能

---

**維護提醒**: 當添加新的Web端功能時，請確保更新此架構文檔並遵循既定的組件設計原則。

**最後更新**: 2025-09-12  
**版本**: v1.0  
**維護者**: Drama Ling Web開發團隊