jettcheng1018
/
dramaling-app
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
dramaling-app/docs/04_technical/api/user-management.md

12 KiB
Raw Blame History

用戶管理 API

📋 概述

用戶資料管理、個人檔案設定、學習統計等功能的 API 端點。

📌 API 端點

1. 獲取用戶資料

GET /api/v1/users/profile
Authorization: Bearer <access_token>

回應範例

Response 200 OK
{
  "success": true,
  "data": {
    "user_id": "USR_12345",
    "username": "dramatic_learner",
    "email": "user@example.com",
    "avatar_url": "https://cdn.dramaling.com/avatars/12345.jpg",
    "display_name": "學習者",
    "level": "B1",
    "level_progress": {
      "current_level": "B1",
      "progress_percentage": 65,
      "total_perfect_dialogues": 23,
      "required_perfect_dialogues": 30
    },
    "total_score": 15680,
    "streak_days": 15,
    "joined_date": "2024-01-15T08:00:00Z",
    "last_active": "2024-09-05T14:30:00Z",
    "preferences": {
      "target_language": "en",
      "native_language": "zh-TW",
      "difficulty_preference": "adaptive",
      "daily_goal_minutes": 30,
      "notifications_enabled": true,
      "push_notifications": {
        "daily_reminder": true,
        "streak_milestone": true,
        "achievement_unlock": false
      },
      "theme": "light",
      "auto_play_audio": true,
      "subtitle_display": "always"
    },
    "subscription": {
      "plan": "premium",
      "status": "active",
      "started_at": "2024-01-15T08:00:00Z",
      "expires_at": "2025-01-15T08:00:00Z",
      "auto_renewal": true,
      "platform": "ios" // ios, android, web
    }
  },
  "meta": {
    "timestamp": "2024-09-07T12:00:00Z",
    "cache_expires_at": "2024-09-07T12:05:00Z"
  }
}

2. 更新用戶資料

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

{
  "username": "new_username",
  "display_name": "新暱稱",
  "avatar_url": "https://cdn.dramaling.com/avatars/new_avatar.jpg",
  "preferences": {
    "daily_goal_minutes": 45,
    "notifications_enabled": false,
    "theme": "dark",
    "push_notifications": {
      "daily_reminder": false,
      "streak_milestone": true
    }
  }
}

回應範例

Response 200 OK
{
  "success": true,
  "data": {
    "updated_fields": [
      "username", 
      "display_name", 
      "preferences.daily_goal_minutes",
      "preferences.notifications_enabled",
      "preferences.theme"
    ],
    "profile": {
      "user_id": "USR_12345",
      "username": "new_username",
      "display_name": "新暱稱",
      "preferences": {
        "daily_goal_minutes": 45,
        "notifications_enabled": false,
        "theme": "dark"
      }
    }
  },
  "message": "Profile updated successfully"
}

資料驗證規則

  • username: 3-20字元，僅允許字母數字和底線
  • display_name: 1-30字元，支援中英文
  • daily_goal_minutes: 5-180分鐘
  • avatar_url: 有效的URL格式

3. 上傳用戶頭像

POST /api/v1/users/avatar
Authorization: Bearer <access_token>
Content-Type: multipart/form-data

Form Data:
- avatar: [Image File] (JPG, PNG, max 5MB)

回應範例

Response 200 OK
{
  "success": true,
  "data": {
    "avatar_url": "https://cdn.dramaling.com/avatars/USR_12345_20240907.jpg",
    "thumbnail_url": "https://cdn.dramaling.com/avatars/thumbs/USR_12345_20240907.jpg",
    "upload_timestamp": "2024-09-07T12:00:00Z"
  },
  "message": "Avatar uploaded successfully"
}

4. 獲取用戶學習統計

GET /api/v1/users/stats
Authorization: Bearer <access_token>

查詢參數

  • period: 統計週期 (today, week, month, all) - 預設 all
  • include_details: 是否包含詳細分解 (true, false) - 預設 false

回應範例

