# 技術選型決策文檔

## 概述
基於 Drama Ling 應用的功能需求、效能要求和團隊技術能力，制定完整的技術棧選型方案。

## 技術選型原則

### 決策考量因素
- [ ] **學習曲線**: 團隊上手難度和開發效率
- [ ] **生態系統**: 社群支援和第三方套件豐富度  
- [ ] **效能表現**: 應用效能和可擴展性需求
- [ ] **維護成本**: 長期維護和升級的成本考量
- [ ] **團隊熟悉度**: 現有團隊的技術背景和經驗

### 架構設計原則
- [ ] **前後端分離**: API優先設計，統一後端服務同時支援Web端和移動端App
- [ ] **API統一設計**: 單一後端API服務，透過不同端點(/api/v1/web, /api/v1/mobile)提供差異化服務
- [ ] **微服務準備**: 依功能模組設計，為未來微服務架構奠定基礎
- [ ] **多平台支援**: 一套API同時服務Web應用和Flutter移動應用
- [ ] **雲原生設計**: 充分利用雲端服務，提高可靠性和擴展性
- [ ] **容器化部署**: 使用Docker進行一致性部署
- [ ] **持續集成**: 自動化測試和部署流程

## 前端技術棧

### 移動應用開發

#### Flutter (選定方案)
**選擇理由:**
- [ ] **跨平台優勢**: 一套Dart代碼支援iOS和Android
- [ ] **原生效能**: 直接編譯為原生代碼，效能優異
- [ ] **UI一致性**: 統一的Material Design和Cupertino風格
- [ ] **熱重載**: 快速開發和調試體驗
- [ ] **Google支持**: 持續更新和長期支援保證

**技術組合:**
```yaml
framework: "Flutter 3.16+"
language: "Dart 3.0+"
state_management: "Riverpod / BLoC"
navigation: "Go Router"
local_storage: "Hive / Isar"
networking: "Dio + Retrofit"
ui_components: "Material 3 + Custom Components"
animations: "Flutter Animations API"
audio_handling: "Just Audio / Audio Players"
testing: "Flutter Test + Integration Test"
build_runner: "Build Runner (code generation)"
```

**開發優勢:**
- [ ] **熱重載**: 毫秒級UI更新，提升開發效率
- [ ] **豐富Widget**: 內建豐富UI組件，快速構建界面
- [ ] **效能監控**: 內建效能分析工具
- [ ] **CI/CD友好**: 命令列工具支援自動化建構

### 網頁應用開發

#### 現代前端架構 (選定方案)
**選擇理由:**
- [ ] **前後端分離**: 純前端應用，透過API與後端通信
- [ ] **Claude Code友好**: 基於現代JavaScript模組系統，便於AI理解和維護
- [ ] **API統一**: 與移動端共享同一套後端API服務
- [ ] **開發效率**: 熱重載、模組化開發、現代工具鏈
- [ ] **效能優化**: Vite構建、代碼分割、Tree-shaking

**技術組合:**
```json
{
  "markup": "HTML5 語義化標籤",
  "styling": "SCSS/Sass + CSS3 + CSS Grid + Flexbox", 
  "scripting": "Modern JavaScript (ES2022+) + ES6 Modules",
  "bundler": "Vite 5.x (開發伺服器 + 生產構建)",
  "架構模式": "模組化前端架構 (非MVC)",
  "狀態管理": "原生JavaScript類別 + localStorage/sessionStorage",
  "API通信": "Fetch API + RESTful設計",
  "組件系統": "ES6 Classes + 模組化組件",
  "路由": "History API + SPA路由",
  "音頻處理": "Web Audio API + Speech Synthesis",
  "測試": "Vitest + Testing Library",
  "代碼品質": "ESLint + Prettier"
}
```

**前後端分離架構:**
```mermaid
graph LR
    WEB[Web Frontend<br/>Vite + Modern JS] --> API[Unified API Server<br/>.NET Core]
    APP[Flutter Mobile App] --> API
    API --> DB[(PostgreSQL)]
    API --> CACHE[(Redis)]
    API --> AI[AI Services<br/>OpenAI]
```

## 後端技術棧

