258 lines
8.0 KiB
Markdown
258 lines
8.0 KiB
Markdown
# Drama Ling 前端架構重構：Vue → 原生HTML
|
||
|
||
**專案狀態**: ⏳ 規劃中
|
||
**建立日期**: 2025-09-10
|
||
**預估工期**: 3-4週
|
||
**優先級**: 🔥 緊急
|
||
|
||
## 🎯 專案目標
|
||
|
||
將 Drama Ling Web 應用從 Vue + Quasar 框架架構重構為原生 HTML + CSS + JavaScript 實現，以獲得：
|
||
|
||
1. **設計精確度 100%** - 完全按照設計規格實現，無框架樣式干擾
|
||
2. **Claude Code 最佳化** - AI 能精確理解和修改每行代碼
|
||
3. **性能提升** - 移除框架 overhead，載入速度更快
|
||
4. **維護性提升** - 代碼直觀易懂，易於調試
|
||
|
||
## 📋 重構範圍
|
||
|
||
### 🎯 **目標架構**
|
||
```
|
||
apps/web-native/
|
||
├── index.html # 主入口頁面
|
||
├── pages/ # 頁面文件
|
||
│ ├── vocabulary/
|
||
│ │ ├── index.html # 詞彙學習首頁
|
||
│ │ ├── practice.html # 練習頁面
|
||
│ │ ├── review.html # 複習頁面
|
||
│ │ └── analytics.html # 分析儀表板
|
||
│ ├── dialogue/
|
||
│ │ ├── index.html # 對話練習首頁
|
||
│ │ └── practice.html # 對話練習頁面
|
||
│ ├── auth/
|
||
│ │ ├── login.html # 登入頁面
|
||
│ │ └── register.html # 註冊頁面
|
||
│ └── profile/
|
||
│ ├── index.html # 個人檔案
|
||
│ ├── progress.html # 學習進度
|
||
│ └── settings.html # 設定頁面
|
||
├── assets/
|
||
│ ├── css/
|
||
│ │ ├── main.css # 全局樣式
|
||
│ │ ├── components.css # 組件樣式
|
||
│ │ ├── layouts.css # 佈局樣式
|
||
│ │ └── themes.css # 主題樣式
|
||
│ ├── js/
|
||
│ │ ├── app.js # 主要應用邏輯
|
||
│ │ ├── api.js # API 通訊
|
||
│ │ ├── auth.js # 認證管理
|
||
│ │ ├── vocabulary.js # 詞彙功能
|
||
│ │ ├── dialogue.js # 對話功能
|
||
│ │ ├── utils.js # 工具函數
|
||
│ │ └── components/ # JavaScript 組件
|
||
│ │ ├── navbar.js # 導航欄
|
||
│ │ ├── sidebar.js # 側邊欄
|
||
│ │ ├── modal.js # 彈窗組件
|
||
│ │ └── charts.js # 圖表組件
|
||
│ └── media/
|
||
│ ├── icons/ # 圖標資源
|
||
│ ├── images/ # 圖片資源
|
||
│ └── audio/ # 音頻資源
|
||
├── data/
|
||
│ ├── vocabulary.json # 詞彙數據
|
||
│ ├── dialogues.json # 對話數據
|
||
│ └── mockData.js # 開發用模擬數據
|
||
└── docs/
|
||
├── README.md # 專案說明
|
||
├── ARCHITECTURE.md # 架構文檔
|
||
└── API_INTEGRATION.md # API 整合指南
|
||
```
|
||
|
||
## 🚀 執行階段
|
||
|
||
### **第一階段：基礎架構搭建 (週1)**
|
||
- [ ] 🏗️ 創建原生HTML專案目錄結構
|
||
- [ ] 🎨 建立核心CSS框架 (設計系統、響應式、主題)
|
||
- [ ] 📱 實現基礎佈局組件 (Header、Sidebar、Footer)
|
||
- [ ] 🔧 建立JavaScript模組化架構
|
||
- [ ] 📊 建立開發用模擬數據系統
|
||
|
||
### **第二階段：核心頁面實現 (週1)**
|
||
- [ ] 🏠 首頁實現
|
||
- [ ] 🔐 認證頁面 (登入/註冊/忘記密碼)
|
||
- [ ] 📚 詞彙學習主頁面
|
||
- [ ] 💬 對話練習主頁面
|
||
- [ ] 👤 個人檔案頁面
|
||
|
||
### **第三階段：功能頁面實現 (週1)**
|
||
- [ ] 📝 詞彙練習頁面 (選擇題、翻譯、同義詞)
|
||
- [ ] 🎯 詞彙複習頁面 (間隔複習系統)
|
||
- [ ] 📊 學習分析儀表板
|
||
- [ ] 💬 對話練習頁面
|
||
- [ ] ⚙️ 設定頁面
|
||
|
||
### **第四階段：整合與優化 (週1)**
|
||
- [ ] 🔌 API 整合 (真實數據對接)
|
||
- [ ] 🎮 進階功能實現 (書籤、多標籤、PWA)
|
||
- [ ] 🧪 測試與調試
|
||
- [ ] 📱 跨瀏覽器兼容性測試
|
||
- [ ] 🚀 部署配置
|
||
|
||
## 🛠️ 技術規格
|
||
|
||
### **前端技術棧**
|
||
- **HTML5** - 語義化標記
|
||
- **CSS3** - Grid + Flexbox 佈局，CSS Variables
|
||
- **JavaScript ES6+** - 模組化開發，無框架依賴
|
||
- **Chart.js** - 數據視覺化 (保留)
|
||
- **Web APIs** - LocalStorage、SessionStorage、IndexedDB
|
||
|
||
### **開發工具**
|
||
- **Vite** - 開發服務器和建置工具 (保留)
|
||
- **PostCSS** - CSS 後處理 (可選)
|
||
- **ESLint** - JavaScript 代碼質量
|
||
- **Prettier** - 代碼格式化
|
||
|
||
### **設計系統**
|
||
```css
|
||
/* 色彩系統 */
|
||
:root {
|
||
--primary-teal: #00E5CC;
|
||
--secondary-purple: #6366F1;
|
||
--background-primary: #F7F9FC;
|
||
--background-dark: #1A1A1A;
|
||
--text-primary: #2C3E50;
|
||
--text-secondary: #64748B;
|
||
}
|
||
|
||
/* 間距系統 */
|
||
:root {
|
||
--space-1: 0.25rem; /* 4px */
|
||
--space-2: 0.5rem; /* 8px */
|
||
--space-3: 0.75rem; /* 12px */
|
||
--space-4: 1rem; /* 16px */
|
||
--space-6: 1.5rem; /* 24px */
|
||
--space-8: 2rem; /* 32px */
|
||
}
|
||
|
||
/* 字體系統 */
|
||
:root {
|
||
--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: 1.875rem; /* 30px */
|
||
--text-4xl: 2.25rem; /* 36px */
|
||
}
|
||
```
|
||
|
||
## 📊 數據管理策略
|
||
|
||
### **狀態管理模式**
|
||
```javascript
|
||
// 不使用Vue/Pinia，改用簡潔的狀態管理
|
||
class AppState {
|
||
constructor() {
|
||
this.user = null;
|
||
this.vocabulary = [];
|
||
this.currentSession = null;
|
||
this.settings = {};
|
||
}
|
||
|
||
// 響應式更新UI
|
||
setState(newState) {
|
||
Object.assign(this, newState);
|
||
this.updateUI();
|
||
}
|
||
|
||
updateUI() {
|
||
// 觸發相關UI更新
|
||
document.dispatchEvent(new CustomEvent('stateChanged', {
|
||
detail: this
|
||
}));
|
||
}
|
||
}
|
||
```
|
||
|
||
### **API 通訊**
|
||
```javascript
|
||
// 簡潔的API客戶端，不依賴axios
|
||
class ApiClient {
|
||
constructor(baseURL) {
|
||
this.baseURL = baseURL;
|
||
this.token = localStorage.getItem('authToken');
|
||
}
|
||
|
||
async request(endpoint, options = {}) {
|
||
const url = `${this.baseURL}${endpoint}`;
|
||
const config = {
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
...(this.token && { Authorization: `Bearer ${this.token}` }),
|
||
...options.headers
|
||
},
|
||
...options
|
||
};
|
||
|
||
const response = await fetch(url, config);
|
||
return this.handleResponse(response);
|
||
}
|
||
}
|
||
```
|
||
|
||
## 🔄 遷移策略
|
||
|
||
### **漸進式遷移方法**
|
||
1. **並行開發** - 保留現有Vue版本，並行開發原生版本
|
||
2. **頁面級遷移** - 逐頁替換，確保功能完整
|
||
3. **數據兼容** - 保持API接口不變，確保數據一致
|
||
4. **用戶驗證** - A/B測試比較兩版本表現
|
||
|
||
### **風險控制**
|
||
- **功能回滾** - 保留Vue版本作為後備
|
||
- **數據備份** - 完整的數據遷移和備份策略
|
||
- **性能監控** - 建立性能基準線對比
|
||
- **用戶反饋** - 收集使用者體驗反饋
|
||
|
||
## 📈 預期效益
|
||
|
||
### **開發效率提升**
|
||
- Claude Code 理解度：80% → 95%
|
||
- 調試效率提升：50%
|
||
- 代碼維護成本降低：40%
|
||
|
||
### **用戶體驗提升**
|
||
- 頁面載入速度：2s → 0.8s (預估)
|
||
- 設計還原度：85% → 100%
|
||
- 跨瀏覽器兼容性提升
|
||
|
||
### **技術債務清理**
|
||
- 移除不必要的框架依賴
|
||
- 清理過度抽象的代碼結構
|
||
- 建立更直觀的開發流程
|
||
|
||
## ⚠️ 風險評估
|
||
|
||
### **高風險項目**
|
||
- **開發時間** - 可能超出預期時間
|
||
- **功能遺漏** - Vue特定功能可能遺漏
|
||
- **團隊適應** - 需要團隊學習新的開發模式
|
||
|
||
### **緩解措施**
|
||
- **階段性交付** - 每週檢查點確保進度
|
||
- **功能檢查** - 詳細的功能對照表
|
||
- **文檔完善** - 完整的開發指南和最佳實踐
|
||
|
||
## 📋 下一步行動
|
||
|
||
1. **立即行動**：創建專案目錄結構
|
||
2. **本週目標**：完成第一階段基礎架構
|
||
3. **里程碑檢查**：每週進度評估和調整
|
||
|
||
---
|
||
|
||
**文檔更新**: 2025-09-10
|
||
**負責人**: Claude Code
|
||
**相關文檔**: [TASKS.md](../TASKS.md) | [架構設計](../docs/04_technical/ARCHITECTURE.md) |