dramaling-app/docs/04_technical/02_api

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 ✅	JWT認證、登入、登出、第三方登入	6個
用戶管理	user-management.md ✅	用戶資料、個人檔案、學習統計	8個

🎓 學習核心功能

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

🎮 遊戲化與競爭

模組	文檔	描述	端點數量
遊戲化系統	gamification.md ⏳	命條、時光挑戰、廣告獎勵、排行榜	15個

💳 商業功能

模組	文檔	描述	端點數量
訂閱系統	subscription.md ✅	訂閱方案、內購驗證、權限管理	7個

🏆 進階功能

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

⚙️ 系統支援

模組	文檔	描述	說明
錯誤處理	errors.md ✅	標準錯誤碼、錯誤回應格式	11個錯誤類別
共通規範	common.md ✅	API設計原則、回應格式、安全規範	設計標準
互動式文檔	swagger-ui.html ✅	Swagger UI界面、API測試工具	互動式瀏覽

🔧 API 設計原則

RESTful 標準

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

安全原則

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

回應格式

所有API使用統一的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. 認證流程

# 用戶註冊
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

📖 相關文檔

技術文檔

• 資料庫架構設計
• 第三方服務整合
• Flutter/.NET整合指南

開發計劃

• API完善計劃
• 技術選型決策

🤝 貢獻指南

文檔維護

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

版本更新

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

---

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