### 應用服務框架

#### .NET Core (選定方案)
**選擇理由:**
- [ ] **高效能**: 出色的效能表現，特別適合API服務
- [ ] **跨平台**: 支援Windows、Linux、macOS部署
- [ ] **強型別**: C#強型別系統，減少執行時錯誤
- [ ] **生態成熟**: 豐富的NuGet套件生態系統
- [ ] **企業級**: 微軟支援，適合長期維護

**技術組合:**
```yaml
framework: ".NET 8"
language: "C# 12"
web_framework: "ASP.NET Core Web API"
architecture: "前後端分離 + API統一設計"
api_design: 
  - "RESTful API設計原則"
  - "統一API服務多平台客戶端"
  - "差異化端點 (/api/v1/web, /api/v1/mobile)"
  - "版本控制和向後相容"
orm: "Entity Framework Core"
authentication: 
  - "JWT (Mobile App)"
  - "Session/Cookie (Web)"
  - "雙重認證策略"
validation: "FluentValidation"
documentation: "Swagger/OpenAPI (Swashbuckle)"
cors: "配置支援前端域名"
testing: "xUnit + Moq + FluentAssertions"
dependency_injection: "內建DI Container"
logging: "ILogger + Serilog"
caching: "IMemoryCache + Redis"
background_services: "Hosted Services + Hangfire"
```

**架構優勢:**
- [ ] **內建DI**: 強大的依賴注入容器
- [ ] **中介軟體**: 靈活的請求處理管道
- [ ] **配置系統**: 強大的配置管理機制
- [ ] **健康檢查**: 內建服務健康檢查
- [ ] **API版本控制**: 原生支援API版本管理

#### 替代方案比較

**Node.js + Express/Fastify**
- 優點: JavaScript生態豐富，快速開發
- 缺點: 弱型別，大型專案維護困難

**Python + FastAPI**
- 優點: AI/ML整合容易，自動API文檔
- 缺點: 效能相對較低，GIL限制

### 資料庫選型

#### PostgreSQL 15+ (主資料庫)
**選擇理由:**
- [ ] **功能完整**: 支援JSON、全文檢索、空間資料
- [ ] **ACID保證**: 強一致性保證資料完整性
- [ ] **擴展性**: 支援水平和垂直擴展
- [ ] **開源免費**: 無授權費用，社群支援強
- [ ] **生態豐富**: 大量擴展套件和工具

**配置:**
```yaml
postgresql:
  version: "15.4"
  extensions:
    - pg_trgm  # 模糊搜尋
    - pg_stat_statements  # 效能監控
    - pgcrypto  # 加密功能
  connection_pooling: "PgBouncer"
  backup_strategy: "WAL-E / pgBackRest"
```

#### Redis 7+ (快取和會話)
**用途:**
- [ ] **應用快取**: API回應和查詢結果快取
- [ ] **會話存儲**: 用戶會話和JWT黑名單
- [ ] **排行榜**: 即時排行榜計算和存儲
- [ ] **任務佇列**: 背景任務處理
- [ ] **即時通訊**: WebSocket會話管理

## AI和機器學習服務

### 低成本AI服務策略

#### OpenAI GPT-4o-mini (主要AI服務)
**應用場景:**
- [ ] **對話分析**: 語法、語意、流暢度評分
- [ ] **內容生成**: 對話建議和回覆範例
- [ ] **錯誤訂正**: 語言錯誤檢測和修正建議
- [ ] **個人化推薦**: 學習內容推薦

**技術整合:**
```javascript
{
  "provider": "OpenAI",
  "models": {
    "dialogue_analysis": "gpt-4o-mini", // 便宜10倍
    "content_generation": "gpt-4o-mini",
    "embedding": "text-embedding-3-small" // 便宜5倍
  },
  "backup_provider": "Anthropic Claude-3 Haiku",
  "rate_limiting": "tiktoken + custom limiter",
  "cost_optimization": {
    "aggressive_caching": "90%+ 快取命中率",
    "prompt_optimization": "最小化token使用",
    "batch_processing": "批量處理降低成本",
    "smart_fallback": "簡單任務用更便宜模型"
  }
}
```

