From f55007d2d85a4fdd6db66843847cfcd1764111ef Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=84=AD=E6=B2=9B=E8=BB=92?= Date: Fri, 12 Sep 2025 00:31:43 +0800 Subject: [PATCH] feat: upgrade API specifications to v2.0 with comprehensive system integration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add speaking evaluation API with five-dimension scoring system - Implement pragmatic analysis API for dialogue communication assessment - Integrate stage and script management APIs for progressive learning system - Add advertisement system APIs with reward mechanisms and daily limits - Include time warp challenge API for bonus learning opportunities - Update vocabulary learning APIs to support multimedia learning structure - Enhance error codes and rate limiting for new API endpoints 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- .../common/api-specifications.md | 427 +++++++++++++++++- 1 file changed, 423 insertions(+), 4 deletions(-) diff --git a/docs/02_design/function-specs/common/api-specifications.md b/docs/02_design/function-specs/common/api-specifications.md index d143748..f84cb79 100644 --- a/docs/02_design/function-specs/common/api-specifications.md +++ b/docs/02_design/function-specs/common/api-specifications.md @@ -167,6 +167,136 @@ Authorization: Bearer ## 📚 學習內容API +### 獲取階段列表 +```http +GET /stages +Authorization: Bearer +Query Parameters: +- language: string (required) - 語言代碼 +- includeProgress: boolean (optional) - 是否包含進度資訊 +``` + +**回應**: +```typescript +interface StagesList { + stages: Array<{ + stageId: string; + stageName: string; + description: string; + order: number; + totalScripts: number; + unlockedScripts: number; + completedScripts: number; + isUnlocked: boolean; + progress: { + percentage: number; + starsEarned: number; + totalStars: number; + }; + }>; + userProgress: { + currentStageId: string; + overallProgress: number; + totalStarsEarned: number; + }; +} +``` + +### 獲取劇本列表 +```http +GET /scripts +Authorization: Bearer +Query Parameters: +- stageId: string (required) - 階段ID +- includeProgress: boolean (optional) +``` + +**回應**: +```typescript +interface ScriptsList { + scripts: Array<{ + scriptId: string; + scriptName: string; + sceneDescription: { + english: string; + chinese: string; + }; + plotOutline: string; + difficulty: number; + estimatedTime: number; + levels: { + vocabulary: LevelStatus; + mastery: LevelStatus; + speaking?: LevelStatus; // 可選關卡 + dialogue: LevelStatus; + }; + isUnlocked: boolean; + requiredVocabulary: string[]; // 詞彙預覽 + }>; +} + +interface LevelStatus { + isUnlocked: boolean; + isCompleted: boolean; + stars: number; + bestScore?: number; +} +``` + +### 獲取劇本詳情 +```http +GET /scripts/{scriptId} +Authorization: Bearer +``` + +**回應**: +```typescript +interface ScriptDetail { + scriptId: string; + scriptName: string; + sceneDescription: { + english: string; + chinese: string; + }; + plotOutline: string; + openingDialogue: Array<{ + character: string; + english: string; + chinese: string; + userRole: boolean; + }>; + plotTasks: Array<{ + taskDescription: string; + exampleEnglish: string; + exampleChinese: string; + }>; + requiredVocabulary: VocabularyDetail[]; + levels: { + vocabulary: DetailedLevelInfo; + mastery: DetailedLevelInfo; + speaking?: DetailedLevelInfo; + dialogue: DetailedLevelInfo; + }; +} + +interface DetailedLevelInfo { + levelType: string; + isUnlocked: boolean; + isCompleted: boolean; + stars: number; + lifePointsCost: number; + diamondsCost?: number; // 僅口說練習關卡 + description: string; + estimatedTime: number; + prerequisites: string[]; + rewards: { + xp: number; + diamonds?: number; + items?: string[]; + }; +} +``` + ### 獲取詞彙列表 ```http GET /vocabulary @@ -422,6 +552,149 @@ Query Parameters: - limit: number (optional) ``` +### 使用時光卷 +```http +POST /items/time-warp/use +Authorization: Bearer +Content-Type: application/json + +{ + "itemId": "time_warp_scroll_uuid", + "preferredStages": string[] // 用戶偏好的階段ID (可選) +} +``` + +**回應**: +```typescript +interface TimeWarpChallengeResponse { + challengeId: string; + selectedScript: { + scriptId: string; + scriptName: string; + stageId: string; + stageName: string; + isFromPreviousStage: boolean; + }; + challenge: { + type: "dialogue"; // 目前固定為對話訓練 + timeLimit: number; // 挑戰時間限制(秒) + specialRewards: { + bonus_xp: number; + bonus_diamonds: number; + vocabulary_review: boolean; // 詞彙加入複習清單 + }; + }; + sessionData: any; // 關卡具體數據 +} +``` + +## 📺 廣告系統API + +### 請求觀看廣告 +```http +POST /ads/request +Authorization: Bearer +Content-Type: application/json + +{ + "adType": "life_points_restore" | "bonus_rewards" | "unlock_content", + "context": { + "currentLifePoints": number, + "maxLifePoints": number, + "sessionId"?: string, + "itemType"?: string // 額外獎勵的道具類型 + } +} +``` + +**回應**: +```typescript +interface AdRequestResponse { + adAvailable: boolean; + adId?: string; + adProvider: "google_admob" | "unity_ads" | "facebook_ads"; + estimatedDuration: number; // 預估廣告時長(秒) + rewards: { + lifePoints?: number; // 恢復的命條數量 + diamonds?: number; // 獲得鑽石 + xp?: number; // 額外經驗值 + items?: string[]; // 獲得道具ID列表 + }; + cooldownTime?: number; // 下次可觀看時間(秒) + dailyLimit: { + watched: number; + maximum: number; + }; +} +``` + +### 完成廣告觀看 +```http +POST /ads/complete +Authorization: Bearer +Content-Type: application/json + +{ + "adId": string, + "adProvider": string, + "watchDuration": number, // 實際觀看時長(秒) + "completed": boolean, // 是否完整觀看 + "rewardClaimed": boolean // 是否領取獎勵 +} +``` + +**回應**: +```typescript +interface AdCompleteResponse { + success: boolean; + rewardsGranted: { + lifePoints?: number; + diamonds?: number; + xp?: number; + items?: Array<{ + itemId: string; + quantity: number; + name: string; + }>; + }; + updatedUserStats: { + currentLifePoints: number; + totalDiamonds: number; + totalXP: number; + }; + nextAdAvailableAt?: string; // ISO timestamp +} +``` + +### 獲取廣告狀態 +```http +GET /ads/status +Authorization: Bearer +Query Parameters: +- adType: string (optional) +``` + +**回應**: +```typescript +interface AdStatusResponse { + dailyStats: { + adsWatched: number; + maxAdsPerDay: number; + resetTime: string; // ISO timestamp + }; + availableAdTypes: Array<{ + type: string; + available: boolean; + cooldownEndsAt?: string; // ISO timestamp + estimatedReward: any; + }>; + userPreferences: { + adsEnabled: boolean; + preferredProviders: string[]; + }; +} +``` + ## 📊 分析與報告API ### 獲取學習分析 @@ -466,6 +739,149 @@ Query Parameters: - includePersonal: boolean ``` +## 🗣️ 口說評分系統API + +### 提交語音進行評分 +```http +POST /speaking/evaluate +Authorization: Bearer +Content-Type: multipart/form-data + +{ + "audioFile": File, // 語音文件 (wav/mp3) + "sessionId": "session_uuid", // 學習會話ID + "contentType": "vocabulary" | "dialogue" | "pronunciation", + "targetText": string, // 預期文本內容 + "language": "en" | "zh-TW", + "evaluationType": "five_dimension" | "basic" +} +``` + +**回應**: +```typescript +interface SpeakingEvaluation { + sessionId: string; + overallScore: number; // 0-100 總分 + dimensions: { + pronunciation: number; // 發音評分 + completeness: number; // 完整度評分 + fluency: number; // 流暢度評分 + prosody: number; // 韻律評分 + accuracy: number; // 準確度評分 + }; + detailedFeedback: { + problemWords: Array<{ + word: string; + issues: string[]; // 發音問題描述 + phonemes: string[]; // 問題音素 + }>; + suggestions: string[]; // 改善建議 + strengths: string[]; // 優點反饋 + }; + rewards?: { + diamonds: number; + xp: number; + items?: string[]; // 獲得道具 (如時光卷) + }; +} +``` + +### 獲取口說評分歷史 +```http +GET /speaking/history +Authorization: Bearer +Query Parameters: +- contentType: string (optional) +- limit: number (optional) +- offset: number (optional) +``` + +## 🎭 語用分析系統API + +### 對話語用分析 +```http +POST /dialogue/pragmatic-analysis +Authorization: Bearer +Content-Type: application/json + +{ + "sessionId": "session_uuid", + "userMessage": string, + "dialogueContext": { + "scenario": string, + "previousTurns": Array<{ + "speaker": "user" | "ai", + "message": string, + "timestamp": string + }>, + "intents": string[] // 預期完成的意圖任務 + } +} +``` + +**回應**: +```typescript +interface PragmaticAnalysis { + sessionId: string; + analysisId: string; + dimensions: { + smallTalk: { + present: boolean; + examples?: string[]; + suggestions?: string[]; + }; + indirectness: { + level: "direct" | "moderately_indirect" | "highly_indirect"; + examples?: string[]; + culturalNotes?: string[]; + }; + fillers: { + count: number; + types: string[]; + appropriateness: "natural" | "excessive" | "insufficient"; + }; + backchanneling: { + present: boolean; + effectiveness: "good" | "adequate" | "needs_improvement"; + examples?: string[]; + }; + hedging: { + level: "confident" | "appropriately_cautious" | "overly_cautious"; + examples?: string[]; + }; + idioms: { + used: Array<{ + idiom: string; + appropriateness: "perfect" | "good" | "awkward"; + culturalFit: boolean; + }>; + suggestions?: string[]; + }; + }; + overallAssessment: { + communicativeEffectiveness: "excellent" | "good" | "adequate" | "needs_work"; + culturalApproppriateness: "excellent" | "good" | "adequate" | "needs_work"; + suggestions: string[]; + strengths: string[]; + }; + intentCompletion: { + completedIntents: string[]; + partialIntents: string[]; + missedIntents: string[]; + completionRate: number; // 0-100 + }; +} +``` + +### 獲取語用分析建議 +```http +GET /dialogue/pragmatic-suggestions +Authorization: Bearer +Query Parameters: +- scenario: string +- userLevel: string (optional) - beginner|intermediate|advanced +``` + ## 🔄 實時功能API ### WebSocket連接 (適用於Web端) @@ -613,11 +1029,14 @@ Retry-After: 60 --- **文檔狀態**: 🟢 已完成 -**最後更新**: 2025-09-09 -**版本**: v1.0 +**最後更新**: 2025-09-12 +**版本**: v2.0 - 新增口說評分、語用分析、階段系統、廣告系統API **相關文檔**: -- `業務規則.md` - 業務邏輯規則 -- `數據模型.md` - 數據結構定義 +- `business-rules.md` - 業務邏輯規則 +- `data-models.md` - 數據結構定義 +- `progressive-stage-system.md` - 線性闖關學習系統 +- `speaking-evaluation-specs.md` - 口說評分系統規格 +- `pragmatic-analysis-specs.md` - 語用分析系統規格 - `../mobile/` - 移動端功能規格 - `../web/` - Web端功能規格 - `/swagger-ui.html` - 互動式API文檔 \ No newline at end of file