鄭沛軒
937f6994eb
Major refactoring of API documentation for better maintainability: ## New Modular Structure - Split 2400+ line monolithic API spec into 10 focused modules - Created centralized navigation at docs/04_technical/api/README.md - Each module now 200-400 lines for easier maintenance ## Completed API Modules (7/10) - ✅ Authentication & Authorization API (JWT, OAuth, permissions) - ✅ User Management API (profiles, stats, achievements) - ✅ Dialogue Practice API (scenarios, AI analysis, assistance) - ✅ Subscription System API (in-app purchases, permissions) - ✅ Daily Missions API (tasks, progress, rewards) - ✅ Error Handling (comprehensive error codes) - ✅ Common Standards (RESTful principles, formats) ## Updated Specifications - Third-party integration spec with iOS/Android in-app purchases - API completion plan with 3-phase development strategy - Organized processed requirements in 已處理/ folder ## Technical Improvements - 35+ API endpoints fully documented with examples - 11 error categories with handling guidelines - Unified response formats and security standards - Team-friendly parallel development structure 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com> |
||
|---|---|---|
| .. | ||
| README.md | ||
| authentication.md | ||
| common.md | ||
| daily-missions.md | ||
| dialogue-practice.md | ||
| errors.md | ||
| subscription.md | ||
| user-management.md | ||
README.md
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設計原則、回應格式、安全規範 | 設計標準 |
🔧 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
📖 相關文檔
技術文檔
開發計劃
🤝 貢獻指南
文檔維護
- 每個模組文件維持在200-400行
- 所有API端點需要完整範例
- 錯誤情境需要詳細說明
- 定期同步更新相關文檔
版本更新
- API變更需要版本控制
- 向後相容性考量
- 廢棄API提前通知機制
文件版本: v2.0 (模組化重構)
最後更新: 2024年9月7日
維護負責: 技術團隊
下次審查: 每月第一週檢討更新