# Drama Ling API 規格文檔

## 📋 總覽
Drama Ling 應用的完整 RESTful API 規格文檔，採用模組化設計便於維護和擴展。

## 🏗️ API 架構

### Base URL
```
Production:  https://api.dramaling.com
Staging:     https://staging-api.dramaling.com  
Development: https://dev-api.dramaling.com
```

### 版本控制
所有 API 端點使用 `/api/v1/` 前綴進行版本控制。

## 📚 模組文檔導航

### 🔐 核心認證與用戶
| 模組 | 文檔 | 描述 | 端點數量 |
|------|------|------|----------|
| **認證與授權** | [authentication.md](./authentication.md) ✅ | JWT認證、登入、登出、第三方登入 | 6個 |
| **用戶管理** | [user-management.md](./user-management.md) ✅ | 用戶資料、個人檔案、學習統計 | 8個 |

### 🎓 學習核心功能
| 模組 | 文檔 | 描述 | 端點數量 |
|------|------|------|----------|
| **學習內容** | [learning-content.md](./learning-content.md) ⏳ | 課程、場景、內容管理 | 5個 |
| **對話練習** | [dialogue-practice.md](./dialogue-practice.md) ✅ | 對話系統、AI分析、回覆輔助 | 8個 |
| **詞彙系統** | [vocabulary.md](./vocabulary.md) ⏳ | 間隔複習、熟悉度練習、詞彙管理 | 8個 |

### 🎮 遊戲化與競爭
| 模組 | 文檔 | 描述 | 端點數量 |
|------|------|------|----------|
| **遊戲化系統** | [gamification.md](./gamification.md) ⏳ | 命條、時光挑戰、廣告獎勵、排行榜 | 15個 |

### 💳 商業功能
| 模組 | 文檔 | 描述 | 端點數量 |
|------|------|------|----------|
| **訂閱系統** | [subscription.md](./subscription.md) ✅ | 訂閱方案、內購驗證、權限管理 | 7個 |

### 🏆 進階功能  
| 模組 | 文檔 | 描述 | 端點數量 |
|------|------|------|----------|
| **特殊任務** | [daily-missions.md](./daily-missions.md) ✅ | 每日任務、獎勵系統、進度追蹤 | 6個 |
| **語言程度** | [language-levels.md](./language-levels.md) ⏳ | 13級程度系統、晉階機制 | 7個 |

### ⚙️ 系統支援
| 模組 | 文檔 | 描述 | 說明 |
|------|------|------|------|
| **錯誤處理** | [errors.md](./errors.md) ✅ | 標準錯誤碼、錯誤回應格式 | 11個錯誤類別 |
| **共通規範** | [common.md](./common.md) ✅ | API設計原則、回應格式、安全規範 | 設計標準 |

## 🔧 API 設計原則

### RESTful 標準
- ✅ 資源導向的URL設計
- ✅ 標準HTTP動詞 (GET, POST, PUT, DELETE, PATCH)
- ✅ 統一的HTTP狀態碼
- ✅ 無狀態設計
- ✅ 版本控制策略

### 安全原則
- ✅ JWT Token認證
- ✅ Role-based權限控制
- ✅ 嚴格資料驗證
- ✅ API速率限制
- ✅ 強制HTTPS傳輸

### 回應格式
所有API使用統一的JSON回應格式：
```json
{
  "success": boolean,
  "data": object | array | null,
  "message": string,
  "error": {
    "code": "ERROR_CODE",
    "message": "錯誤描述",
    "details": {}
  },
  "meta": {
    "timestamp": "2024-09-07T12:00:00Z",
    "request_id": "uuid-string",
    "pagination": {}
  }
}
```

## 📈 API 統計

### 整體規模
- **總端點數量**: 78個API端點
- **功能模組**: 10個主要模組
- **錯誤類別**: 11種錯誤類型
- **文檔行數**: ~2,400行 → 分拆為10個文件

### 開發狀態
- ✅ **已完成**: 7個核心模組 (認證、用戶、對話、訂閱、任務、錯誤、共通) (70%)
- 🔄 **進行中**: 剩餘4個模組拆分 (遊戲化、語言程度、詞彙、學習內容) (25%)  
- ⏳ **待優化**: API詳細範例和整合測試 (5%)

## 🚀 快速開始

### 1. 認證流程
```bash
# 用戶註冊
POST /api/v1/auth/register

# 用戶登入取得Token
POST /api/v1/auth/login

# 使用Token存取API
GET /api/v1/user/profile
Authorization: Bearer <access_token>
```

### 2. 常用API範例
- 取得學習統計：`GET /api/v1/user/learning-stats`
- 開始對話練習：`POST /api/v1/dialogues/start`
- 獲取今日任務：`GET /api/v1/missions/today`
- 檢查訂閱狀態：`GET /api/v1/subscriptions/status`

## 📖 相關文檔

### 技術文檔
- [資料庫架構設計](../database-schema.md)
- [第三方服務整合](../third-party-integration-specification.md)
- [Flutter/.NET整合指南](../flutter-dotnet-integration.md)

### 開發計劃
- [API完善計劃](../api-specifications-completion-plan.md)
- [技術選型決策](../tech-stack-decision.md)

## 🤝 貢獻指南

### 文檔維護
- 每個模組文件維持在200-400行
- 所有API端點需要完整範例
- 錯誤情境需要詳細說明
- 定期同步更新相關文檔

### 版本更新
- API變更需要版本控制
- 向後相容性考量
- 廢棄API提前通知機制

---

**文件版本**: v2.0 (模組化重構)  
**最後更新**: 2024年9月7日  
**維護負責**: 技術團隊  
**下次審查**: 每月第一週檢討更新