205 lines
5.9 KiB
Markdown
205 lines
5.9 KiB
Markdown
# 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)
|
||
|
||
---
|
||
|
||
**本文檔持續更新中** - 隨著重構進度會不斷完善各項技術細節。 |