155 lines
4.8 KiB
Markdown
155 lines
4.8 KiB
Markdown
# 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設計原則、回應格式、安全規範 | 設計標準 |
|
||
| **互動式文檔** | [swagger-ui.html](./swagger-ui.html) ✅ | Swagger UI界面、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日
|
||
**維護負責**: 技術團隊
|
||
**下次審查**: 每月第一週檢討更新 |