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

10 KiB
Raw Blame History

LinguaForge API 規格文件

API 基礎資訊

Base URL

Development: https://api-dev.linguaforge.com/v1
Production: https://api.linguaforge.com/v1

認證方式

Authorization: Bearer <JWT_TOKEN>

通用回應格式

{
  "success": true,
  "data": { ... },
  "message": "操作成功",
  "timestamp": "2024-01-15T10:30:00Z"
}

錯誤回應格式

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "錯誤描述",
    "details": { ... }
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

1. 認證相關 API

1.1 使用者註冊

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

{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "username": "johndoe",
  "acceptTerms": true
}

Response 201:
{
  "success": true,
  "data": {
    "userId": "uuid",
    "email": "user@example.com",
    "username": "johndoe",
    "emailVerificationRequired": true
  },
  "message": "註冊成功，請查收驗證郵件"
}

1.2 使用者登入

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

{
  "email": "user@example.com",
  "password": "SecurePassword123!"
}

Response 200:
{
  "success": true,
  "data": {
    "accessToken": "eyJhbGc...",
    "refreshToken": "eyJhbGc...",
    "expiresIn": 900,
    "user": {
      "id": "uuid",
      "email": "user@example.com",
      "username": "johndoe"
    }
  }
}

1.3 重新整理 Token

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

{
  "refreshToken": "eyJhbGc..."
}

Response 200:
{
  "success": true,
  "data": {
    "accessToken": "eyJhbGc...",
    "expiresIn": 900
  }
}

1.4 登出

POST /auth/logout
Authorization: Bearer <token>

Response 200:
{
  "success": true,
  "message": "登出成功"
}

2. 詞卡管理 API

2.1 取得詞卡列表

GET /cards?page=1&limit=20&sort=createdAt&order=desc
Authorization: Bearer <token>