Response 200 OK
{
  "success": true,
  "data": {
    "summary": {
      "total_dialogues": 245,
      "total_study_time": 1280, // minutes
      "vocabulary_learned": 890,
      "vocabulary_mastered": 650,
      "scenarios_completed": 35,
      "achievements_unlocked": 18,
      "perfect_dialogues": 89
    },
    "streaks": {
      "current_streak": 15,
      "longest_streak": 28,
      "streak_start_date": "2024-08-23T00:00:00Z"
    },
    "weekly_progress": {
      "dialogues_this_week": 12,
      "minutes_this_week": 180,
      "vocabulary_this_week": 45,
      "daily_goal_minutes": 30,
      "goal_completion_rate": 0.85,
      "days_active_this_week": 6
    },
    "monthly_progress": {
      "dialogues_this_month": 52,
      "minutes_this_month": 780,
      "vocabulary_this_month": 189,
      "monthly_goal_completion": 0.92
    },
    "level_progression": {
      "current_level": "B1",
      "level_start_date": "2024-08-01T00:00:00Z",
      "progress_in_current_level": 0.65,
      "perfect_dialogues_in_level": 23,
      "required_for_next_level": 30,
      "estimated_days_to_next_level": 12
    }
  }
}

5. 獲取詳細學習歷史

GET /api/v1/users/learning-history
Authorization: Bearer <access_token>

查詢參數

  • start_date: 開始日期 (ISO 8601)
  • end_date: 結束日期 (ISO 8601)
  • activity_type: 活動類型 (dialogue, vocabulary, mission, all)
  • page: 頁碼 (預設 1)
  • limit: 每頁筆數 (預設 20, 最大 100)

回應範例

Response 200 OK
{
  "success": true,
  "data": {
    "activities": [
      {
        "activity_id": "ACT_12345",
        "type": "dialogue",
        "scenario_id": "restaurant_order",
        "scenario_name": "餐廳點餐",
        "score": 85,
        "is_perfect": false,
        "duration_minutes": 12,
        "vocabulary_learned": 5,
        "completed_at": "2024-09-07T11:30:00Z"
      },
      {
        "activity_id": "ACT_12346",
        "type": "vocabulary",
        "practice_type": "spaced_repetition",
        "words_reviewed": 20,
        "words_mastered": 15,
        "accuracy_rate": 0.75,
        "completed_at": "2024-09-07T10:15:00Z"
      },
      {
        "activity_id": "ACT_12347",
        "type": "mission",
        "mission_id": "daily_dialogue_3",
        "mission_name": "今日對話練習 3次",
        "progress": "3/3",
        "reward_diamonds": 50,
        "completed_at": "2024-09-07T09:45:00Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_items": 89,
      "items_per_page": 20
    }
  }
}

6. 獲取成就系統

GET /api/v1/users/achievements
Authorization: Bearer <access_token>

回應範例

Response 200 OK
{
  "success": true,
  "data": {
    "unlocked_achievements": [
      {
        "achievement_id": "first_dialogue",
        "name": "初次對話",
        "description": "完成第一次對話練習",
        "icon_url": "https://cdn.dramaling.com/achievements/first_dialogue.png",
        "unlocked_at": "2024-01-15T10:30:00Z",
        "rarity": "common"
      },
      {
        "achievement_id": "week_streak_1",
        "name": "週連擊手",
        "description": "連續學習7天",
        "icon_url": "https://cdn.dramaling.com/achievements/week_streak.png",
        "unlocked_at": "2024-01-22T09:15:00Z",
        "rarity": "uncommon"
      }
    ],
    "available_achievements": [
      {
        "achievement_id": "perfect_score_10",
        "name": "完美十連",
        "description": "獲得10次滿分對話",
        "icon_url": "https://cdn.dramaling.com/achievements/perfect_10.png",
        "progress": {
          "current": 7,
          "required": 10
        },
        "rarity": "rare"
      }
    ],
    "achievement_stats": {
      "total_unlocked": 18,
      "total_available": 45,
      "completion_percentage": 0.4,
      "rarity_breakdown": {
        "common": 12,
        "uncommon": 5,
        "rare": 1,
        "epic": 0,
        "legendary": 0
      }
    }
  }
}

7. 更新學習偏好設定

PATCH /api/v1/users/preferences
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "target_language": "en",
  "difficulty_preference": "challenging",
  "daily_goal_minutes": 60,
  "auto_play_audio": false,
  "push_notifications": {
    "daily_reminder": true,
    "streak_milestone": false,
    "achievement_unlock": true
  }
}