#### 高階AI方案 (預算充足時)
```javascript
{
  "provider": "OpenAI",
  "models": {
    "dialogue_analysis": "gpt-4-turbo", 
    "content_generation": "gpt-3.5-turbo",
    "embedding": "text-embedding-ada-002"
  },
  "backup_provider": "Anthropic Claude-3",
  "rate_limiting": "tiktoken + custom limiter",
  "cost_optimization": "caching + prompt optimization"
}
```

#### 語音處理服務
**語音轉文字 (STT):**
- 主選: Google Cloud Speech-to-Text
- 備選: Azure Speech Services
- 考量: 多語言支援、準確度、成本

**文字轉語音 (TTS):**
- 主選: ElevenLabs (自然度高)
- 備選: Google Cloud Text-to-Speech  
- 考量: 語音品質、語言支援、API穩定性

### 本地化AI考量
```python
# 未來可考慮的本地模型
local_models = {
    "grammar_checking": "LanguageTool API",
    "pronunciation_scoring": "SpeechAce API", 
    "vocabulary_difficulty": "Custom trained model",
    "content_classification": "Hugging Face Transformers"
}
```

## 雲端服務架構

### 低預算部署方案 (推薦)

#### VPS部署配置
```yaml
# 核心服務
compute:
  vps_provider: "DigitalOcean / Vultr / Linode"
  instance_type: "4GB RAM, 2 vCPU, 80GB SSD"
  containerization: "Docker + Docker Compose"
  reverse_proxy: "Nginx"

# 資料存儲  
storage:
  database: "PostgreSQL 15 (容器化)"
  cache: "Redis 7 (容器化)"
  files: "本地存儲 + Nginx靜態服務"
  backups: "PostgreSQL dump + 對象存儲同步"

# 網路與安全
networking:
  ssl: "Let's Encrypt免費SSL證書"
  security: "Fail2ban + UFW防火牆"
  domain: "Cloudflare DNS + CDN (免費版)"
  
# 監控與日誌
monitoring:
  metrics: "Grafana + Prometheus (輕量化)"
  logs: "Docker logs + 日誌輪轉"
  uptime: "UptimeRobot免費監控"
  alerts: "Discord/Telegram通知"
```

#### 高階AWS方案 (預算充足時)
```yaml
# 應用服務 (預算充足時的選項)
compute:
  api_servers: "ECS Fargate"
  background_jobs: "Lambda Functions"
  load_balancer: "Application Load Balancer"

# 資料存儲  
storage:
  database: "RDS PostgreSQL Multi-AZ"
  cache: "ElastiCache Redis"
  files: "S3 + CloudFront CDN"
  backups: "S3 Glacier"

# 網路與安全
networking:
  vpc: "Custom VPC with private subnets"
  security: "WAF + Shield + GuardDuty"
  ssl: "ACM SSL Certificates"
  
# 監控與日誌
monitoring:
  metrics: "CloudWatch"
  logs: "CloudWatch Logs"
  tracing: "X-Ray"
  alerts: "SNS + CloudWatch Alarms"
```

#### 替代方案比較

**Google Cloud Platform**
- 優點: AI服務整合佳、BigQuery分析強
- 缺點: 服務相對較少、台灣資料中心限制

**Microsoft Azure**
- 優點: 企業客戶友好、Office整合
- 缺點: 學習曲線較陡、定價複雜

### CDN和媒體服務

#### CloudFront + S3
**媒體檔案處理:**
- [ ] **音頻檔案**: 對話範例、發音示範
- [ ] **圖片資源**: 場景圖片、用戶頭像  
- [ ] **影片內容**: 教學影片、文化介紹
- [ ] **靜態資源**: CSS、JavaScript、字體檔案

**優化策略:**
```yaml
cdn_config:
  cache_behaviors:
    - path: "/api/*"
      cache_policy: "CachingDisabled"
    - path: "/assets/*"  
      cache_policy: "CachingOptimized"
      compress: true
  security:
    - origin_access_identity: true
    - signed_urls: true # 付費內容保護
```

## 開發工具鏈

### 版本控制和CI/CD

