dramaling-app/docs/04_technical

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

更新日期: 2025-09-10
架構版本: Native HTML v1.0
前一版本: Vue架構已歸檔

🏗️ 新架構概覽

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	整體架構設計	📝 準備中
FRONTEND.md	前端技術規格	📝 準備中
COMPONENTS.md	組件系統設計	📝 準備中
STATE_MANAGEMENT.md	狀態管理模式	📝 準備中

🔌 API整合文檔

文檔	描述	狀態
API_CLIENT.md	原生API客戶端實現	📝 準備中
README.md	API規格總覽	✅ 已更新

🎨 樣式系統文檔

文檔	描述	狀態
DESIGN_SYSTEM.md	設計系統規格	📝 準備中
CSS_ARCHITECTURE.md	CSS架構指南	📝 準備中
RESPONSIVE.md	響應式設計規範	📝 準備中

🚀 部署與工具

文檔	描述	狀態
BUILD_PROCESS.md	建置流程	📝 準備中
DEVELOPMENT.md	開發環境設置	📝 準備中
PERFORMANCE.md	效能優化指南	📝 準備中

🎯 快速開始

開發環境要求

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

專案啟動

# 克隆專案
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/                    # 專案文檔

🔧 技術棧詳情

前端技術

HTML5: 
  - 語義化標記
  - Web組件標準
  - 無障礙設計 (WCAG 2.1)

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

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

開發工具

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

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

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

🎨 設計系統

色彩系統

: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;
}

間距系統

: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 */
}

字體系統

: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
• 功能規格: function-specs/
• API文檔: api/README.md
• 重構專案: native-html-migration.md

---

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