246 lines
7.9 KiB
Markdown
246 lines
7.9 KiB
Markdown
# 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 故障轉移
|
|
- 主從複製
|
|
- 自動故障檢測
|
|
- 快速恢復機制 |