jettcheng1018
/
dramaling-app
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
dramaling-app/docs/02_design/function-specs/common/api-specifications.md

11 KiB
Raw Blame History

共同API規格

📋 概述

文檔名稱: 跨平台API規格定義
建立日期: 2025-09-09
適用平台: Mobile App / Web App
API版本: v1
基礎URL: https://api.dramaling.com/api/v1

本文檔定義了Drama Ling系統中所有平台通用的API接口規格。

🔧 通用設計原則

RESTful 設計

  • 使用標準HTTP方法 (GET, POST, PUT, DELETE)
  • 資源導向的URL設計
  • 統一的狀態碼使用
  • JSON格式的請求和回應

認證機制

  • JWT Bearer Token認證
  • 訪問令牌有效期: 1小時
  • 刷新令牌有效期: 30天
  • 自動令牌刷新機制

錯誤處理

  • 統一的錯誤回應格式
  • 多語言錯誤訊息支援
  • 詳細的錯誤碼系統

回應格式

interface APIResponse<T> {
  success: boolean;
  data?: T;
  error?: APIError;
  message: string;
  meta: {
    timestamp: string;
    requestId: string;
    version: string;
  };
}

interface APIError {
  code: string;
  message: string;
  details?: any;
}

🔐 認證相關API

用戶註冊

POST /auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "securePassword123",
  "username": "learner123",
  "nativeLanguage": "zh-TW",
  "learningLanguages": ["en"]
}

回應:

interface RegisterResponse {
  userId: string;
  username: string;
  email: string;
  accessToken: string;
  refreshToken: string;
  expiresIn: number;
  userRole: string;
}

用戶登入

POST /auth/login
Content-Type: application/json

{
  "email": "user@example.com", 
  "password": "securePassword123",
  "platform": "mobile" | "web",
  "rememberMe": boolean
}

Token刷新

POST /auth/refresh
Authorization: Bearer <refresh_token>

第三方登入

POST /auth/social
Content-Type: application/json

{
  "provider": "google" | "apple" | "facebook",
  "token": "social_provider_token",
  "platform": "mobile" | "web"
}

👤 用戶資料API

獲取用戶資料

GET /users/profile
Authorization: Bearer <access_token>

更新用戶資料

PUT /users/profile
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "username": "newUsername",
  "nativeLanguage": "zh-TW",
  "learningLanguages": ["en", "ja"],
  "profile": {
    "firstName": "John",
    "lastName": "Doe",
    "bio": "Language learning enthusiast"
  }
}

獲取學習進度

GET /users/progress
Authorization: Bearer <access_token>
Query Parameters:
- skill: string (optional) - vocabulary|dialogue|pronunciation
- timeframe: string (optional) - day|week|month|all

回應:

interface ProgressResponse {
  overallProgress: number;
  skillProgress: {
    vocabulary: SkillProgress;
    dialogue: SkillProgress; 
    pronunciation: SkillProgress;
  };
  recentAchievements: Achievement[];
  nextGoals: Goal[];
}

獲取遊戲統計

GET /users/game-stats
Authorization: Bearer <access_token>

📚 學習內容API

獲取詞彙列表

GET /vocabulary
Authorization: Bearer <access_token>
Query Parameters:
- language: string (required) - 語言代碼
- level: number (optional) - 難度等級 1-5
- category: string (optional) - 詞彙分類
- limit: number (optional) - 返回數量限制
- offset: number (optional) - 偏移量

獲取詞彙詳情

GET /vocabulary/{vocabularyId}
Authorization: Bearer <access_token>

回應:

interface VocabularyDetail {
  id: string;
  word: string;
  pronunciation: string;
  definitions: Definition[];
  examples: Example[];
  audioUrl: string;
  relatedWords: RelatedWord[];
  userProgress?: {
    masteryLevel: number;
    lastStudied: string;
    studyCount: number;
  };
}

獲取對話列表

GET /dialogues
Authorization: Bearer <access_token>
Query Parameters:
- difficulty: number (optional)
- scenario: string (optional)
- completed: boolean (optional)

獲取對話詳情

GET /dialogues/{dialogueId}
Authorization: Bearer <access_token>

搜索學習內容

GET /content/search
Authorization: Bearer <access_token>
Query Parameters:
- query: string (required) - 搜索關鍵詞
- type: string (optional) - vocabulary|dialogue|all
- language: string (required)

🎯 學習活動API

開始學習會話

POST /learning/sessions
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "type": "vocabulary" | "dialogue" | "review",
  "contentId": "content_uuid",
  "settings": {
    "difficulty": number,
    "timeLimit": number,
    "hints": boolean
  }
}

回應:

interface SessionResponse {
  sessionId: string;
  content: LearningContent;
  questions: Question[];
  timeLimit: number;
  lifePointsCost: number;
}

提交答案

POST /learning/sessions/{sessionId}/answers
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "questionId": "question_uuid",
  "answer": any,
  "responseTime": number,
  "hintsUsed": number
}

回應:

interface AnswerResponse {
  correct: boolean;
  correctAnswer?: any;
  explanation?: string;
  scoreGained: number;
  lifePointsLost: number;
  nextQuestion?: Question;
}

完成學習會話

POST /learning/sessions/{sessionId}/complete
Authorization: Bearer <access_token>

回應:

