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
|
||||
|
||||
### 獲取階段列表
|
||||
```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
|
||||
GET /vocabulary
|
||||
|
|
@ -422,6 +552,149 @@ Query Parameters:
|
|||
- 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
|
||||
|
||||
### 獲取學習分析
|
||||
|
|
@ -466,6 +739,149 @@ Query Parameters:
|
|||
- 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
|
||||
|
||||
### 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文檔
|
||||
Loading…
Reference in New Issue