jettcheng1018
/
dramaling-vocab-learning
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
dramaling-vocab-learning/00_starter/old/technical-architecture.md

7.9 KiB
Raw Blame History

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 使用者管理模組

interface User {
  id: string;
  email: string;
  username: string;
  createdAt: Date;
  subscription: SubscriptionTier;
  preferences: UserPreferences;
}

3.2 詞彙學習模組

interface VocabularyCard {
  id: string;
  userId: string;
  word: string;
  definition: string;
  examples: string[];
  imageUrl?: string;
  audioUrl?: string;
  nextReviewDate: Date;
  reviewCount: number;
  easinessFactor: number;
}

3.3 間隔重複演算法

// SM-2 演算法實現
interface SpacedRepetition {
  calculateNextReview(
    quality: number,  // 0-5 評分
    repetitions: number,
    easinessFactor: number,
    interval: number
  ): ReviewSchedule;
}

3.4 語音評估模組

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 錯誤處理規範

{
  "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 故障轉移

  • 主從複製
  • 自動故障檢測
  • 快速恢復機制