feat: upgrade API specifications to v2.0 with comprehensive system integration
- 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 <noreply@anthropic.com>
This commit is contained in:
parent
8bddc3b06d
commit
f55007d2d8
|
|
@ -167,6 +167,136 @@ Authorization: Bearer <access_token>
|
||||||
|
|
||||||
## 📚 學習內容API
|
## 📚 學習內容API
|
||||||
|
|
||||||
|
### 獲取階段列表
|
||||||
|
```http
|
||||||
|
GET /stages
|
||||||
|
Authorization: Bearer <access_token>
|
||||||
|
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 <access_token>
|
||||||
|
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 <access_token>
|
||||||
|
```
|
||||||
|
|
||||||
|
**回應**:
|
||||||
|
```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
|
```http
|
||||||
GET /vocabulary
|
GET /vocabulary
|
||||||
|
|
@ -422,6 +552,149 @@ Query Parameters:
|
||||||
- limit: number (optional)
|
- limit: number (optional)
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### 使用時光卷
|
||||||
|
```http
|
||||||
|
POST /items/time-warp/use
|
||||||
|
Authorization: Bearer <access_token>
|
||||||
|
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 <access_token>
|
||||||
|
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 <access_token>
|
||||||
|
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 <access_token>
|
||||||
|
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
|
## 📊 分析與報告API
|
||||||
|
|
||||||
### 獲取學習分析
|
### 獲取學習分析
|
||||||
|
|
@ -466,6 +739,149 @@ Query Parameters:
|
||||||
- includePersonal: boolean
|
- includePersonal: boolean
|
||||||
```
|
```
|
||||||
|
|
||||||
|
## 🗣️ 口說評分系統API
|
||||||
|
|
||||||
|
### 提交語音進行評分
|
||||||
|
```http
|
||||||
|
POST /speaking/evaluate
|
||||||
|
Authorization: Bearer <access_token>
|
||||||
|
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 <access_token>
|
||||||
|
Query Parameters:
|
||||||
|
- contentType: string (optional)
|
||||||
|
- limit: number (optional)
|
||||||
|
- offset: number (optional)
|
||||||
|
```
|
||||||
|
|
||||||
|
## 🎭 語用分析系統API
|
||||||
|
|
||||||
|
### 對話語用分析
|
||||||
|
```http
|
||||||
|
POST /dialogue/pragmatic-analysis
|
||||||
|
Authorization: Bearer <access_token>
|
||||||
|
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 <access_token>
|
||||||
|
Query Parameters:
|
||||||
|
- scenario: string
|
||||||
|
- userLevel: string (optional) - beginner|intermediate|advanced
|
||||||
|
```
|
||||||
|
|
||||||
## 🔄 實時功能API
|
## 🔄 實時功能API
|
||||||
|
|
||||||
### WebSocket連接 (適用於Web端)
|
### WebSocket連接 (適用於Web端)
|
||||||
|
|
@ -613,11 +1029,14 @@ Retry-After: 60
|
||||||
---
|
---
|
||||||
|
|
||||||
**文檔狀態**: 🟢 已完成
|
**文檔狀態**: 🟢 已完成
|
||||||
**最後更新**: 2025-09-09
|
**最後更新**: 2025-09-12
|
||||||
**版本**: v1.0
|
**版本**: v2.0 - 新增口說評分、語用分析、階段系統、廣告系統API
|
||||||
**相關文檔**:
|
**相關文檔**:
|
||||||
- `業務規則.md` - 業務邏輯規則
|
- `business-rules.md` - 業務邏輯規則
|
||||||
- `數據模型.md` - 數據結構定義
|
- `data-models.md` - 數據結構定義
|
||||||
|
- `progressive-stage-system.md` - 線性闖關學習系統
|
||||||
|
- `speaking-evaluation-specs.md` - 口說評分系統規格
|
||||||
|
- `pragmatic-analysis-specs.md` - 語用分析系統規格
|
||||||
- `../mobile/` - 移動端功能規格
|
- `../mobile/` - 移動端功能規格
|
||||||
- `../web/` - Web端功能規格
|
- `../web/` - Web端功能規格
|
||||||
- `/swagger-ui.html` - 互動式API文檔
|
- `/swagger-ui.html` - 互動式API文檔
|
||||||
Loading…
Reference in New Issue