Response 200:
{
  "success": true,
  "data": {
    "cards": [
      {
        "id": "uuid",
        "word": "abandon",
        "definition": "放棄、遺棄",
        "examples": ["He abandoned his car in the snow."],
        "imageUrl": "https://...",
        "audioUrl": "https://...",
        "nextReviewDate": "2024-01-16T10:00:00Z",
        "easinessFactor": 2.5,
        "repetitionCount": 3,
        "createdAt": "2024-01-10T10:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "pages": 8
    }
  }
}

2.2 取得單一詞卡

GET /cards/:cardId
Authorization: Bearer <token>

Response 200:
{
  "success": true,
  "data": {
    "id": "uuid",
    "word": "abandon",
    "definition": "放棄、遺棄",
    "examples": [
      "He abandoned his car in the snow.",
      "They had to abandon the ship."
    ],
    "sourceSentence": "I need to abandon this bad habit.",
    "imageUrl": "https://...",
    "audioUrl": "https://...",
    "pronunciation": "/əˈbændən/",
    "partOfSpeech": "verb",
    "difficulty": "medium",
    "tags": ["常用", "動詞"],
    "nextReviewDate": "2024-01-16T10:00:00Z",
    "reviewHistory": [
      {
        "date": "2024-01-15T10:00:00Z",
        "quality": 4,
        "timeSpent": 15
      }
    ]
  }
}

2.3 AI 生成詞卡

POST /cards/generate
Authorization: Bearer <token>
Content-Type: application/json

{
  "sentence": "I need to abandon this bad habit immediately.",
  "targetWord": "abandon"
}

Response 201:
{
  "success": true,
  "data": {
    "id": "uuid",
    "word": "abandon",
    "definition": "to give up or discontinue something",
    "examples": [
      "He abandoned his car in the snow.",
      "They had to abandon the ship."
    ],
    "pronunciation": "/əˈbændən/",
    "partOfSpeech": "verb",
    "imageUrl": "https://...",
    "audioUrl": "https://...",
    "aiGenerated": true,
    "generationMetadata": {
      "model": "gemini-pro",
      "confidence": 0.95
    }
  }
}

2.4 更新詞卡

PUT /cards/:cardId
Authorization: Bearer <token>
Content-Type: application/json

{
  "definition": "放棄、拋棄",
  "examples": ["新例句1", "新例句2"],
  "tags": ["更新標籤"]
}

Response 200:
{
  "success": true,
  "data": { ... },
  "message": "詞卡更新成功"
}

2.5 刪除詞卡

DELETE /cards/:cardId
Authorization: Bearer <token>

Response 200:
{
  "success": true,
  "message": "詞卡刪除成功"
}

3. 複習系統 API

3.1 取得今日複習詞卡

GET /review/today?limit=20
Authorization: Bearer <token>

Response 200:
{
  "success": true,
  "data": {
    "reviewCards": [
      {
        "id": "uuid",
        "word": "abandon",
        "nextReviewDate": "2024-01-15T10:00:00Z",
        "overduedays": 0,
        "priority": "high"
      }
    ],
    "totalCount": 15,
    "newCards": 5,
    "reviewCards": 10
  }
}

3.2 提交複習結果

POST /review/submit
Authorization: Bearer <token>
Content-Type: application/json

{
  "cardId": "uuid",
  "quality": 4,
  "timeSpent": 15,
  "sessionId": "uuid"
}

Response 200:
{
  "success": true,
  "data": {
    "nextReviewDate": "2024-01-17T10:00:00Z",
    "newInterval": 3,
    "newEasinessFactor": 2.6,
    "streakDays": 7
  }
}

3.3 開始複習會話

POST /review/session/start
Authorization: Bearer <token>

Response 201:
{
  "success": true,
  "data": {
    "sessionId": "uuid",
    "startedAt": "2024-01-15T10:00:00Z",
    "cardsToReview": 15
  }
}

3.4 結束複習會話

POST /review/session/:sessionId/end
Authorization: Bearer <token>

Response 200:
{
  "success": true,
  "data": {
    "sessionId": "uuid",
    "duration": 300,
    "cardsReviewed": 15,
    "accuracy": 0.87,
    "stats": {
      "perfect": 5,
      "good": 8,
      "hard": 2,
      "again": 0
    }
  }
}

4. 語音評估 API

4.1 提交語音評估

POST /speech/assess
Authorization: Bearer <token>
Content-Type: multipart/form-data

FormData:
- audio: <audio_file>
- text: "I need to abandon this bad habit"
- cardId: "uuid" (optional)

Response 200:
{
  "success": true,
  "data": {
    "assessmentId": "uuid",
    "scores": {
      "accuracy": 85.5,
      "fluency": 72.3,
      "completeness": 100,
      "pronunciation": 86.2
    },
    "phonemes": [
      {
        "phoneme": "aɪ",
        "accuracy": 95
      }
    ],
    "words": [
      {
        "word": "abandon",
        "accuracy": 82,
        "errorType": null
      }
    ],
    "suggestions": [
      "注意 'abandon' 的重音在第二個音節"
    ]
  }
}

4.2 取得評估歷史

GET /speech/history?cardId=uuid&page=1&limit=10
Authorization: Bearer <token>

Response 200:
{
  "success": true,
  "data": {
    "assessments": [
      {
        "id": "uuid",
        "text": "I need to abandon this bad habit",
        "pronunciationScore": 86.2,
        "assessedAt": "2024-01-15T10:00:00Z"
      }
    ],
    "pagination": { ... }
  }
}

5. 學習統計 API

5.1 取得學習統計

GET /stats/overview?period=week
Authorization: Bearer <token>

Response 200:
{
  "success": true,
  "data": {
    "period": "week",
    "stats": {
      "totalCards": 150,
      "cardsReviewed": 105,
      "newCards": 15,
      "studyTime": 3600,
      "accuracy": 0.85,
      "streakDays": 7
    },
    "dailyStats": [
      {
        "date": "2024-01-15",
        "cardsReviewed": 20,
        "newCards": 3,
        "studyTime": 600,
        "accuracy": 0.90
      }
    ],
    "achievements": [
      {
        "id": "7day_streak",
        "name": "7天連續學習",
        "unlockedAt": "2024-01-15T10:00:00Z"
      }
    ]
  }
}

5.2 取得學習進度

GET /stats/progress
Authorization: Bearer <token>

Response 200:
{
  "success": true,
  "data": {
    "totalWords": 150,
    "mastered": 45,
    "learning": 80,
    "new": 25,
    "retention": {
      "mature": 0.92,
      "young": 0.85
    },
    "forecast": {
      "tomorrow": 18,
      "thisWeek": 126
    }
  }
}

6. 使用者設定 API

6.1 取得使用者偏好

GET /user/preferences
Authorization: Bearer <token>

Response 200:
{
  "success": true,
  "data": {
    "dailyReviewGoal": 20,
    "reviewReminderTime": "09:00",
    "pushNotifications": true,
    "uiLanguage": "zh-TW",
    "learningLanguage": "en-US",
    "studySettings": {
      "autoPlay": true,
      "showImages": true,
      "reviewOrder": "random"
    }
  }
}

6.2 更新使用者偏好

PUT /user/preferences
Authorization: Bearer <token>
Content-Type: application/json

{
  "dailyReviewGoal": 30,
  "pushNotifications": false
}

Response 200:
{
  "success": true,
  "message": "偏好設定更新成功"
}

7. 訂閱管理 API

7.1 取得訂閱方案

GET /subscriptions/plans
Authorization: Bearer <token>

Response 200:
{
  "success": true,
  "data": {
    "plans": [
      {
        "id": "uuid",
        "name": "免費版",
        "tier": "free",
        "monthlyPrice": 0,
        "features": ["每日20張詞卡", "基礎統計"]
      },
      {
        "id": "uuid",
        "name": "專業版",
        "tier": "premium",
        "monthlyPrice": 9.99,
        "yearlyPrice": 99.99,
        "features": ["無限詞卡", "進階統計", "語音評估", "離線使用"]
      }
    ]
  }
}

7.2 訂閱方案

POST /subscriptions/subscribe
Authorization: Bearer <token>
Content-Type: application/json

{
  "planId": "uuid",
  "billingPeriod": "monthly",
  "paymentMethod": "credit_card"
}

Response 201:
{
  "success": true,
  "data": {
    "subscriptionId": "uuid",
    "status": "active",
    "expiresAt": "2024-02-15T10:00:00Z",
    "paymentUrl": "https://payment-gateway.com/..."
  }
}

錯誤代碼對照表

錯誤代碼 HTTP 狀態碼 說明
AUTH_INVALID_CREDENTIALS 401 無效的登入憑證
AUTH_TOKEN_EXPIRED 401 Token 已過期
AUTH_UNAUTHORIZED 403 無權限存取
VALIDATION_ERROR 400 輸入資料驗證失敗
RESOURCE_NOT_FOUND 404 資源不存在
DUPLICATE_RESOURCE 409 資源已存在
RATE_LIMIT_EXCEEDED 429 超過請求頻率限制
INTERNAL_SERVER_ERROR 500 伺服器內部錯誤
SERVICE_UNAVAILABLE 503 服務暫時不可用