#### GitHub + GitHub Actions
**工作流程:**
```yaml
# .github/workflows/main.yml
name: CI/CD Pipeline
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm ci
      - run: npm run test
      - run: npm run lint
      
  deploy:
    if: github.ref == 'refs/heads/main'  
    needs: test
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to AWS
        run: |
          # 部署邏輯
```

### 監控和日誌

#### 應用監控堆疊
```yaml
monitoring_stack:
  apm: "New Relic / Datadog"
  error_tracking: "Sentry"
  uptime_monitoring: "Pingdom / StatusCake"  
  log_aggregation: "ELK Stack / Fluentd"
  metrics: "Prometheus + Grafana (自建)"
```

#### 關鍵指標追蹤
- [ ] **API效能**: 回應時間、吞吐量、錯誤率
- [ ] **用戶體驗**: 頁面載入時間、應用崩潰率
- [ ] **業務指標**: 活躍用戶、學習完成率、付費轉換
- [ ] **基礎設施**: CPU、記憶體、網路、磁碟使用率

### 安全性工具

#### 安全掃描和檢測
```yaml
security_tools:
  dependency_scanning: "Snyk / GitHub Dependabot"
  code_scanning: "SonarQube / CodeQL"
  container_scanning: "Trivy / Clair"
  secret_detection: "GitGuardian / TruffleHog"
  penetration_testing: "OWASP ZAP"
```

## 第三方服務整合

### 支付服務

#### Stripe (國際用戶)
```javascript
const stripe_config = {
  subscription_management: "Stripe Billing",
  payment_methods: ["card", "apple_pay", "google_pay"],
  webhooks: "subscription lifecycle events",
  fraud_detection: "Stripe Radar",
  local_payment_methods: {
    "taiwan": ["card", "bank_transfer"],
    "global": ["card", "digital_wallets"]
  }
}
```

#### 藍新金流 (台灣用戶)
- 信用卡收單
- ATM轉帳  
- 超商代碼繳費
- LINE Pay / 街口支付

### 推播通知服務

#### Firebase Cloud Messaging
```yaml
push_notifications:
  service: "Firebase Cloud Messaging"
  features:
    - cross_platform: true
    - topic_based: true # 學習提醒、系統公告
    - personalized: true # 個人化推薦
  integration:
    - react_native: "@react-native-firebase/messaging"
    - backend: "firebase-admin SDK"
```

### 客服系統

#### Intercom / Zendesk
- [ ] **即時聊天**: 應用內客服聊天
- [ ] **幫助中心**: 自助服務文檔
- [ ] **工單系統**: 問題追蹤和處理
- [ ] **知識庫**: 常見問題和解答

## 開發環境配置

### 本地開發環境

#### Docker Compose 設定
```yaml
# docker-compose.dev.yml
version: '3.8'
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: dramaling_dev
      POSTGRES_USER: dev
      POSTGRES_PASSWORD: dev123
    ports:
      - "5432:5432"
      
  redis:
    image: redis:7-alpine  
    ports:
      - "6379:6379"
      
  api:
    build: ./backend
    ports:
      - "3001:3001"
    depends_on:
      - postgres
      - redis
    volumes:
      - ./backend:/app
```

### 測試環境

#### 自動化測試策略
```yaml
testing_pyramid:
  unit_tests:
    coverage_target: ">= 80%"
    tools: "Jest + Testing Library"
    
  integration_tests:
    api_testing: "Supertest + Jest"
    database_testing: "Test Containers"
    
  e2e_tests:
    mobile: "Detox"
    web: "Cypress / Playwright"
    
  performance_tests:
    load_testing: "k6"
    stress_testing: "Artillery"
```

## 成本估算和優化

### 低預算成本估算 (月費估算)

#### 開發階段 (NT$ 2,000/月預算)
```yaml
development_costs:
  infrastructure:
    - local_docker: "NT$ 0" # 完全本地開發
    - domain_testing: "NT$ 0" # ngrok或localhost
    
  services:
    - openai_api: "NT$ 300-600" # 低使用量GPT-4o-mini
    - database: "NT$ 0" # 本地PostgreSQL
    - storage: "NT$ 0" # 本地檔案系統
    
  tools:
    - monitoring: "NT$ 0" # 免費工具
    - version_control: "NT$ 0" # GitHub免費版
    
  total_estimated: "NT$ 300-600/月"
  budget_remaining: "NT$ 1,400-1,700/月"
```

