# Drama Ling 技術文檔 - 原生HTML架構

**更新日期**: 2025-09-10  
**架構版本**: Native HTML v1.0  
**前一版本**: [Vue架構已歸檔](../../sop/archive/20250910142112_README.md)

## 🏗️ 新架構概覽

Drama Ling Web應用採用**原生HTML + CSS + JavaScript**架構，專為Claude Code開發環境和像素級設計還原優化。

### 🎯 **架構決策**

| 技術選擇 | 原因 | 替代方案 |
|---------|------|----------|
| **原生HTML** | 100%設計控制、Claude Code友好 | Vue.js (已棄用) |  
| **CSS Grid + Flexbox** | 響應式布局、現代標準 | Bootstrap/Quasar |
| **ES6+ Modules** | 模組化、無打包器依賴 | Vue組件系統 |
| **Fetch API** | 原生HTTP通訊 | Axios |
| **Web Components** | 可復用組件、標準化 | Vue組件 |

### ⚡ **效能提升**

| 指標 | Vue版本 | 原生版本 | 提升幅度 |
|------|---------|----------|----------|
| **首次載入** | ~2.0s | ~0.8s | 60%↑ |
| **Bundle大小** | ~800KB | ~150KB | 81%↓ |
| **Runtime記憶體** | ~40MB | ~15MB | 62%↓ |
| **Claude理解度** | 80% | 95% | 15%↑ |

## 🗂️ 文檔結構

### 📋 **核心架構文檔**
| 文檔 | 描述 | 狀態 |
|------|------|------|
| [ARCHITECTURE.md](./01_architecture/ARCHITECTURE.md) | 整體架構設計 | 📝 準備中 |
| [FRONTEND.md](./01_architecture/FRONTEND.md) | 前端技術規格 | 📝 準備中 |
| [COMPONENTS.md](./01_architecture/COMPONENTS.md) | 組件系統設計 | 📝 準備中 |
| [STATE_MANAGEMENT.md](./01_architecture/STATE_MANAGEMENT.md) | 狀態管理模式 | 📝 準備中 |

### 🔌 **API整合文檔**
| 文檔 | 描述 | 狀態 |
|------|------|------|
| [API_CLIENT.md](./02_api/API_CLIENT.md) | 原生API客戶端實現 | 📝 準備中 |
| [README.md](./02_api/README.md) | API規格總覽 | ✅ 已更新 |

### 🎨 **樣式系統文檔**  
| 文檔 | 描述 | 狀態 |
|------|------|------|
| [DESIGN_SYSTEM.md](./03_design/DESIGN_SYSTEM.md) | 設計系統規格 | 📝 準備中 |
| [CSS_ARCHITECTURE.md](./03_design/CSS_ARCHITECTURE.md) | CSS架構指南 | 📝 準備中 |
| [RESPONSIVE.md](./03_design/RESPONSIVE.md) | 響應式設計規範 | 📝 準備中 |

### 🚀 **部署與工具**
| 文檔 | 描述 | 狀態 |
|------|------|------|
| [BUILD_PROCESS.md](./04_deployment/BUILD_PROCESS.md) | 建置流程 | 📝 準備中 |
| [DEVELOPMENT.md](./04_deployment/DEVELOPMENT.md) | 開發環境設置 | 📝 準備中 |
| [PERFORMANCE.md](./04_deployment/PERFORMANCE.md) | 效能優化指南 | 📝 準備中 |

## 🎯 快速開始

### **開發環境要求**
- **Node.js** ≥ 18.0.0 (僅用於開發工具)
- **現代瀏覽器** (Chrome 90+, Firefox 88+, Safari 14+)
- **Visual Studio Code** + Claude Code擴充

### **專案啟動**
```bash
# 克隆專案
git clone https://github.com/your-org/dramaling-app.git
cd dramaling-app

# 啟動開發服務器 (使用Vite僅作為開發服務器)
cd apps/web-native
npm install
npm run dev

# 開啟瀏覽器
open http://localhost:3000
```

### **專案結構預覽**
```
apps/web-native/
├── index.html                 # 應用入口
├── pages/                     # 頁面文件
│   ├── vocabulary/
│   ├── dialogue/
│   ├── auth/
│   └── profile/
├── assets/
│   ├── css/                   # 樣式文件
│   │   ├── main.css          # 主要樣式
│   │   ├── components.css    # 組件樣式
│   │   └── themes.css        # 主題系統
│   ├── js/                   # JavaScript模組
│   │   ├── app.js           # 應用核心
│   │   ├── api.js           # API通訊
│   │   └── components/      # JavaScript組件
│   └── media/               # 媒體資源
├── data/                    # 靜態數據
└── docs/                    # 專案文檔
```

## 🔧 技術棧詳情

### **前端技術**
```yaml
HTML5: 
  - 語義化標記
  - Web組件標準
  - 無障礙設計 (WCAG 2.1)

CSS3:
  - CSS Grid + Flexbox佈局
  - CSS Custom Properties (變數)
  - 現代動畫和轉場
  - 響應式設計 (移動優先)

JavaScript:
  - ES2022+ 語法
  - 原生Web APIs
  - 模組化架構 (ESM)
  - 無框架依賴
```

### **開發工具**
```yaml
構建工具:
  - Vite (開發服務器)
  - PostCSS (CSS處理)
  - ESLint (代碼質量)

測試工具:
  - 瀏覽器原生測試
  - 手動測試為主
  - 自動化測試 (可選)

部署工具:
  - 靜態文件部署
  - CDN優化
  - 性能監控
```

## 🎨 設計系統

### **色彩系統**
```css
:root {
  /* 主色調 */
  --primary-teal: #00E5CC;
  --primary-teal-light: #26F5DA;
  --primary-teal-dark: #00C4A7;
  
  /* 輔助色 */
  --secondary-purple: #6366F1;
  --accent-orange: #FF7A00;
  
  /* 中性色 */
  --text-primary: #2C3E50;
  --text-secondary: #64748B;
  --background-primary: #F7F9FC;
  --background-dark: #1A1A1A;
}
```

### **間距系統**
```css
:root {
  --space-xs: 0.25rem;    /* 4px */
  --space-sm: 0.5rem;     /* 8px */
  --space-md: 1rem;       /* 16px */
  --space-lg: 1.5rem;     /* 24px */
  --space-xl: 2rem;       /* 32px */
  --space-2xl: 3rem;      /* 48px */
}
```

### **字體系統**
```css
:root {
  --font-family-primary: 'Inter', 'Noto Sans TC', sans-serif;
  --font-family-mono: 'Fira Code', monospace;
  
  --text-xs: 0.75rem;     /* 12px */
  --text-sm: 0.875rem;    /* 14px */
  --text-base: 1rem;      /* 16px */
  --text-lg: 1.125rem;    /* 18px */
  --text-xl: 1.25rem;     /* 20px */
  --text-2xl: 1.5rem;     /* 24px */
  --text-3xl: 2rem;       /* 32px */
  --text-4xl: 2.5rem;     /* 40px */
}
```

## 🔗 相關連結

- **專案管理**: [TASKS.md](../../TASKS.md)
- **功能規格**: [function-specs/](../02_design/function-specs/)
- **API文檔**: [api/README.md](./02_api/README.md)
- **重構專案**: [native-html-migration.md](../../projects/native-html-migration.md)

---

**本文檔持續更新中** - 隨著重構進度會不斷完善各項技術細節。