interface SessionCompleteResponse {
  finalScore: number;
  accuracy: number;
  xpGained: number;
  diamondsGained: number;
  achievementsUnlocked: Achievement[];
  nextRecommendations: Recommendation[];
}

獲取複習內容

GET /learning/review
Authorization: Bearer <access_token>
Query Parameters:
- type: string (optional) - vocabulary|dialogue|all
- limit: number (optional)

🏆 遊戲化系統API

獲取成就列表

GET /achievements
Authorization: Bearer <access_token>
Query Parameters:
- category: string (optional)
- completed: boolean (optional)

獲取用戶道具

GET /inventory
Authorization: Bearer <access_token>

使用道具

POST /inventory/use
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "itemId": "item_uuid",
  "quantity": number,
  "context": {
    "sessionId": "session_uuid"
  }
}

購買道具

POST /store/purchase
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "itemId": "item_uuid",
  "quantity": number,
  "paymentMethod": "diamonds" | "learning_coins" | "real_money"
}

獲取排行榜

GET /leaderboard
Authorization: Bearer <access_token>
Query Parameters:
- type: string - xp|vocabulary|dialogue|streak
- timeframe: string - day|week|month|all
- limit: number (optional)

📊 分析與報告API

獲取學習分析

GET /analytics/learning
Authorization: Bearer <access_token>
Query Parameters:
- startDate: string (YYYY-MM-DD)
- endDate: string (YYYY-MM-DD)
- granularity: string - day|week|month

回應:

interface LearningAnalytics {
  timeRange: {
    start: string;
    end: string;
  };
  summary: {
    totalStudyTime: number;
    wordsLearned: number;
    dialoguesCompleted: number;
    overallAccuracy: number;
    streakDays: number;
  };
  skillBreakdown: SkillAnalytics[];
  progressTrend: DataPoint[];
  weakAreas: WeakArea[];
  recommendations: string[];
}

導出學習數據

GET /analytics/export
Authorization: Bearer <access_token>
Query Parameters:
- format: string - json|csv|pdf
- startDate: string
- endDate: string
- includePersonal: boolean

🔄 實時功能API

WebSocket連接 (適用於Web端)

WSS /ws/learning
Authorization: Bearer <access_token>

支援事件:

  • session_start - 學習會話開始
  • question_answered - 回答題目
  • achievement_unlocked - 解鎖成就
  • life_point_restored - 命條恢復
  • friend_activity - 好友活動通知

推送通知API (適用於Mobile端)

POST /notifications/register
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "deviceToken": "fcm_device_token",
  "platform": "ios" | "android",
  "preferences": {
    "studyReminders": boolean,
    "achievements": boolean,
    "friends": boolean
  }
}

🌐 多語言支援API

獲取語言包

GET /localization/{languageCode}
Query Parameters:
- version: string (optional) - 語言包版本號

獲取支援語言列表

GET /localization/languages

🛡️ 資料保護API

請求數據導出

POST /privacy/export-request
Authorization: Bearer <access_token>

請求帳戶刪除

POST /privacy/delete-request
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "reason": string,
  "confirmPassword": string
}

更新隱私設定

PUT /privacy/settings
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "dataCollection": boolean,
  "analytics": boolean,
  "marketing": boolean,
  "thirdPartySharing": boolean
}

📈 API限流規則

頻率限制

端點類別 限制 時間窗口
認證相關 5次 每分鐘
學習內容 100次 每分鐘
學習活動 50次 每分鐘
分析報告 10次 每分鐘
通用查詢 200次 每分鐘

限流回應

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Request rate limit exceeded"
  }
}

🔍 錯誤碼參考

認證錯誤 (4xx)

  • INVALID_CREDENTIALS (401) - 登入憑證錯誤
  • TOKEN_EXPIRED (401) - Token已過期
  • TOKEN_INVALID (401) - Token格式錯誤
  • INSUFFICIENT_PERMISSIONS (403) - 權限不足

業務邏輯錯誤 (4xx)

  • INSUFFICIENT_LIFE_POINTS (402) - 命條不足
  • CONTENT_NOT_FOUND (404) - 學習內容不存在
  • SESSION_EXPIRED (410) - 學習會話已過期
  • INVALID_ANSWER_FORMAT (422) - 答案格式錯誤

系統錯誤 (5xx)

  • INTERNAL_SERVER_ERROR (500) - 內部伺服器錯誤
  • DATABASE_ERROR (503) - 資料庫連接錯誤
  • THIRD_PARTY_SERVICE_ERROR (503) - 第三方服務錯誤

📋 API測試

測試端點

開發環境: https://dev-api.dramaling.com/api/v1
測試環境: https://test-api.dramaling.com/api/v1  
生產環境: https://api.dramaling.com/api/v1

測試帳號

測試用戶: test@dramaling.com
測試密碼: TestUser123456
測試Token: 開發環境提供長效測試Token

Postman Collection

  • 完整API集合下載: /docs/api/postman-collection.json
  • 環境變數設定: /docs/api/postman-environment.json

文檔狀態: 🟢 已完成
最後更新: 2025-09-09
版本: v1.0
相關文檔:

  • 業務規則.md - 業務邏輯規則
  • 數據模型.md - 數據結構定義
  • ../mobile/ - 移動端功能規格
  • ../web/ - Web端功能規格
  • /swagger-ui.html - 互動式API文檔