# LinguaForge 技術架構設計文檔

## 1. 系統架構概覽

### 1.1 整體架構
```
┌─────────────────────────────────────────────────────┐
│                    客戶端層                          │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐            │
│  │   iOS   │  │ Android │  │   Web   │            │
│  └────┬────┘  └────┬────┘  └────┬────┘            │
└───────┼────────────┼────────────┼──────────────────┘
        │            │            │
        └────────────┼────────────┘
                     │ HTTPS/REST API
┌────────────────────┼────────────────────────────────┐
│                    │  API Gateway                   │
│                    ▼                                │
│  ┌──────────────────────────────────────┐         │
│  │         後端服務層 (Node.js)          │         │
│  │  ┌──────────┐  ┌──────────┐         │         │
│  │  │Auth Service│  │Core API │         │         │
│  │  └──────────┘  └─────┬────┘         │         │
│  └───────────────────────┼──────────────┘         │
└──────────────────────────┼──────────────────────────┘
                          │
┌──────────────────────────┼──────────────────────────┐
│                 外部服務整合層                       │
│  ┌─────────────┐  ┌─────────────┐  ┌────────────┐│
│  │ Gemini API  │  │ MS Speech   │  │   AWS S3   ││
│  │             │  │   Service   │  │            ││
│  └─────────────┘  └─────────────┘  └────────────┘│
└──────────────────────────────────────────────────────┘
                          │
┌──────────────────────────┼──────────────────────────┐
│                   資料儲存層                         │
│  ┌─────────────┐  ┌─────────────┐  ┌────────────┐│
│  │ PostgreSQL  │  │   Redis     │  │  S3 Bucket ││
│  │  (主資料庫)  │  │  (快取)     │  │ (檔案儲存)  ││
│  └─────────────┘  └─────────────┘  └────────────┘│
└──────────────────────────────────────────────────────┘
```

## 2. 技術選型

### 2.1 前端技術棧
- **跨平台框架**: React Native
  - 共享程式碼達 85%
  - 生態系統成熟
  - 支援熱更新
- **狀態管理**: Redux Toolkit + RTK Query
- **UI 元件庫**: React Native Paper (Material Design)
- **離線資料**: SQLite + WatermelonDB
- **導航**: React Navigation v6

### 2.2 後端技術棧
- **運行環境**: Node.js 18+ LTS
- **框架**: NestJS (企業級架構)
- **API 協議**: RESTful + GraphQL (部分即時功能)
- **認證**: JWT + Refresh Token
- **驗證**: class-validator + class-transformer
- **ORM**: TypeORM
- **任務排程**: Bull (基於 Redis)

### 2.3 資料庫設計
- **主資料庫**: PostgreSQL 14+
- **快取層**: Redis 7+
- **檔案儲存**: AWS S3 / MinIO (自建)
- **搜尋引擎**: Elasticsearch (未來擴展)

### 2.4 第三方服務
- **AI 服務**: Google Gemini API
- **語音評估**: Microsoft Speech Service
- **推播通知**: Firebase Cloud Messaging
- **錯誤追蹤**: Sentry
- **分析**: Google Analytics / Mixpanel

## 3. 核心模組設計

### 3.1 使用者管理模組
```typescript
interface User {
  id: string;
  email: string;
  username: string;
  createdAt: Date;
  subscription: SubscriptionTier;
  preferences: UserPreferences;
}
```

### 3.2 詞彙學習模組
```typescript
interface VocabularyCard {
  id: string;
  userId: string;
  word: string;
  definition: string;
  examples: string[];
  imageUrl?: string;
  audioUrl?: string;
  nextReviewDate: Date;
  reviewCount: number;
  easinessFactor: number;
}
```

### 3.3 間隔重複演算法
```typescript
// SM-2 演算法實現
interface SpacedRepetition {
  calculateNextReview(
    quality: number,  // 0-5 評分
    repetitions: number,
    easinessFactor: number,
    interval: number
  ): ReviewSchedule;
}
```

### 3.4 語音評估模組
```typescript
interface PronunciationAssessment {
  accuracy: number;      // 準確度 0-100
  fluency: number;       // 流暢度 0-100
  completeness: number;  // 完整度 0-100
  pronunciation: number; // 綜合分數 0-100
}
```

## 4. API 設計規範

### 4.1 RESTful 端點設計
```
POST   /api/auth/register
POST   /api/auth/login
POST   /api/auth/refresh

GET    /api/cards           # 獲取所有詞卡
POST   /api/cards           # 創建新詞卡
GET    /api/cards/:id       # 獲取單張詞卡
PUT    /api/cards/:id       # 更新詞卡
DELETE /api/cards/:id       # 刪除詞卡

POST   /api/cards/generate  # AI 生成詞卡
GET    /api/cards/review    # 獲取今日複習詞卡
POST   /api/cards/:id/review # 提交複習結果

POST   /api/speech/assess   # 語音評估
GET    /api/speech/history  # 評估歷史
```

### 4.2 錯誤處理規範
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "輸入資料驗證失敗",
    "details": {
      "field": "email",
      "reason": "格式不正確"
    }
  }
}
```

## 5. 安全性設計

### 5.1 認證與授權
- JWT Token (15分鐘過期)
- Refresh Token (7天過期)
- 角色權限管理 (RBAC)

### 5.2 資料保護
- HTTPS 強制使用
- 敏感資料加密儲存
- SQL Injection 防護
- XSS/CSRF 防護
- Rate Limiting

### 5.3 API 安全
- API Key 管理
- Request 簽名驗證
- IP 白名單 (生產環境)

## 6. 效能優化策略

### 6.1 快取策略
- Redis 快取熱門詞卡
- CDN 快取靜態資源
- 客戶端快取複習進度

### 6.2 資料庫優化
- 索引優化
- 查詢優化
- 連線池管理
- 讀寫分離 (未來)

### 6.3 API 優化
- 分頁查詢
- 欄位過濾
- 批量操作
- GraphQL DataLoader

## 7. 監控與維運

### 7.1 監控指標
- API 回應時間
- 錯誤率
- 資料庫查詢效能
- 外部服務可用性

### 7.2 日誌管理
- 結構化日誌 (JSON)
- 分級日誌 (DEBUG/INFO/WARN/ERROR)
- 集中式日誌收集 (ELK Stack)

### 7.3 部署架構
- Docker 容器化
- Kubernetes 編排 (生產環境)
- CI/CD Pipeline (GitHub Actions)
- 藍綠部署策略

## 8. 擴展性考量

### 8.1 水平擴展
- 無狀態服務設計
- 負載均衡 (Nginx/ALB)
- 自動擴縮容

### 8.2 微服務化準備
- 模組化設計
- 服務邊界清晰
- 事件驅動架構預留

## 9. 災難恢復

### 9.1 備份策略
- 資料庫每日備份
- 增量備份
- 異地備份

### 9.2 故障轉移
- 主從複製
- 自動故障檢測
- 快速恢復機制