#### 生產階段 (NT$ 5,000/月預算)
```yaml
production_costs:
  infrastructure:
    - vps_server: "NT$ 320-480" # DigitalOcean 4GB
    - domain_ssl: "NT$ 400-600" # 域名 + Cloudflare Pro
    - backup_storage: "NT$ 160-240" # 對象存儲備份
    
  services:
    - openai_api: "NT$ 1,500-3,000" # 優化使用的GPT-4o-mini
    - stripe_processing: "3% 交易手續費"
    - monitoring: "NT$ 0-480" # 基本監控免費或便宜方案
    
  total_estimated: "NT$ 2,380-4,800/月"
  budget_remaining: "NT$ 200-2,620/月"
```

#### AWS高階方案比較 (預算充足時)
```yaml
aws_costs:
  compute:
    - ecs_fargate: "$200-500" # 2-4 tasks
    - lambda: "$50-100" # background jobs
    
  storage:
    - rds_postgresql: "$150-300" # db.r5.large Multi-AZ
    - elasticache_redis: "$100-200" # cache.r6g.large
    - s3_storage: "$50-150" # media files + backups
    
  networking:
    - cloudfront_cdn: "$20-80" # data transfer
    - load_balancer: "$25" # ALB
    
  monitoring:
    - cloudwatch: "$30-60" # logs + metrics
    
  total_estimated: "$625-1415/month (約NT$ 20,000-45,000)"
```

### 第三方服務成本優化
```yaml
optimized_third_party_costs:
  ai_services:
    - openai_gpt4o_mini: "NT$ 1,500-3,000/月" # 90%快取命中率
    - embedding_service: "NT$ 150-300/月" # 較便宜的embedding模型
    
  payment_processing:
    - stripe_international: "2.9% + NT$ 9.6 per transaction"
    - local_payment: "1.8% + NT$ 6 per transaction" # 台灣金流
    
  communication:
    - firebase_messaging: "NT$ 0" # 免費版足夠
    - email_service: "NT$ 0-160" # SendGrid免費版或便宜方案
    
  monitoring_free:
    - uptime_monitoring: "NT$ 0" # UptimeRobot免費版
    - error_tracking: "NT$ 0" # Sentry免費版
    - log_analysis: "NT$ 0" # 基本Docker logs
```

### 成本優化策略
- [ ] **自動擴縮**: 基於負載自動調整資源
- [ ] **Spot實例**: 非關鍵服務使用Spot實例
- [ ] **資料生命週期**: 舊資料自動遷移到便宜存儲
- [ ] **CDN最佳化**: 壓縮和快取策略降低頻寬成本
- [ ] **API快取**: 減少AI API調用次數

## 效能和擴展性考量

### 效能目標
```yaml
performance_targets:
  api_response_time:
    p95: "< 200ms"
    p99: "< 500ms"
    
  mobile_app:
    cold_start: "< 3s"
    hot_start: "< 1s"
    
  web_app:
    first_contentful_paint: "< 1.5s"
    largest_contentful_paint: "< 2.5s"
    
  database:
    query_time: "< 50ms (95th percentile)"
    connection_time: "< 10ms"
```

### 擴展策略
```yaml
scaling_strategy:
  horizontal_scaling:
    - api_servers: "ECS Auto Scaling"
    - database: "Read Replicas"
    - cache: "Redis Cluster"
    
  vertical_scaling:
    - database: "Automated instance sizing"
    - cache: "Memory optimization"
    
  geographic_scaling:
    - cdn: "Global edge locations"
    - database: "Regional read replicas"
```

---

## 實施路徑和里程碑

### Phase 1: MVP (3個月)
- [ ] React Native基礎應用架構
- [ ] Node.js API服務
- [ ] PostgreSQL資料庫設計  
- [ ] 基礎AI整合 (OpenAI)
- [ ] AWS基礎設施設置