回應範例

Response 200 OK
{
  "success": true,
  "data": {
    "updated_preferences": {
      "target_language": "en",
      "difficulty_preference": "challenging",
      "daily_goal_minutes": 60,
      "auto_play_audio": false,
      "push_notifications": {
        "daily_reminder": true,
        "streak_milestone": false,
        "achievement_unlock": true
      }
    }
  },
  "message": "Preferences updated successfully"
}

8. 刪除用戶帳號

DELETE /api/v1/users/account
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "password": "current_password",
  "confirmation": "DELETE_MY_ACCOUNT"
}

回應範例

Response 200 OK
{
  "success": true,
  "data": {
    "deletion_scheduled_at": "2024-09-14T12:00:00Z",
    "grace_period_days": 7,
    "cancellation_token": "CANCEL_DEL_TOKEN_12345"
  },
  "message": "Account deletion scheduled. You have 7 days to cancel."
}

📊 資料結構

用戶偏好設定

interface UserPreferences {
  target_language: string;        // ISO 639-1 語言碼
  native_language: string;        // ISO 639-1 語言碼  
  difficulty_preference: 'easy' | 'adaptive' | 'challenging';
  daily_goal_minutes: number;     // 5-180
  notifications_enabled: boolean;
  push_notifications: {
    daily_reminder: boolean;
    streak_milestone: boolean;
    achievement_unlock: boolean;
  };
  theme: 'light' | 'dark' | 'auto';
  auto_play_audio: boolean;
  subtitle_display: 'always' | 'never' | 'learning_mode';
}

學習統計

interface LearningStats {
  total_dialogues: number;
  total_study_time: number;       // minutes
  vocabulary_learned: number;
  vocabulary_mastered: number;
  scenarios_completed: number;
  achievements_unlocked: number;
  perfect_dialogues: number;
  current_streak: number;
  longest_streak: number;
}

🔧 錯誤處理

用戶管理相關錯誤

錯誤碼 HTTP狀態 描述
USER_NOT_FOUND 404 用戶不存在
PROFILE_UPDATE_FAILED 400 個人資料更新失敗
AVATAR_UPLOAD_FAILED 400 頭像上傳失敗
INVALID_PREFERENCES 400 偏好設定無效
USERNAME_TAKEN 409 用戶名已被使用
AVATAR_TOO_LARGE 413 頭像檔案過大
ACCOUNT_DELETION_FAILED 400 帳號刪除失敗

錯誤回應範例

Response 400 Bad Request
{
  "success": false,
  "error": {
    "code": "PROFILE_UPDATE_FAILED",
    "message": "個人資料更新失敗",
    "details": {
      "field": "username",
      "reason": "Username must be 3-20 characters",
      "provided_value": "ab"
    }
  }
}

🛡️ 權限控制

資料存取權限

  • 個人資料: 只能存取和修改自己的資料
  • 學習統計: 只能查看自己的統計資料
  • 成就系統: 只能查看自己的成就進度
  • 帳號刪除: 需要密碼驗證

訂閱用戶特殊權限

  • 詳細統計: 可存取更詳細的學習分析
  • 高級偏好: 可設定進階學習偏好
  • 資料導出: 可導出完整學習歷史

🧪 測試範例

取得用戶資料

curl -X GET "https://api.dramaling.com/api/v1/users/profile" \
  -H "Authorization: Bearer <access_token>" \
  -H "Accept: application/json"

更新偏好設定

curl -X PATCH "https://api.dramaling.com/api/v1/users/preferences" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"daily_goal_minutes": 45, "theme": "dark"}'

上傳頭像

curl -X POST "https://api.dramaling.com/api/v1/users/avatar" \
  -H "Authorization: Bearer <access_token>" \
  -F "avatar=@/path/to/avatar.jpg"

模組負責人: 後端團隊
最後更新: 2024年9月7日
相關文檔: 認證API, 訂閱系統API