# 用戶管理 API

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

## 📌 API 端點

### 1. 獲取用戶資料
```http
GET /api/v1/users/profile
Authorization: Bearer <access_token>
```

#### 回應範例
```http
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. 更新用戶資料
```http
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
    }
  }
}
```

#### 回應範例
```http
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. 上傳用戶頭像
```http
POST /api/v1/users/avatar
Authorization: Bearer <access_token>
Content-Type: multipart/form-data

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

#### 回應範例
```http
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. 獲取用戶學習統計
```http
GET /api/v1/users/stats
Authorization: Bearer <access_token>
```

#### 查詢參數
- `period`: 統計週期 (`today`, `week`, `month`, `all`) - 預設 `all`
- `include_details`: 是否包含詳細分解 (`true`, `false`) - 預設 `false`

#### 回應範例
```http
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. 獲取詳細學習歷史
```http
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)

#### 回應範例
```http
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. 獲取成就系統
```http
GET /api/v1/users/achievements
Authorization: Bearer <access_token>
```

#### 回應範例
```http
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. 更新學習偏好設定
```http
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
  }
}
```

#### 回應範例
```http
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. 刪除用戶帳號
```http
DELETE /api/v1/users/account
Authorization: Bearer <access_token>
Content-Type: application/json

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

#### 回應範例
```http
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."
}
```

## 📊 資料結構

### 用戶偏好設定
```typescript
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';
}
```

### 學習統計
```typescript
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 | 帳號刪除失敗 |

### 錯誤回應範例
```http
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"
    }
  }
}
```

## 🛡️ 權限控制

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

### 訂閱用戶特殊權限
- **詳細統計**: 可存取更詳細的學習分析
- **高級偏好**: 可設定進階學習偏好
- **資料導出**: 可導出完整學習歷史

## 🧪 測試範例

### 取得用戶資料
```bash
curl -X GET "https://api.dramaling.com/api/v1/users/profile" \
  -H "Authorization: Bearer <access_token>" \
  -H "Accept: application/json"
```

### 更新偏好設定
```bash
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"}'
```

### 上傳頭像
```bash
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](./authentication.md), [訂閱系統API](./subscription.md)