### Phase 2: 完整功能 (6個月)  
- [ ] 完整遊戲化系統
- [ ] 支付系統整合
- [ ] 進階AI功能
- [ ] 效能優化
- [ ] 監控和告警系統

### Phase 3: 規模化 (9-12個月)
- [ ] 多語言支援  
- [ ] 企業功能
- [ ] 高可用架構
- [ ] 自動化維運
- [ ] 資料分析平台

---

## 風險評估與緩解

### 技術風險
| 風險項目 | 機率 | 影響 | 緩解策略 |
|---------|------|------|----------|
| AI API成本過高 | 中 | 高 | 實施快取策略、成本監控 |
| 第三方服務中斷 | 低 | 高 | 多供應商策略、服務降級 |
| 資料庫效能瓶頸 | 中 | 中 | 讀寫分離、查詢優化 |
| 移動應用效能 | 中 | 中 | 效能測試、代碼優化 |

### 業務風險
| 風險項目 | 機率 | 影響 | 緩解策略 |
|---------|------|------|----------|
| 用戶增長超預期 | 低 | 高 | 自動擴縮、負載測試 |
| 競爭對手技術領先 | 中 | 中 | 快速迭代、技術創新 |
| 法規變化影響 | 低 | 中 | 合規審查、架構調整 |

---

## 待完成任務

### 高優先級
1. [ ] 確定最終技術棧組合和版本號
2. [ ] 建立開發環境的Docker配置
3. [ ] 設計CI/CD流程的詳細配置
4. [ ] 規劃第三方服務的整合時程

### 中優先級
1. [ ] 評估和選擇監控工具的具體方案
2. [ ] 設計資料庫連接池和快取策略
3. [ ] 規劃安全性測試和合規性檢查
4. [ ] 建立效能基準測試和優化流程

### 低優先級  
1. [ ] 研究最新技術趨勢對架構的影響
2. [ ] 評估邊緣計算在AI推理中的應用
3. [ ] 探索微前端架構的可行性
4. [ ] 調研區塊鏈技術在學習認證中的應用

---

## 現有實現驗證

### 當前 `/apps/web` 實現符合度 ✅

經過分析，當前的實現**完全符合**技術文件規範：

| 項目 | 文件要求 | 當前實現 | 符合度 |
|------|----------|----------|--------|
| **架構模式** | 前後端分離 | ✅ 純前端應用，透過API通信 | **100%** |
| **前端技術** | Modern JavaScript + ES6 Modules | ✅ ES2022+ + ES6 Modules | **100%** |
| **構建工具** | Vite 5.x | ✅ Vite 7.x (更新版本) | **100%** |
| **樣式處理** | SCSS/Sass | ✅ SCSS + CSS變數系統 | **100%** |
| **狀態管理** | 原生JavaScript類別 | ✅ VocabularyState 類別 | **100%** |
| **組件系統** | ES6 Classes + 模組化 | ✅ BaseComponent + 模組化組件 | **100%** |
| **API整合** | Fetch API + RESTful | ✅ 預留API整合架構 | **100%** |
| **音頻處理** | Web Audio API | ✅ AudioManager + Speech Synthesis | **100%** |

### 實現亮點

1. **🎯 完美的前後端分離設計**
   - 純前端應用，無後端渲染依賴
   - 為統一API整合預留完整架構

2. **🚀 現代化技術棧**
   - Vite 7.x (比文件要求更新)
   - ES2022+ 語法支援
   - 模組化架構設計

3. **🧩 擴展性設計**
   - 清晰的模組分離 (VocabularyApp, VocabularyState)
   - 可重用的組件系統 (BaseComponent)
   - 統一的工具模組 (AudioManager)

### 後續整合建議

當前實現已為API整合做好準備，建議：

1. **後端API開發**: 按照 `backend-api-separation-plan.md` 開發.NET Core API
2. **API整合**: 在現有架構基礎上添加API通信層
3. **認證系統**: 整合JWT/Session雙重認證
4. **移動端開發**: Flutter App整合同一套API服務

---

**最後更新**: 2025-09-10  
**負責人**: Drama Ling 開發團隊  
**審查週期**: 每兩週檢討一次