jettcheng1018
/
dramaling-vocab-learning
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: 整理AI句子分析功能規格文檔到note目錄 

📁 文檔重組:
• 將AI句子分析相關規格文檔移至note/AI句子分析規格目錄
• 統一文檔管理和版本控制
• 提升文檔可讀性和查找效率

📋 包含文檔:
• AI分析API技術實現規格.md - 技術實現細節
• AI句子分析功能產品需求規格.md - 產品需求與用戶故事
• DramaLing AI句子分析功能前後端串接實施計劃.md - 實施計劃與進度
• 文件結構說明.md - 文檔結構說明
• 系統整合與部署規格.md - 部署和整合指南

🎯 改善效果:
• 文檔結構清晰化
• 便於開發團隊查閱
• 支援未來功能擴展

🚀 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
鄭沛軒 2025-09-23 02:44:21 +08:00
parent a2c2ada8a9
commit ad919ec5b7
5 changed files with 3247 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

815
note/AI句子分析規格/AI分析API技術實現規格.md Normal file
View File

@ -0,0 +1,815 @@
# AI分析API技術實現規格
## 📋 **文件資訊**
- **文件名稱**: AI分析API技術實現規格
- **版本**: v2.0
- **建立日期**: 2025-01-25
- **最後更新**: 2025-01-25
- **負責團隊**: DramaLing後端技術團隊
- **對應產品需求**: 《AI句子分析功能產品需求規格》
---
## 🛠 **技術架構概述**
### **系統架構設計**
```yaml
分層架構:
- API Gateway: 認證、限流、路由
- Controllers: HTTP請求處理、參數驗證
- Services: 業務邏輯、AI整合
- Data Access: 資料庫操作、快取管理
- External APIs: AI服務、第三方整合
技術棧:
- 語言: C# / .NET 8
- 框架: ASP.NET Core Web API
- AI服務: Google Gemini 1.5 Flash
- 資料庫: SQLite (開發) / PostgreSQL (生產)
- 快取: Redis (生產) / In-Memory (開發)
- 監控: Application Insights
```
### **核心設計原則**
- **單一職責**: 每個服務類別職責明確
- **依賴注入**: 基於介面的鬆耦合設計
- **配置外部化**: 強型別配置管理
- **錯誤恢復**: 重試機制和降級策略
- **可觀測性**: 結構化日誌和健康檢查
---
## 📡 **API端點設計**
### **核心分析端點**
#### **POST /api/ai/analyze-sentence**
**功能**: 智能英文句子分析
**請求格式**:
```json
{
"inputText": "She just join the team, so let's cut her some slack until she get used to the workflow.",
"analysisMode": "full",
"options": {
"includeGrammarCheck": true,
"includeVocabularyAnalysis": true,
"includeTranslation": true,
"includeIdiomDetection": true,
"includeExamples": true
}
}
```
**回應格式**:
```json
{
"success": true,
"processingTime": 2.34,
"data": {
"analysisId": "uuid-string",
"originalText": "原始輸入文本",
"grammarCorrection": {
"hasErrors": true,
"correctedText": "修正後文本",
"corrections": [
{
"position": { "start": 9, "end": 13 },
"error": "join",
"correction": "joined",
"type": "時態錯誤",
"explanation": "第三人稱單數過去式應使用 'joined'",
"severity": "high"
}
]
},
"sentenceMeaning": "中文翻譯",
"vocabularyAnalysis": {
"word": {
"word": "詞彙",
"translation": "中文翻譯",
"definition": "英文定義",
"partOfSpeech": "詞性",
"pronunciation": "/IPA發音/",
"difficultyLevel": "A1-C2",
"frequency": "high/medium/low",
"synonyms": ["同義詞陣列"],
"example": "例句",
"exampleTranslation": "例句翻譯"
}
},
"idioms": [
{
"idiom": "cut someone some slack",
"translation": "對某人寬容一點",
"definition": "to be more lenient or forgiving",
"pronunciation": "/發音/",
"difficultyLevel": "B2",
"frequency": "medium",
"synonyms": ["be lenient", "give leeway"],
"example": "例句",
"exampleTranslation": "例句翻譯"
}
],
"metadata": {
"analysisModel": "gemini-1.5-flash",
"analysisVersion": "2.0",
"processingDate": "2025-01-25T10:30:00Z"
}
}
}
```
#### **GET /api/ai/health**
**功能**: 服務健康檢查
**回應格式**:
```json
{
"status": "Healthy",
"service": "AI Analysis Service",
"timestamp": "2025-01-25T10:30:00Z",
"version": "2.0",
"dependencies": {
"geminiApi": "healthy",
"database": "healthy",
"cache": "healthy"
}
}
```
---
## 🤖 **AI集成架構**
### **Prompt工程設計**
#### **核心Prompt模板**
```text
You are an English learning assistant. Analyze this sentence and return ONLY a valid JSON response.
**Input Sentence**: "{inputText}"
**Required JSON Structure:**
{
"sentenceTranslation": "Traditional Chinese translation of the entire sentence",
"hasGrammarErrors": true/false,
"grammarCorrections": [
{
"original": "incorrect text",
"corrected": "correct text",
"type": "error type (tense/subject-verb/preposition/word-order)",
"explanation": "brief explanation in Traditional Chinese"
}
],
"vocabularyAnalysis": {
"word1": {
"word": "the word",
"translation": "Traditional Chinese translation",
"definition": "English definition",
"partOfSpeech": "noun/verb/adjective/etc",
"pronunciation": "/phonetic/",
"difficultyLevel": "A1/A2/B1/B2/C1/C2",
"frequency": "high/medium/low",
"synonyms": ["synonym1", "synonym2"],
"example": "example sentence",
"exampleTranslation": "Traditional Chinese example translation"
}
},
"idioms": [
{
"idiom": "idiomatic expression",
"translation": "Traditional Chinese meaning",
"definition": "English explanation",
"pronunciation": "/phonetic notation/",
"difficultyLevel": "A1/A2/B1/B2/C1/C2",
"frequency": "high/medium/low",
"synonyms": ["synonym1", "synonym2"],
"example": "usage example",
"exampleTranslation": "Traditional Chinese example"
}
]
}
**Analysis Guidelines:**
1. **Grammar Check**: Detect tense errors, subject-verb agreement, preposition usage, word order
2. **Vocabulary Analysis**: Include ALL significant words (exclude articles: a, an, the)
3. **CEFR Levels**: Assign accurate A1-C2 levels for each word
4. **Idioms**: Identify any idiomatic expressions or phrasal verbs
5. **Translations**: Use Traditional Chinese (Taiwan standard)
**IMPORTANT**: Return ONLY the JSON object, no additional text or explanation.
```
### **AI服務配置**
#### **Gemini API配置**
```yaml
模型配置:
- 模型: gemini-1.5-flash
- 溫度: 0.7 (平衡創造性和準確性)
- 最大輸出: 2000 tokens
- 超時: 30秒
重試策略:
- 最大重試: 3次
- 退避策略: 指數退避 (1s, 2s, 4s)
- 重試條件: 網路錯誤、超時、5xx錯誤
- 熔斷條件: 連續失敗 > 5次
降級策略:
- 備用回應: 基礎翻譯和詞性分析
- 快取回退: 相似句子的歷史分析結果
- 服務狀態: 實時監控和告警
```
---
## 🔧 **數據模型設計**
### **請求模型**
#### **SentenceAnalysisRequest**
```csharp
public class SentenceAnalysisRequest
{
[Required]
[StringLength(300, MinimumLength = 1)]
public string InputText { get; set; } = string.Empty;
public string AnalysisMode { get; set; } = "full";
public AnalysisOptions? Options { get; set; }
}
public class AnalysisOptions
{
public bool IncludeGrammarCheck { get; set; } = true;
public bool IncludeVocabularyAnalysis { get; set; } = true;
public bool IncludeTranslation { get; set; } = true;
public bool IncludeIdiomDetection { get; set; } = true;
public bool IncludeExamples { get; set; } = true;
}
```
### **回應模型**
#### **核心資料模型**
```csharp
public class SentenceAnalysisResponse
{
public bool Success { get; set; } = true;
public double ProcessingTime { get; set; }
public SentenceAnalysisData? Data { get; set; }
public string? Message { get; set; }
}
public class SentenceAnalysisData
{
public string AnalysisId { get; set; } = Guid.NewGuid().ToString();
public string OriginalText { get; set; } = string.Empty;
public GrammarCorrectionDto? GrammarCorrection { get; set; }
public string SentenceMeaning { get; set; } = string.Empty;
public Dictionary<string, VocabularyAnalysisDto> VocabularyAnalysis { get; set; } = new();
public List<IdiomDto> Idioms { get; set; } = new();
public AnalysisMetadata Metadata { get; set; } = new();
}
```
#### **詳細模型定義**
```csharp
public class VocabularyAnalysisDto
{
public string Word { get; set; } = string.Empty;
public string Translation { get; set; } = string.Empty;
public string Definition { get; set; } = string.Empty;
public string PartOfSpeech { get; set; } = string.Empty;
public string Pronunciation { get; set; } = string.Empty;
public string DifficultyLevel { get; set; } = string.Empty;
public string Frequency { get; set; } = string.Empty;
public List<string> Synonyms { get; set; } = new();
public string? Example { get; set; }
public string? ExampleTranslation { get; set; }
}
public class IdiomDto
{
public string Idiom { get; set; } = string.Empty;
public string Translation { get; set; } = string.Empty;
public string Definition { get; set; } = string.Empty;
public string Pronunciation { get; set; } = string.Empty;
public string DifficultyLevel { get; set; } = string.Empty;
public string Frequency { get; set; } = string.Empty;
public List<string> Synonyms { get; set; } = new();
public string? Example { get; set; }
public string? ExampleTranslation { get; set; }
}
public class GrammarCorrectionDto
{
public bool HasErrors { get; set; }
public string CorrectedText { get; set; } = string.Empty;
public List<GrammarErrorDto> Corrections { get; set; } = new();
}
public class GrammarErrorDto
{
public ErrorPosition Position { get; set; } = new();
public string Error { get; set; } = string.Empty;
public string Correction { get; set; } = string.Empty;
public string Type { get; set; } = string.Empty;
public string Explanation { get; set; } = string.Empty;
public string Severity { get; set; } = "medium";
}
```
---
## 🔧 **服務層架構**
### **核心服務設計**
#### **IGeminiService介面**
```csharp
public interface IGeminiService
{
Task<SentenceAnalysisData> AnalyzeSentenceAsync(string inputText, AnalysisOptions options);
Task<bool> HealthCheckAsync();
Task<string> GetModelVersionAsync();
}
```
#### **服務實現重點**
```csharp
public class GeminiService : IGeminiService
{
private readonly HttpClient _httpClient;
private readonly IOptions<GeminiOptions> _options;
private readonly ILogger<GeminiService> _logger;
// ✅ 強型別配置注入
public GeminiService(HttpClient httpClient, IOptions<GeminiOptions> options, ILogger<GeminiService> logger)
{
_httpClient = httpClient;
_options = options;
_logger = logger;
ConfigureHttpClient();
}
// ✅ 結構化錯誤處理
public async Task<SentenceAnalysisData> AnalyzeSentenceAsync(string inputText, AnalysisOptions options)
{
try
{
var prompt = BuildPrompt(inputText, options);
var aiResponse = await CallGeminiAPIWithRetry(prompt);
return ParseResponse(inputText, aiResponse);
}
catch (HttpRequestException ex)
{
throw new AIServiceException("Gemini", "Network error", ex);
}
catch (JsonException ex)
{
throw new AIServiceException("Gemini", "Invalid response format", ex);
}
}
}
```
### **配置管理架構**
#### **強型別配置**
```csharp
public class GeminiOptions
{
public const string SectionName = "Gemini";
[Required]
public string ApiKey { get; set; } = string.Empty;
[Range(1, 120)]
public int TimeoutSeconds { get; set; } = 30;
[Range(1, 10)]
public int MaxRetries { get; set; } = 3;
public string Model { get; set; } = "gemini-1.5-flash";
public double Temperature { get; set; } = 0.7;
public int MaxOutputTokens { get; set; } = 2000;
}
// 配置驗證器
public class GeminiOptionsValidator : IValidateOptions<GeminiOptions>
{
public ValidateOptionsResult Validate(string name, GeminiOptions options)
{
var failures = new List<string>();
if (string.IsNullOrWhiteSpace(options.ApiKey))
failures.Add("Gemini API key is required");
if (!IsValidApiKey(options.ApiKey))
failures.Add("Invalid Gemini API key format");
return failures.Any()
? ValidateOptionsResult.Fail(failures)
: ValidateOptionsResult.Success;
}
}
```
---
## 🛡️ **錯誤處理與穩定性**
### **異常層次結構**
```csharp
public abstract class DramaLingException : Exception
{
public string ErrorCode { get; }
public Dictionary<string, object> Context { get; }
protected DramaLingException(string errorCode, string message) : base(message)
{
ErrorCode = errorCode;
Context = new Dictionary<string, object>();
}
}
public class AIServiceException : DramaLingException
{
public AIServiceException(string provider, string details)
: base("AI_SERVICE_ERROR", $"AI service '{provider}' failed: {details}")
{
Context["Provider"] = provider;
Context["Details"] = details;
}
}
public class ValidationException : DramaLingException
{
public ValidationException(string field, string message)
: base("VALIDATION_ERROR", $"Validation failed for {field}: {message}")
{
Context["Field"] = field;
}
}
```
### **錯誤回應標準**
```json
{
"success": false,
"error": {
"code": "AI_SERVICE_ERROR",
"message": "AI服務暫時不可用",
"details": {
"provider": "gemini",
"originalError": "Network timeout"
},
"suggestions": [
"請稍後重試",
"如果問題持續，請聯繫客服"
]
},
"timestamp": "2025-01-25T10:30:00Z",
"requestId": "uuid-string"
}
```
### **重試與熔斷機制**
```csharp
// 使用Polly實現重試策略
services.AddHttpClient<IGeminiService, GeminiService>()
.AddPolicyHandler(GetRetryPolicy())
.AddPolicyHandler(GetCircuitBreakerPolicy());
private static IAsyncPolicy<HttpResponseMessage> GetRetryPolicy()
{
return HttpPolicyExtensions
.HandleTransientHttpError()
.WaitAndRetryAsync(
retryCount: 3,
sleepDurationProvider: retryAttempt =>
TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)),
onRetry: (outcome, timespan, retryCount, context) =>
{
logger.LogWarning("Retry {RetryCount} after {Delay}ms",
retryCount, timespan.TotalMilliseconds);
});
}
```
---
## 📊 **性能優化設計**
### **快取策略**
```yaml
多層快取架構:
L1: 應用程序記憶體快取 (5分鐘)
L2: Redis分散式快取 (1小時)
L3: 資料庫持久快取 (24小時)
快取鍵設計:
- 格式: "analysis:{hash(inputText)}"
- 過期: 基於內容複雜度動態調整
- 清理: 背景服務定期清理過期快取
快取命中率目標: > 70%
```
### **資料庫優化**
```csharp
// 查詢優化範例
public async Task<AnalysisCache> GetCachedAnalysisAsync(string inputText)
{
var textHash = ComputeHash(inputText);
return await _context.AnalysisCache
.AsNoTracking() // 只讀查詢優化
.Where(c => c.InputTextHash == textHash && c.ExpiresAt > DateTime.UtcNow)
.Select(c => new AnalysisCache // 投影查詢，只選需要的欄位
{
Id = c.Id,
CachedData = c.CachedData,
CreatedAt = c.CreatedAt
})
.FirstOrDefaultAsync();
}
```
---
## 🔒 **安全架構設計**
### **API安全**
```yaml
認證機制:
- JWT Bearer Token認證
- Token過期時間: 24小時
- 刷新機制: Refresh Token
授權控制:
- 角色基礎存取控制 (RBAC)
- 資源級別權限
- API速率限制
輸入驗證:
- 參數類型檢查
- 字符長度限制
- XSS防護過濾
- SQL注入防護
```
### **資料安全**
```yaml
傳輸安全:
- TLS 1.3強制加密
- HSTS標頭
- 安全標頭 (CSP, X-Frame-Options)
存儲安全:
- 敏感資料加密
- API金鑰安全管理
- 個人資料匿名化
- 定期安全掃描
```
---
## 🧪 **測試策略**
### **測試金字塔**
```yaml
單元測試 (70%):
- 服務邏輯測試
- 配置驗證測試
- 錯誤處理測試
- Mock外部依賴
整合測試 (20%):
- API端點測試
- 資料庫整合測試
- 快取系統測試
- 健康檢查測試
E2E測試 (10%):
- 完整分析流程測試
- 真實AI API測試
- 性能基準測試
- 安全滲透測試
```
### **測試案例設計**
```csharp
[TestFixture]
public class AIAnalysisServiceTests
{
[Test]
public async Task AnalyzeAsync_WithValidInput_ReturnsAnalysisResult()
{
// Arrange
var request = new AnalysisRequest { InputText = "She just joined the team." };
// Act
var result = await _service.AnalyzeAsync(request);
// Assert
Assert.That(result.VocabularyAnalysis.Count, Is.GreaterThan(0));
Assert.That(result.SentenceMeaning, Is.Not.Empty);
}
[Test]
public async Task AnalyzeAsync_WhenAIServiceFails_ThrowsAIServiceException()
{
// 測試AI服務故障時的錯誤處理
}
}
```
---
## 📈 **監控與可觀測性**
### **日誌標準**
```csharp
// 結構化日誌擴展
public static class LoggerExtensions
{
public static void LogAIRequest(this ILogger logger, string requestId,
string inputText, string provider, double processingTime)
{
logger.LogInformation("AI Request: {RequestId} Provider: {Provider} " +
"Length: {Length} Time: {Time}ms",
requestId, provider, inputText.Length, processingTime);
}
}
```
### **健康檢查**
```csharp
public class AIServiceHealthCheck : IHealthCheck
{
public async Task<HealthCheckResult> CheckHealthAsync(HealthCheckContext context,
CancellationToken cancellationToken = default)
{
var checks = new Dictionary<string, bool>
{
["gemini_api"] = await CheckGeminiHealthAsync(),
["database"] = await CheckDatabaseHealthAsync(),
["cache"] = await CheckCacheHealthAsync()
};
var failedChecks = checks.Where(c => !c.Value).Select(c => c.Key).ToList();
return failedChecks.Any()
? HealthCheckResult.Unhealthy($"Failed: {string.Join(", ", failedChecks)}")
: HealthCheckResult.Healthy("All systems operational");
}
}
```
### **性能指標**
```yaml
關鍵指標:
- API回應時間分佈 (P50, P95, P99)
- AI API調用成功率
- 快取命中率
- 記憶體和CPU使用率
- 錯誤率和異常分佈
告警閾值:
- 回應時間P95 > 5秒
- 錯誤率 > 5%
- AI API失敗率 > 10%
- 記憶體使用 > 80%
```
---
## 🚀 **部署與配置**
### **環境配置**
```yaml
Development:
- Database: SQLite
- Cache: In-Memory
- AI Provider: Gemini (測試Key)
- Logging: Debug Level
Production:
- Database: PostgreSQL (HA)
- Cache: Redis Cluster
- AI Provider: Gemini (生產Key)
- Logging: Information Level
- Monitoring: Application Insights
```
### **Docker配置**
```dockerfile
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
WORKDIR /app
EXPOSE 5008
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY ["DramaLing.Api.csproj", "."]
RUN dotnet restore
COPY . .
RUN dotnet publish -c Release -o /app/publish
FROM base AS final
WORKDIR /app
COPY --from=build /app/publish .
HEALTHCHECK --interval=30s --timeout=3s \
CMD curl -f http://localhost:5008/health || exit 1
ENTRYPOINT ["dotnet", "DramaLing.Api.dll"]
```
---
## 📋 **開發指導**
### **程式碼規範**
```yaml
命名規範:
- 類別: PascalCase (UserService)
- 方法: PascalCase (AnalyzeAsync)
- 參數: camelCase (inputText)
- 常數: UPPER_CASE (MAX_LENGTH)
註釋規範:
- 公開API: 完整XML註釋
- 複雜邏輯: 行內註釋解釋
- 業務邏輯: 意圖說明註釋
- TODO: 使用標準格式
錯誤處理:
- 自訂異常類型
- 結構化錯誤回應
- 日誌記錄完整
- 用戶友善訊息
```
### **API設計原則**
```yaml
RESTful設計:
- 使用標準HTTP動詞
- 資源導向URL設計
- 狀態碼語義明確
- 一致的回應格式
版本管理:
- URL版本控制 (/api/v1/)
- 向下相容保證
- 淘汰策略明確
- 版本變更文檔
安全實踐:
- 最小權限原則
- 輸入驗證完整
- 輸出編碼安全
- 審計日誌記錄
```
---
## 🔄 **變更管理**
### **API版本演進**
- **v1.0**: 基礎分析功能 (2025-01-20)
- **v1.1**: 移除userLevel，簡化API (2025-01-25)
- **v2.0**: 重構技術規格，標準化設計 (2025-01-25)
### **技術債務管理**
```yaml
已解決:
- 硬編碼配置移除
- 強型別配置實施
- API規格標準化
待解決:
- 重試機制實施
- 健康檢查完善
- 監控指標實施
- 性能優化
```
---
**文件版本**: v2.0
**技術負責人**: DramaLing後端技術團隊
**最後更新**: 2025-01-25
**下次審查**: 2025-02-25
**關聯文件**:
- 《AI句子分析功能產品需求規格》- 業務需求和用戶故事
- 《系統整合與部署規格》- 整合和部署細節
- 《AI驅動產品後端技術架構指南》- 架構設計指導原則

569
note/AI句子分析規格/AI句子分析功能產品需求規格.md Normal file
View File

@ -0,0 +1,569 @@
# AI句子分析功能產品需求規格
## 📋 **文件資訊**
- **文件名稱**: AI句子分析功能產品需求規格
- **版本**: v2.0
- **建立日期**: 2025-01-25
- **最後更新**: 2025-01-25
- **負責團隊**: DramaLing產品團隊
- **適用範圍**: 全平台 (Web、API、未來Mobile)
---
## 🎯 **產品概述**
### **產品定位**
DramaLing AI句子分析功能是個人化英語學習平台的核心功能，專注於提供智能句子分析、個人化詞彙標記和互動式學習體驗。
### **商業目標**
- 🎯 **提升學習效率**: 通過AI分析幫助用戶快速理解句子結構
- 💡 **個人化學習**: 基於用戶程度提供適合的學習內容
- 📈 **用戶留存**: 通過互動式體驗增加平台黏性
- 🌍 **市場差異化**: 提供業界領先的AI驅動語言學習體驗
### **核心價值主張**
- 🤖 **AI驅動分析** - 即時語法檢查和詞彙解析
- 🎯 **個人化學習** - 基於CEFR等級的智能詞彙分類
- 📊 **視覺化回饋** - 直觀的學習進度和統計展示
- 💡 **互動式學習** - 點擊探索式的深度學習體驗
---
## 🎭 **用戶故事與使用場景**
### **US1. 核心學習流程**
#### **US1.1 智能句子分析**
```gherkin
功能: 智能英文句子分析
背景: 用戶想要學習和理解英文句子
場景: 用戶分析英文句子
給定 用戶是英語學習者
當 用戶輸入英文句子 "She just join the team, so let's cut her some slack until she get used to the workflow."
並且 點擊「分析句子」按鈕
那麼 系統應該顯示語法修正建議
並且 系統應該提供詞彙難度標記
並且 系統應該識別慣用語 "cut someone some slack"
並且 系統應該提供完整的中文翻譯
驗收標準:
- 能輸入最多300字的英文句子
- 分析回應時間 < 5秒
- 語法檢查準確率 > 85%
- 詞彙CEFR分級準確率 > 90%
- 慣用語識別覆蓋率 > 80%
```
#### **US1.2 個人化詞彙學習**
```gherkin
功能: 基於CEFR等級的個人化詞彙標記
背景: 不同程度的學習者需要不同的學習重點
場景: A2程度學習者查看句子分析
給定 用戶的CEFR等級是A2
當 系統分析句子中的詞彙
那麼 A1詞彙應該顯示為「太簡單啦」(灰色虛線)
並且 A2詞彙應該顯示為「重點學習」(綠色邊框)
並且 B1+詞彙應該顯示為「有點挑戰」(橙色邊框)
並且 慣用語應該獨立顯示為「慣用語」(藍色邊框)
驗收標準:
- 詞彙分類基於用戶當前CEFR等級動態計算
- 用戶可以調整CEFR等級設定
- 等級變更時詞彙標記即時更新
- 統計卡片數字與實際標記一致
```
#### **US1.3 語法修正學習**
```gherkin
功能: 智能語法錯誤檢測和修正建議
背景: 學習者需要了解和改正語法錯誤
場景: 用戶獲得語法修正建議
給定 用戶輸入有語法錯誤的句子
當 系統完成分析
那麼 系統應該顯示語法修正面板
並且 提供原句與修正句的對比
並且 解釋每個錯誤的類型和原因
並且 用戶可以選擇採用修正或保持原樣
驗收標準:
- 檢測時態錯誤、主謂一致、介詞使用、詞序問題
- 提供繁體中文的錯誤解釋
- 修正建議自然且符合語言習慣
- 用戶選擇後影響後續的詞彙學習內容
```
### **US2. 深度學習互動**
#### **US2.1 詞彙探索學習**
```gherkin
功能: 互動式詞彙詳情查看
背景: 學習者想要深入了解特定詞彙
場景: 用戶點擊詞彙查看詳情
給定 句子已完成分析並顯示詞彙標記
當 用戶點擊任何標記的詞彙
那麼 系統應該顯示詞彙詳情彈窗
並且 包含中文翻譯、英文定義、發音
並且 提供同義詞和實用例句
並且 提供「保存到詞卡」功能
驗收標準:
- 所有標記詞彙都可點擊
- 彈窗定位智能，不超出螢幕邊界
- 彈窗開啟時間 < 200ms
- 詞彙資料完整且準確
```
#### **US2.2 慣用語學習**
```gherkin
功能: 慣用語識別和學習
背景: 學習者需要掌握地道的英語表達
場景: 用戶學習句子中的慣用語
給定 句子包含慣用語表達
當 系統完成分析
那麼 慣用語應該在專門區域顯示
並且 不在句子中重複標記
並且 點擊慣用語可查看詳細解釋
並且 包含文化背景和使用場景
驗收標準:
- 慣用語、片語動詞、固定搭配的準確識別
- 提供文化背景和使用建議
- 與詞彙詳情彈窗一致的視覺設計
- 支援保存到個人詞彙庫
```
---
## 📋 **功能需求規格 (Functional Requirements)**
### **FR1. 智能分析引擎**
#### **FR1.1 文本輸入處理**
**優先級**: P0 (必須)
**需求描述**:
- 支援多語言文本輸入（主要英文）
- 文本長度限制和即時驗證
- 特殊字符和格式處理
**詳細規格**:
```yaml
輸入限制:
- 最大長度: 300字符
- 支援字符: 英文字母、數字、標點符號
- 警告機制: 280字符黃色警告，300字符禁止輸入
- 即時驗證: 字符計數顯示，超限阻止提交
錯誤處理:
- 空字串: 禁用分析按鈕
- 無效字符: 自動過濾或提示
- 超長文本: 截斷並警告用戶
```
#### **FR1.2 AI分析核心**
**優先級**: P0 (必須)
**需求描述**:
- 整合AI語言模型進行句子分析
- 支援多維度分析結果
- 確保分析準確性和一致性
**詳細規格**:
```yaml
分析範圍:
- 語法檢查: 時態、主謂一致、介詞、詞序
- 詞彙分析: CEFR等級、詞性、發音、翻譯
- 句子翻譯: 自然流暢的繁體中文
- 慣用語識別: 慣用語、片語動詞、固定搭配
品質要求:
- 語法檢查準確率: > 85%
- CEFR分級準確率: > 90%
- 翻譯自然度評分: > 4.0/5.0
- 慣用語識別率: > 80%
性能要求:
- 分析響應時間: < 5秒
- 同時支援用戶數: > 100
- 服務可用性: > 99.5%
```
### **FR2. 個人化學習系統**
#### **FR2.1 CEFR等級個人化**
**優先級**: P0 (必須)
**需求描述**:
- 基於用戶CEFR等級提供個人化詞彙分類
- 支援等級調整和即時更新
- 提供學習進度指引
**詳細規格**:
```yaml
分類邏輯:
- 簡單詞彙: 用戶等級 > 詞彙等級
- 適中詞彙: 用戶等級 = 詞彙等級
- 困難詞彙: 用戶等級 < 詞彙等級
- 慣用語: 獨立分類，不參與等級比較
支援等級:
- A1: 初學者 (約1000詞彙)
- A2: 基礎 (約2000詞彙)
- B1: 中級 (約3000詞彙)
- B2: 中高級 (約4000詞彙)
- C1: 高級 (約8000詞彙)
- C2: 精通 (約15000詞彙)
更新機制:
- 等級變更即時重新分類
- 本地存儲用戶設定
- 跨設備同步 (未來功能)
```
#### **FR2.2 學習進度可視化**
**優先級**: P0 (必須)
**需求描述**:
- 提供直觀的詞彙難度分布統計
- 支援學習重點識別
- 幫助用戶評估學習挑戰
**詳細規格**:
```yaml
統計卡片:
- 簡單詞彙卡片: 灰色虛線，「太簡單啦」
- 適中詞彙卡片: 綠色邊框，「重點學習」
- 困難詞彙卡片: 橙色邊框，「有點挑戰」
- 慣用語卡片: 藍色邊框，「慣用語」
計算邏輯:
- 前端即時計算統計數據
- 基於當前用戶等級動態分類
- 統計數字與實際標記保持一致
- 用戶等級變更時即時更新
```
### **FR3. 互動學習體驗**
#### **FR3.1 詞彙深度探索**
**優先級**: P0 (必須)
**需求描述**:
- 提供豐富的詞彙學習資訊
- 支援多感官學習體驗
- 整合個人詞彙管理
**詳細規格**:
```yaml
詞彙詳情內容:
- 基礎資訊: 詞彙、翻譯、定義、詞性
- 語音資訊: IPA發音標記、音頻播放 (未來)
- 學習輔助: 同義詞、例句、例句翻譯
- 個人化: CEFR等級、使用頻率、學習狀態
互動功能:
- 點擊詞彙開啟詳情彈窗
- 一鍵保存到個人詞卡庫
- 發音練習 (未來功能)
- 相關詞彙推薦 (未來功能)
```
#### **FR3.2 慣用語文化學習**
**優先級**: P0 (必須)
**需求描述**:
- 深度學習英語慣用語和文化表達
- 提供使用場景和文化背景
- 支援實際應用練習
**詳細規格**:
```yaml
慣用語資訊:
- 基礎定義: 慣用語、中英文解釋、發音
- 文化背景: 起源、使用場景、語域標記
- 學習輔助: 同義表達、實用例句
- 難度標記: CEFR等級、使用頻率
展示方式:
- 獨立區域展示，不與一般詞彙混淆
- 統一的視覺設計和互動體驗
- 支援多個慣用語並排顯示
- 與詞彙詳情一致的彈窗設計
```
---
## 🔧 **非功能性需求 (Non-Functional Requirements)**
### **NFR1. 性能需求**
#### **NFR1.1 響應時間要求**
```yaml
核心功能:
- 文本輸入響應: < 100ms
- AI分析處理: < 5秒
- 詞彙標記渲染: < 200ms
- 詞彙詳情彈窗: < 100ms
- 統計卡片更新: < 50ms
系統負載:
- 同時在線用戶: > 100
- 每日分析請求: > 10,000
- 峰值處理能力: > 200 req/min
- 系統可用性: > 99.5%
```
#### **NFR1.2 可擴展性要求**
```yaml
用戶擴展:
- 支援用戶數: 10,000+ (第一年)
- 數據存儲: 100GB+ (分析記錄)
- 並發處理: 500+ 同時請求
功能擴展:
- 多語言支援: 法語、德語 (未來)
- 多模態分析: 語音、圖片 (未來)
- 實時協作: 團隊學習 (未來)
```
### **NFR2. 用戶體驗需求**
#### **NFR2.1 易用性標準**
```yaml
學習曲線:
- 新用戶上手時間: < 5分鐘
- 完整分析流程: < 2分鐘
- 功能發現時間: < 30秒
操作效率:
- 點擊響應時間: < 100ms
- 頁面載入時間: < 2秒
- 功能切換時間: < 500ms
- 錯誤恢復時間: < 3秒
滿意度指標:
- 用戶體驗評分: > 4.5/5
- 功能完成率: > 95%
- 錯誤率: < 5%
```
#### **NFR2.2 無障礙需求**
```yaml
WCAG 2.1 AA 合規:
- 顏色對比度: > 4.5:1
- 鍵盤導航: 完整支援
- 螢幕閱讀器: 適當的ARIA標籤
- 字體縮放: 支援200%放大
多設備支援:
- 桌面瀏覽器: Chrome 90+, Safari 14+, Firefox 88+
- 移動設備: iOS 14+, Android 10+
- 響應式設計: 320px - 2560px
```
### **NFR3. 安全與隱私需求**
#### **NFR3.1 數據安全**
```yaml
輸入安全:
- XSS防護: 輸入內容過濾和轉義
- 內容驗證: 惡意內容檢測
- 長度限制: 嚴格執行字符限制
數據隱私:
- 個人數據: 符合GDPR要求
- 學習記錄: 用戶控制和導出
- 數據保留: 明確的保留政策
- 匿名化: 分析統計數據去識別
```
#### **NFR3.2 API安全**
```yaml
認證授權:
- JWT Token認證
- 角色權限控制
- 速率限制保護
數據傳輸:
- HTTPS強制加密
- API金鑰安全管理
- 請求簽名驗證
```
---
## 🎨 **用戶介面需求**
### **UI1. 視覺設計標準**
#### **UI1.1 詞彙標記設計**
```yaml
視覺層次:
- 簡單詞彙: bg-gray-50, border-dashed, border-gray-300, text-gray-600, opacity-80
- 適中詞彙: bg-green-50, border-green-200, text-green-700, font-medium
- 困難詞彙: bg-orange-50, border-orange-200, text-orange-700, font-medium
- 慣用語: bg-blue-50, border-blue-200, text-blue-700
互動效果:
- hover: 陰影提升，輕微上移
- focus: 鍵盤導航支援
- active: 點擊回饋動畫
```
#### **UI1.2 統計卡片設計**
```yaml
卡片規格:
- 響應式佈局: 桌面1行4張，移動設備2行2張
- 數字突出: 大字體顯示統計數量
- 顏色一致: 與對應詞彙標記顏色匹配
- 即時更新: 分析完成後動畫顯示
```
### **UI2. 互動體驗設計**
#### **UI2.1 彈窗系統設計**
```yaml
詞彙詳情彈窗:
- 標題區: 漸層藍色背景，詞彙名稱，CEFR標籤
- 內容區: 翻譯(綠)、定義(灰)、例句(藍)、同義詞(紫)
- 操作區: 保存按鈕，關閉按鈕
- 定位: 智能計算，避免螢幕邊界
語法修正面板:
- 警告樣式: 黃色背景，警告圖標
- 對比顯示: 原句 vs 修正句
- 操作按鈕: 採用修正(綠色)，保持原樣(灰色)
```
---
## 🧪 **驗收標準與測試需求**
### **AC1. 功能驗收標準**
#### **AC1.1 核心功能檢查表**
- [ ] 文本輸入和字符限制正常運作
- [ ] AI分析在5秒內完成並返回結果
- [ ] 語法修正準確檢測並提供合理建議
- [ ] 詞彙CEFR分級準確率達到90%以上
- [ ] 慣用語識別覆蓋率達到80%以上
- [ ] 個人化詞彙標記根據用戶等級正確分類
- [ ] 統計卡片數字與實際詞彙標記一致
- [ ] 詞彙和慣用語詳情彈窗正常運作
- [ ] 保存到詞卡功能完整可用
#### **AC1.2 用戶體驗檢查表**
- [ ] 新用戶能在5分鐘內完成首次完整分析
- [ ] 所有互動響應時間符合性能要求
- [ ] 響應式設計在所有目標設備正常顯示
- [ ] 錯誤處理友善且提供有用指導
- [ ] 視覺設計一致且符合品牌標準
### **AC2. 技術驗收標準**
#### **AC2.1 API品質檢查**
- [ ] API回應格式穩定一致
- [ ] 錯誤處理涵蓋所有邊界情況
- [ ] 性能指標達到要求基準
- [ ] 安全檢查通過滲透測試
#### **AC2.2 資料品質檢查**
- [ ] AI分析結果準確性達標
- [ ] 繁體中文翻譯自然流暢
- [ ] CEFR等級分配符合標準
- [ ] 慣用語解釋準確且完整
---
## 🚀 **產品路線圖**
### **Phase 1: 核心功能 (已完成)**
- ✅ 基礎AI句子分析
- ✅ 詞彙標記和分類
- ✅ 語法修正功能
- ✅ 慣用語識別
### **Phase 2: 體驗優化 (當前階段)**
- 🔄 性能優化和穩定性提升
- 🔄 用戶介面細節優化
- ⏳ 錯誤處理完善
- ⏳ 無障礙功能實施
### **Phase 3: 功能擴展 (規劃中)**
- 📅 批次分析功能
- 📅 學習歷史記錄
- 📅 個人詞彙庫進階管理
- 📅 語音集成 (TTS/STT)
### **Phase 4: 平台擴展 (未來)**
- 🔮 多語言學習支援
- 🔮 移動應用開發
- 🔮 團隊協作功能
- 🔮 AI模型自定義
---
## 📊 **成功指標 (KPIs)**
### **產品指標**
```yaml
用戶參與度:
- 日活躍用戶數 (DAU): > 1,000
- 平均每用戶分析次數: > 5次/日
- 用戶留存率 (7天): > 70%
- 功能使用率: > 80%
學習效果:
- 用戶滿意度評分: > 4.5/5
- 學習目標完成率: > 85%
- 詞彙掌握改善度: > 30%
- 重複使用率: > 60%
```
### **技術指標**
```yaml
性能指標:
- API回應時間P95: < 5秒
- 頁面載入時間P95: < 2秒
- 系統可用性: > 99.5%
- 錯誤率: < 1%
品質指標:
- AI分析準確率: > 90%
- 代碼覆蓋率: > 80%
- 安全掃描通過率: 100%
- 用戶回報問題解決率: > 95%
```
---
## 🔄 **變更管理**
### **需求變更流程**
1. **提出變更**: 產品經理、開發團隊、用戶回饋
2. **影響評估**: 技術可行性、工期影響、資源需求
3. **優先級評定**: 商業價值、緊急程度、實施成本
4. **審核批准**: 產品委員會審核決定
5. **實施追蹤**: 開發進度、測試驗證、上線監控
### **文件版本管理**
- **v1.0**: 初始需求規格 (2025-09-21)
- **v2.0**: 整合統一產品需求規格 (2025-01-25)
---
**文件版本**: v2.0
**產品負責人**: DramaLing產品團隊
**最後更新**: 2025-01-25
**下次審查**: 2025-02-25
**關聯文件**:
- 《AI分析API技術實現規格》- 技術實現細節
- 《系統整合與部署規格》- 系統整合和部署
- 《AI驅動產品後端技術架構指南》- 架構設計指導

711
note/AI句子分析規格/DramaLing AI句子分析功能前後端串接實施計劃.md Normal file
View File

@ -0,0 +1,711 @@
# DramaLing AI句子分析功能前後端串接實施計劃
## 📋 **文件資訊**
- **文件名稱**: DramaLing AI句子分析功能前後端串接實施計劃
- **版本**: v1.0
- **建立日期**: 2025-01-25
- **最後更新**: 2025-01-25
- **負責團隊**: DramaLing技術團隊
- **專案階段**: 後端完成，準備前後端整合
---
## 🎯 **計劃概述**
### **目標**
完成DramaLing AI句子分析功能的前後端串接，實現完整的智能英語學習體驗。
### **現狀分析**
- ✅ **後端API**: 已完成開發並運行在 localhost:5008
- ✅ **前端架構**: Next.js 15 + TypeScript + Tailwind CSS
- ✅ **AI整合**: Google Gemini 1.5 Flash API 已整合
- ⏳ **串接狀態**: 需要調整前端API調用邏輯以對接新後端
### **串接範圍**
1. AI句子分析核心功能
2. 詞彙分析與CEFR分級
3. 語法修正功能
4. 慣用語檢測
5. 個人化學習統計
6. 錯誤處理與用戶體驗
---
## 📊 **當前架構對比分析**
### **後端API架構 (.NET 8)**
```yaml
核心端點:
- POST /api/ai/analyze-sentence # 主要分析API (backend/DramaLing.Api/Controllers/AIController.cs)
- GET /api/ai/health # 健康檢查 (backend/DramaLing.Api/Controllers/AIController.cs)
- POST /api/flashcards # 詞卡管理 (backend/DramaLing.Api/Controllers/FlashcardsController.cs)
- POST /api/auth/login # 用戶認證 (backend/DramaLing.Api/Controllers/AuthController.cs)
技術棧:
- .NET 8 Web API
- Entity Framework Core
- SQLite (開發) / PostgreSQL (生產)
- Google Gemini 1.5 Flash AI
- JWT認證機制
```
### **前端架構 (Next.js 15)**
```yaml
核心功能:
- 句子輸入與分析 (/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/app/generate/page.tsx)
- 詞彙標記與統計 (/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/components/ClickableTextV2.tsx)
- 語法修正面板 (/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/components/GrammarCorrectionPanel.tsx)
- 詞彙詳情彈窗 (VocabPopup - 位於ClickableTextV2.tsx內)
- 學習模式整合 (/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/app/learn/page.tsx)
技術棧:
- Next.js 15.5.3 + React 19
- TypeScript + Tailwind CSS
- localStorage (用戶設定)
- Fetch API (HTTP請求)
```
---
## 🔄 **API整合對比**
### **現有前端API調用**
```typescript
// 檔案位置: /Users/jettcheng1018/code/dramaling-vocab-learning/frontend/app/generate/page.tsx
// 函數: handleAnalyzeSentence (約在第185-220行)
const response = await fetch('http://localhost:5008/api/ai/analyze-sentence', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
inputText: textInput,
userLevel: userLevel, // ⚠️ 後端不需要此欄位
analysisMode: 'full',
options: {
includeGrammarCheck: true,
includeVocabularyAnalysis: true,
includeTranslation: true,
includeIdiomDetection: true,
includeExamples: true
}
})
});
```
### **後端API規格**
```json
// 檔案參考: backend/DramaLing.Api/Controllers/AIController.cs
// 端點: POST /api/ai/analyze-sentence
// 請求格式
{
"inputText": "英文句子",
"analysisMode": "full",
"options": {
"includeGrammarCheck": true,
"includeVocabularyAnalysis": true,
"includeTranslation": true,
"includeIdiomDetection": true,
"includeExamples": true
}
}
// 回應格式
{
"success": true,
"processingTime": 2.34,
"data": {
"analysisId": "uuid-string",
"originalText": "原始句子",
"sentenceMeaning": "中文翻譯",
"grammarCorrection": {
"hasErrors": true,
"correctedText": "修正後文本",
"corrections": [...]
},
"vocabularyAnalysis": {
"word1": {
"word": "詞彙",
"translation": "翻譯",
"definition": "定義",
"partOfSpeech": "詞性",
"pronunciation": "發音",
"difficultyLevel": "A1-C2",
"frequency": "high/medium/low",
"synonyms": ["同義詞"],
"example": "例句",
"exampleTranslation": "例句翻譯"
}
},
"idioms": [...],
"metadata": {...}
}
}
```
---
## 🛠️ **實施計劃**
### **階段一：API適配與調整 (1-2天)**
#### **1.1 前端API調用更新**
**目標**: 移除後端不需要的userLevel參數，確保請求格式正確
**檔案**: `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/app/generate/page.tsx`
**函數**: `handleAnalyzeSentence` (約在第185-220行)
```typescript
// 修改前
body: JSON.stringify({
inputText: textInput,
userLevel: userLevel, // 移除此行
analysisMode: 'full',
options: { ... }
})
// 修改後
body: JSON.stringify({
inputText: textInput,
analysisMode: 'full',
options: {
includeGrammarCheck: true,
includeVocabularyAnalysis: true,
includeTranslation: true,
includeIdiomDetection: true,
includeExamples: true
}
})
```
#### **1.2 回應數據結構適配**
**目標**: 更新前端以處理新的API回應格式
**檔案**: `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/app/generate/page.tsx`
**函數**: `handleAnalysisResult` (需新增)
```typescript
// 修改回應處理邏輯
const handleAnalysisResult = (result) => {
// 後端回應結構: result.data.vocabularyAnalysis
// 前端期望結構: result.vocabularyAnalysis
const analysisData = {
originalText: result.data.originalText,
sentenceMeaning: result.data.sentenceMeaning,
grammarCorrection: result.data.grammarCorrection,
vocabularyAnalysis: result.data.vocabularyAnalysis,
idioms: result.data.idioms,
processingTime: result.processingTime
};
setSentenceAnalysis(analysisData);
};
```
### **階段二：詞彙分析整合 (2-3天)**
#### **2.1 詞彙數據格式統一**
**目標**: 確保前端詞彙分析邏輯與後端回應格式匹配
**檔案**: `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/components/ClickableTextV2.tsx`
**函數**: `findWordAnalysis`, `getWordProperty` (約在第50-80行)
```typescript
// 更新詞彙分析資料存取邏輯
const findWordAnalysis = useCallback((word: string) => {
if (!sentenceAnalysis?.vocabularyAnalysis) return null;
// 後端格式: vocabularyAnalysis[word]
return sentenceAnalysis.vocabularyAnalysis[word] || null;
}, [sentenceAnalysis]);
// 更新CEFR難度取得邏輯
const getWordProperty = useCallback((word: string, property: string) => {
const analysis = findWordAnalysis(word);
return analysis?.[property] || '';
}, [findWordAnalysis]);
```
#### **2.2 統計計算邏輯優化**
**目標**: 基於新的API回應格式重新計算詞彙統計
**檔案**: `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/app/generate/page.tsx`
**函數**: `vocabularyStats` useMemo hook (約在第250-280行)
```typescript
const vocabularyStats = useMemo(() => {
if (!sentenceAnalysis?.vocabularyAnalysis) {
return { simpleCount: 0, moderateCount: 0, difficultCount: 0, idiomCount: 0 };
}
const userIndex = CEFR_LEVELS.indexOf(userLevel);
let simple = 0, moderate = 0, difficult = 0;
// 遍歷vocabularyAnalysis物件
Object.values(sentenceAnalysis.vocabularyAnalysis).forEach(word => {
const wordIndex = CEFR_LEVELS.indexOf(word.difficultyLevel);
if (userIndex > wordIndex) simple++;
else if (userIndex === wordIndex) moderate++;
else difficult++;
});
return {
simpleCount: simple,
moderateCount: moderate,
difficultCount: difficult,
idiomCount: sentenceAnalysis.idioms?.length || 0
};
}, [sentenceAnalysis, userLevel]);
```
### **階段三：語法修正整合 (1-2天)**
#### **3.1 語法修正數據適配**
**目標**: 更新語法修正面板以處理新的錯誤格式
**檔案**: `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/components/GrammarCorrectionPanel.tsx`
**介面定義**: `GrammarError` interface (需新增)
**函數**: `renderCorrections` (需修改)
```typescript
// 更新錯誤數據結構處理
interface GrammarError {
position: { start: number; end: number };
error: string;
correction: string;
type: string;
explanation: string;
severity: 'high' | 'medium' | 'low';
}
// 更新組件以使用新的錯誤格式
const renderCorrections = () => {
return grammarCorrection.corrections.map((correction, index) => (
<div key={index} className="correction-item">
<span className="error-text">{correction.error}</span>
<span className="arrow">→</span>
<span className="corrected-text">{correction.correction}</span>
<div className="explanation">{correction.explanation}</div>
</div>
));
};
```
### **階段四：慣用語功能整合 (1-2天)**
#### **4.1 慣用語顯示邏輯**
**目標**: 整合後端慣用語檢測結果
**檔案**: `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/app/generate/page.tsx`
**函數**: `renderIdioms`, `handleIdiomClick` (需新增)
```typescript
// 慣用語渲染邏輯
const renderIdioms = () => {
if (!sentenceAnalysis?.idioms || sentenceAnalysis.idioms.length === 0) {
return null;
}
return (
<div className="idioms-section">
<h3>慣用語解析</h3>
{sentenceAnalysis.idioms.map((idiom, index) => (
<div key={index} className="idiom-chip" onClick={() => handleIdiomClick(idiom)}>
{idiom.idiom}
</div>
))}
</div>
);
};
// 慣用語點擊處理
const handleIdiomClick = (idiom) => {
setSelectedVocab({
word: idiom.idiom,
translation: idiom.translation,
definition: idiom.definition,
pronunciation: idiom.pronunciation,
partOfSpeech: 'idiom',
difficultyLevel: idiom.difficultyLevel,
frequency: idiom.frequency,
synonyms: idiom.synonyms,
example: idiom.example,
exampleTranslation: idiom.exampleTranslation
});
setIsPopupVisible(true);
};
```
### **階段五：錯誤處理與用戶體驗 (1-2天)**
#### **5.1 統一錯誤處理**
**目標**: 實現友善的錯誤提示和降級體驗
**檔案**: `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/app/generate/page.tsx`
**函數**: `handleAnalysisError`, `setFallbackAnalysisView` (需新增或修改)
```typescript
const handleAnalysisError = (error) => {
console.error('Analysis error:', error);
setIsAnalyzing(false);
// 根據錯誤類型提供不同的用戶提示
if (error.message.includes('timeout')) {
setErrorMessage('分析服務繁忙，請稍後再試');
} else if (error.message.includes('network')) {
setErrorMessage('網路連接問題，請檢查網路狀態');
} else if (error.message.includes('500')) {
setErrorMessage('服務器暫時不可用，請稍後重試');
} else {
setErrorMessage('分析過程中發生錯誤，請稍後再試');
}
// 提供降級體驗：基礎翻譯
setFallbackAnalysisView(textInput);
};
// 降級體驗實現
const setFallbackAnalysisView = (text) => {
setSentenceAnalysis({
originalText: text,
sentenceMeaning: '暫時無法提供完整分析，請稍後重試',
grammarCorrection: { hasErrors: false, corrections: [] },
vocabularyAnalysis: {},
idioms: []
});
};
```
#### **5.2 載入狀態優化**
**目標**: 提供清晰的載入反饋
**檔案**: `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/app/generate/page.tsx`
**狀態管理**: 新增 `analysisState` state
**函數**: 修改 `handleAnalyzeSentence`
```typescript
// 分析狀態管理
const [analysisState, setAnalysisState] = useState({
isAnalyzing: false,
progress: 0,
stage: ''
});
const handleAnalyzeSentence = async () => {
setAnalysisState({ isAnalyzing: true, progress: 20, stage: '正在分析句子...' });
try {
setAnalysisState(prev => ({ ...prev, progress: 60, stage: '處理詞彙分析...' }));
const response = await fetch(API_URL, { ... });
setAnalysisState(prev => ({ ...prev, progress: 90, stage: '整理分析結果...' }));
const result = await response.json();
handleAnalysisResult(result);
setAnalysisState({ isAnalyzing: false, progress: 100, stage: '分析完成' });
} catch (error) {
handleAnalysisError(error);
}
};
```
### **階段六：閃卡整合 (2-3天)**
#### **6.1 閃卡保存API整合**
**目標**: 整合後端閃卡API用於詞彙保存
**檔案**: `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/services/flashcardsService.ts` (需新建)
**類別**: `FlashcardsService`
**方法**: `createFlashcard`, `getAuthToken`
```typescript
class FlashcardsService {
private baseURL = 'http://localhost:5008/api/flashcards';
async createFlashcard(cardData: FlashcardData): Promise<{success: boolean}> {
try {
const response = await fetch(this.baseURL, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${this.getAuthToken()}`
},
body: JSON.stringify({
word: cardData.word,
translation: cardData.translation,
definition: cardData.definition,
pronunciation: cardData.pronunciation,
partOfSpeech: cardData.partOfSpeech,
difficultyLevel: cardData.difficultyLevel,
example: cardData.example,
exampleTranslation: cardData.exampleTranslation
})
});
if (!response.ok) {
throw new Error(`API request failed: ${response.status}`);
}
return { success: true };
} catch (error) {
console.error('Save flashcard error:', error);
return { success: false, error: error.message };
}
}
private getAuthToken(): string | null {
return localStorage.getItem('auth_token');
}
}
export const flashcardsService = new FlashcardsService();
```
#### **6.2 認證機制整合**
**目標**: 實現JWT認證用於保護閃卡API
**檔案**: `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/services/authService.ts` (需新建)
**類別**: `AuthService`
**方法**: `login`, `logout`, `isAuthenticated`
```typescript
class AuthService {
private baseURL = 'http://localhost:5008/api/auth';
async login(username: string, password: string): Promise<{success: boolean, token?: string}> {
try {
const response = await fetch(`${this.baseURL}/login`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ username, password })
});
if (!response.ok) {
throw new Error('登入失敗');
}
const result = await response.json();
if (result.success && result.token) {
localStorage.setItem('auth_token', result.token);
return { success: true, token: result.token };
}
return { success: false };
} catch (error) {
console.error('Login error:', error);
return { success: false };
}
}
logout(): void {
localStorage.removeItem('auth_token');
}
isAuthenticated(): boolean {
return !!localStorage.getItem('auth_token');
}
}
export const authService = new AuthService();
```
---
## ✅ **測試計劃**
### **單元測試**
1. API調用函數測試
2. 數據轉換邏輯測試
3. 錯誤處理機制測試
4. 統計計算邏輯測試
### **整合測試**
1. 完整分析流程測試
2. 詞彙保存流程測試
3. 認證機制測試
4. 錯誤恢復機制測試
### **E2E測試**
1. 用戶完整使用流程
2. 各種輸入情況測試
3. 錯誤邊界情況測試
4. 性能和載入測試
---
## 📋 **實施檢查清單**
### **前端調整**
- [x] 移除API請求中的userLevel參數 ✅ **已完成**
- [x] 更新回應數據結構處理邏輯 ✅ **已完成**
- [x] 適配新的vocabularyAnalysis格式 ✅ **已完成**
- [ ] 更新語法修正面板數據處理 ⏳ **進行中**
- [x] 整合慣用語顯示邏輯 ✅ **已完成**ㄎ
- [ ] 實現統一錯誤處理機制 ⏳ **進行中**
- [ ] 優化載入狀態提示 ⏳ **進行中**
- [ ] 整合閃卡保存API ⏳ **進行中**
- [ ] 實現JWT認證機制 📅 **計劃中**
### **後端驗證**
- [x] 確認API端點正常運行 ✅ **已完成** - API健康檢查通過
- [x] 驗證回應格式正確性 ✅ **已完成** - 格式完全符合規格
- [x] 測試錯誤處理機制 ✅ **已完成** - 錯誤處理正常
- [ ] 確認認證機制有效 📅 **待實施** - JWT功能需要用戶系統
- [x] 驗證CORS設定正確 ✅ **已完成** - 前端可正常訪問
### **整合測試**
- [x] 前後端通信正常 ✅ **已完成** - API調用成功
- [x] 數據格式完全匹配 ✅ **已完成** - vocabularyAnalysis格式正確
- [x] 錯誤處理機制有效 ✅ **已完成** - 錯誤回饋正常
- [x] 性能表現符合預期 ✅ **已完成** - 3.5秒分析時間符合<5秒要求
- [x] 用戶體驗流暢 ✅ **已完成** - 前端頁面正常載入
---
## 🚀 **部署準備**
### **開發環境**
1. 確保後端運行在 localhost:5008
2. 確保前端運行在 localhost:3000
3. 配置CORS允許前端域名
4. 設定開發環境的Gemini API密鑰
### **測試環境**
1. 部署到測試服務器
2. 配置測試環境的環境變數
3. 執行完整的E2E測試
4. 進行性能和安全測試
### **生產環境**
1. 配置生產環境域名和SSL
2. 設定生產環境API密鑰
3. 配置監控和日誌系統
4. 準備回滾計劃
---
## 📊 **風險評估與緩解**
### **技術風險**
1. **API格式不匹配**
- 風險: 前後端數據格式差異
- 緩解: 詳細的格式驗證和測試
2. **性能問題**
- 風險: AI API響應時間過長
- 緩解: 實現載入狀態和超時處理
3. **錯誤處理不完善**
- 風險: 用戶體驗受影響
- 緩解: 完整的錯誤處理和降級機制
### **業務風險**
1. **功能缺失**
- 風險: 某些功能無法正常工作
- 緩解: 逐步測試和驗證
2. **用戶體驗下降**
- 風險: 串接過程中影響現有功能
- 緩解: 保持現有功能的向後兼容性
---
## 📈 **成功指標**
### **技術指標**
- API回應時間 < 5秒
- 錯誤率 < 1%
- 前端載入時間 < 2秒
- 詞彙分析準確率 > 90%
### **用戶體驗指標**
- 分析完成率 > 95%
- 用戶滿意度 > 4.5/5
- 功能使用率 > 80%
- 錯誤恢復時間 < 3秒
---
## 🔄 **後續維護計劃**
### **監控機制**
1. API調用成功率監控
2. 用戶行為數據收集
3. 錯誤日誌分析
4. 性能指標追蹤
### **優化計劃**
1. 基於用戶反饋優化UI/UX
2. AI分析結果質量提升
3. 新功能開發和整合
4. 性能持續優化
---
## 📚 **參考文件**
### **產品需求文件**
- `/Users/jettcheng1018/code/dramaling-vocab-learning/AI句子分析功能產品需求規格.md`
- `/Users/jettcheng1018/code/dramaling-vocab-learning/AI分析API技術實現規格.md`
- `/Users/jettcheng1018/code/dramaling-vocab-learning/系統整合與部署規格.md`
### **關鍵源碼檔案**
#### **後端檔案**
- `/Users/jettcheng1018/code/dramaling-vocab-learning/backend/DramaLing.Api/Controllers/AIController.cs`
- `/Users/jettcheng1018/code/dramaling-vocab-learning/backend/DramaLing.Api/Controllers/FlashcardsController.cs`
- `/Users/jettcheng1018/code/dramaling-vocab-learning/backend/DramaLing.Api/Controllers/AuthController.cs`
- `/Users/jettcheng1018/code/dramaling-vocab-learning/backend/DramaLing.Api/Services/GeminiService.cs`
#### **前端檔案**
- `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/app/generate/page.tsx` (主要分析頁面)
- `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/components/ClickableTextV2.tsx` (詞彙標記組件)
- `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/components/GrammarCorrectionPanel.tsx` (語法修正組件)
- `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/app/learn/page.tsx` (學習模式頁面)
### **配置檔案**
- `/Users/jettcheng1018/code/dramaling-vocab-learning/backend/DramaLing.Api/appsettings.json`
- `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/package.json`
- `/Users/jettcheng1018/code/dramaling-vocab-learning/frontend/next.config.js`
---
---
## 🎉 **實施狀態總結**
### **第一階段完成狀況 (2025-01-25)**
#### **✅ 已完成功能 (核心串接)**
1. **API格式適配** - 移除userLevel參數，更新請求格式
2. **回應數據處理** - 適配新的`result.data`結構
3. **詞彙分析整合** - 使用`vocabularyAnalysis`對象格式
4. **慣用語功能** - 整合`idioms`陣列顯示
5. **統計計算** - 修正詞彙難度統計邏輯
6. **API測試** - 驗證前後端通信正常
#### **📊 測試結果**
- ✅ **後端API健康檢查**: 正常運行
- ✅ **句子分析API**: 3.5秒回應時間，符合<5秒要求
- ✅ **數據格式匹配**: 100%兼容新後端格式
- ✅ **詞彙分析**: CEFR分級和統計正確
- ✅ **語法修正**: 錯誤檢測和修正建議正常
- ✅ **慣用語檢測**: 顯示和交互功能正常
#### **🚀 核心功能狀態**
- **AI句子分析**: ✅ **生產就緒**
- **詞彙標記**: ✅ **生產就緒**
- **語法修正**: ✅ **生產就緒**
- **慣用語學習**: ✅ **生產就緒**
- **統計卡片**: ✅ **生產就緒**
- **響應式設計**: ✅ **生產就緒**
#### **📈 性能指標達成**
- **API回應時間**: 3.5秒 < 5秒目標 ✅
- **前端載入**: <2秒 ✅
- **詞彙分析準確**: 基於Gemini 1.5 Flash ✅
- **用戶體驗**: 流暢互動 ✅
### **下一階段建議 (可選優化)**
1. **JWT認證整合** - 用於保護閃卡功能
2. **錯誤處理增強** - 更友善的錯誤提示
3. **載入狀態優化** - 進度指示器
4. **離線快取** - 分析結果本地存儲
---
**計劃制定者**: DramaLing技術團隊
**計劃版本**: v1.1 - 第一階段完成
**實際完成時間**: 1個工作天 (提前完成)
**完成狀態**: 🎯 **核心功能100%可用，生產就緒**
**下次評估**: 基於用戶回饋進行功能優化

265
note/AI句子分析規格/文件結構說明.md Normal file
View File

@ -0,0 +1,265 @@
# DramaLing 文件結構說明
## 📁 **文件組織架構**
### **核心規格文件**
```
📋 產品與技術規格 (按關注點分離)
├── 🎯 AI句子分析功能產品需求規格.md # 產品需求、用戶故事、商業目標
├── 🔧 AI分析API技術實現規格.md # API設計、數據模型、技術實現
└── 🚀 系統整合與部署規格.md # 系統整合、部署、監控
📚 架構與指導文件
├── 🏗️ docs/AI驅動產品後端技術架構指南.md # 後端架構設計原則和最佳實踐
└── 📋 後端架構優化待辦清單.md # 當前優化項目和進度追蹤
```
---
## 🎯 **文件用途說明**
### **產品團隊使用**
- **📋 產品需求規格** - 產品經理、UX設計師、QA測試
- 用戶故事和使用場景
- 功能需求和驗收標準
- 產品路線圖和KPI指標
- 非功能性需求
### **開發團隊使用**
- **🔧 API技術規格** - 後端開發工程師
- API端點設計和數據模型
- AI Prompt設計和版本管理
- 錯誤處理和安全設計
- 性能要求和優化策略
- **🏗️ 架構指南** - 技術主管、資深工程師
- 分層架構設計原則
- 程式碼組織和最佳實踐
- 性能優化和穩定性設計
- 擴展性和維護性指導
### **運維團隊使用**
- **🚀 整合部署規格** - DevOps工程師、運維團隊
- 環境配置和容器化
- CI/CD流程和部署策略
- 監控告警和故障排除
- 安全配置和合規要求
### **全團隊使用**
- **📋 優化待辦清單** - 所有技術團隊成員
- 當前優化項目和優先級
- 進度追蹤和責任分配
- 技術債務管理
- 架構改進記錄
---
## 🔄 **文件維護流程**
### **更新觸發條件**
```yaml
產品需求規格:
- 新功能規劃
- 用戶回饋整合
- 商業目標調整
- 定期產品審查
技術實現規格:
- API設計變更
- 數據模型調整
- 技術棧更新
- 安全要求變更
整合部署規格:
- 基礎設施變更
- 部署流程優化
- 監控需求更新
- 安全政策調整
架構指南:
- 技術決策更新
- 最佳實踐演進
- 工具和框架升級
- 團隊規模變化
```
### **版本管理策略**
```yaml
版本命名:
- 主要改版: v2.0, v3.0 (架構重大變更)
- 次要更新: v2.1, v2.2 (功能增加或修改)
- 修正更新: v2.1.1 (錯誤修正和澄清)
變更記錄:
- 每個文件包含詳細的更新記錄
- 記錄變更原因和影響範圍
- 標注向下相容性影響
- 提供遷移指導 (如需要)
```
---
## 📚 **閱讀指南**
### **新成員入門順序**
1. **📋 產品需求規格** - 了解產品目標和用戶需求
2. **🏗️ 架構指南** - 理解技術架構和設計原則
3. **🔧 API技術規格** - 掌握具體實現細節
4. **🚀 整合部署規格** - 了解系統整合和部署
5. **📋 優化待辦清單** - 參與當前改進項目
### **角色專用指南**
#### **產品經理**
```yaml
重點文件:
- 產品需求規格 (詳細閱讀)
- API技術規格 (概要了解)
- 整合部署規格 (監控部分)
關注要點:
- 用戶故事完整性
- 驗收標準明確性
- KPI指標合理性
- 技術可行性評估
```
#### **前端開發**
```yaml
重點文件:
- 產品需求規格 (UI/UX需求)
- API技術規格 (API端點和數據模型)
- 整合部署規格 (前端部分)
關注要點:
- API接口設計
- 數據結構定義
- 錯誤處理邏輯
- 性能要求
```
#### **後端開發**
```yaml
重點文件:
- API技術規格 (詳細閱讀)
- 架構指南 (詳細閱讀)
- 優化待辦清單 (參與執行)
關注要點:
- 服務架構設計
- 數據模型實現
- 錯誤處理策略
- 性能優化方案
```
#### **DevOps/運維**
```yaml
重點文件:
- 整合部署規格 (詳細閱讀)
- 架構指南 (基礎設施部分)
- API技術規格 (監控需求)
關注要點:
- 部署流程設計
- 監控告警配置
- 安全策略實施
- 災難恢復計劃
```
---
## 🔗 **文件間關聯**
### **依賴關係**
```mermaid
graph TD
A[產品需求規格] --> B[API技術規格]
A --> C[整合部署規格]
B --> C
D[架構指南] --> B
D --> E[優化待辦清單]
B --> E
```
### **交叉引用索引**
```yaml
功能需求 → 技術實現:
- FR1.1 文本輸入處理 → API端點 POST /api/ai/analyze-sentence
- FR1.2 AI分析核心 → Gemini服務整合和Prompt設計
- FR2.1 CEFR個人化 → 前端統計計算邏輯
- FR2.2 學習進度可視化 → 前端UI組件設計
技術實現 → 部署配置:
- GeminiOptions配置 → 環境變數和配置管理
- 健康檢查實現 → 監控和告警配置
- 錯誤處理設計 → 日誌和調試策略
- 性能要求 → 負載測試和優化
```
---
## ⚠️ **廢棄文件說明**
### **已移除的重複文件**
```yaml
舊文件結構 (v1.0):
❌ AI生成網頁前端需求規格.md → 整合到產品需求規格
❌ AI生成功能後端API規格.md → 重構為API技術規格
❌ AI生成功能前後端串接規格.md → 整合到部署規格
移除原因:
- 內容重疊和矛盾
- 前後端界限模糊
- 維護成本高
- 不符合行業標準
```
### **遷移對照表**
```yaml
內容遷移映射:
舊檔案 → 新檔案位置:
- 產品定位和用戶故事 → 產品需求規格
- API設計和數據模型 → API技術規格
- UI/UX需求和視覺設計 → 產品需求規格 (UI章節)
- 前後端整合邏輯 → 整合部署規格
- 開發環境配置 → 整合部署規格
- 測試策略和驗證 → 整合部署規格
```
---
## 📅 **維護計劃**
### **定期審查週期**
```yaml
月度審查:
- 優化待辦清單進度檢查
- 技術債務評估
- 新需求整合評估
季度審查:
- 產品需求規格更新
- 技術架構演進評估
- 文件結構優化
年度審查:
- 整體架構重新評估
- 文件體系重構
- 工具和流程升級
```
### **責任分工**
```yaml
文件擁有者:
- 產品需求規格: 產品經理
- API技術規格: 後端技術主管
- 整合部署規格: DevOps負責人
- 架構指南: 技術架構師
- 優化待辦清單: 開發團隊共同維護
```
---
**建立時間**: 2025-01-25
**維護團隊**: DramaLing全體技術團隊
**下次審查**: 2025-02-25

887
note/AI句子分析規格/系統整合與部署規格.md Normal file
View File

@ -0,0 +1,887 @@
# 系統整合與部署規格
## 📋 **文件資訊**
- **文件名稱**: 系統整合與部署規格
- **版本**: v2.0
- **建立日期**: 2025-01-25
- **最後更新**: 2025-01-25
- **負責團隊**: DramaLing DevOps團隊
- **適用系統**: AI句子分析功能全棧系統
---
## 🏗️ **系統架構圖**
### **整體架構**
```
┌─────────────────┐ HTTP/JSON ┌──────────────────┐ Gemini API ┌─────────────────┐
│ │ Request │ │ Request │ │
│ Frontend │ ──────────────► │ Backend API │ ──────────────► │ Google Gemini │
│ (Next.js) │ │ (.NET Core) │ │ AI Service │
│ Port 3000 │ ◄────────────── │ Port 5008 │ ◄────────────── │ │
│ │ Response │ │ Response │ │
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │
│ │
▼ ▼
┌─────────────────┐ ┌──────────────────┐
│ Local Storage │ │ SQLite Database │
│ - user_level │ │ - Cache Data │
│ - auth_token │ │ - Usage Stats │
└─────────────────┘ └──────────────────┘
```
### **數據流向**
```mermaid
sequenceDiagram
participant U as 用戶
participant F as 前端(3000)
participant B as 後端(5008)
participant G as Gemini API
participant D as 資料庫
U->>F: 1. 輸入英文句子
U->>F: 2. 點擊「分析句子」
F->>F: 3. 驗證輸入(≤300字符)
F->>F: 4. 讀取userLevel (localStorage)
F->>B: 5. POST /api/ai/analyze-sentence
B->>B: 6. 輸入驗證和處理
B->>G: 7. 調用Gemini API
G->>B: 8. 返回AI分析結果
B->>B: 9. 解析和格式化數據
B->>D: 10. 記錄使用統計 (可選)
B->>F: 11. 返回結構化分析結果
F->>F: 12. 計算個人化統計
F->>F: 13. 渲染詞彙標記和統計卡片
F->>U: 14. 顯示完整分析結果
```
---
## 🔄 **前後端整合規格**
### **API整合詳細設計**
#### **前端請求實現**
```typescript
// 位置: frontend/app/generate/page.tsx
const handleAnalyzeSentence = async () => {
try {
const response = await fetch('http://localhost:5008/api/ai/analyze-sentence', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${getAuthToken()}` // 可選
},
body: JSON.stringify({
inputText: textInput,
analysisMode: 'full',
options: {
includeGrammarCheck: true,
includeVocabularyAnalysis: true,
includeTranslation: true,
includeIdiomDetection: true,
includeExamples: true
}
})
});
if (!response.ok) {
throw new Error(`API請求失敗: ${response.status}`);
}
const result = await response.json();
handleAnalysisResult(result.data);
} catch (error) {
handleAnalysisError(error);
}
};
```
#### **數據處理邏輯**
```typescript
// 前端個人化統計計算
const calculateVocabularyStats = (vocabularyAnalysis, idioms, userLevel) => {
const userIndex = CEFR_LEVELS.indexOf(userLevel);
let simple = 0, moderate = 0, difficult = 0;
Object.values(vocabularyAnalysis).forEach(word => {
const wordIndex = CEFR_LEVELS.indexOf(word.difficultyLevel);
if (userIndex > wordIndex) simple++;
else if (userIndex === wordIndex) moderate++;
else difficult++;
});
return {
simpleCount: simple,
moderateCount: moderate,
difficultCount: difficult,
idiomCount: idioms.length
};
};
```
### **錯誤處理整合**
#### **前端錯誤處理**
```typescript
const handleAnalysisError = (error) => {
console.error('Analysis error:', error);
// 顯示用戶友善的錯誤訊息
if (error.message.includes('timeout')) {
setErrorMessage('分析服務繁忙，請稍後再試');
} else if (error.message.includes('network')) {
setErrorMessage('網路連接問題，請檢查網路狀態');
} else {
setErrorMessage('分析過程中發生錯誤，請稍後再試');
}
// 提供降級體驗
setFallbackAnalysisView(textInput);
};
```
#### **後端錯誤映射**
```csharp
// 位置: backend/Controllers/AIController.cs
private ApiErrorResponse CreateErrorResponse(string code, string message, object? details, string requestId)
{
var userFriendlyMessage = code switch
{
"INVALID_INPUT" => "輸入格式不正確，請檢查文本內容",
"AI_SERVICE_ERROR" => "AI分析服務暫時不可用，請稍後重試",
"RATE_LIMIT_EXCEEDED" => "請求過於頻繁，請稍候再試",
"TIMEOUT" => "分析超時，請嘗試較短的句子",
_ => "系統暫時不可用，請稍後重試"
};
return new ApiErrorResponse
{
Success = false,
Error = new ApiError
{
Code = code,
Message = userFriendlyMessage,
Details = details,
Suggestions = GetSuggestionsForError(code)
},
RequestId = requestId,
Timestamp = DateTime.UtcNow
};
}
```
---
## 🔧 **開發環境配置**
### **環境準備**
#### **必要軟體**
```yaml
開發工具:
- Node.js: >= 18.0.0
- .NET SDK: >= 8.0.0
- Git: >= 2.40.0
- VSCode: 最新版本
瀏覽器支援:
- Chrome: >= 90 (開發調試用)
- Safari: >= 14 (測試用)
- Firefox: >= 88 (測試用)
可選工具:
- Docker: >= 20.0 (容器化部署)
- Redis: >= 6.0 (本地快取測試)
- Postman: API測試
```
#### **環境變數配置**
```bash
# 後端環境變數
export GEMINI_API_KEY="your-gemini-api-key"
export ASPNETCORE_ENVIRONMENT="Development"
export DRAMALING_DB_CONNECTION="Data Source=dramaling_test.db"
# 前端環境變數 (可選)
export NEXT_PUBLIC_API_URL="http://localhost:5008"
export NEXT_PUBLIC_ENVIRONMENT="development"
```
### **啟動流程**
#### **開發環境啟動腳本**
```bash
#!/bin/bash
# 位置: start-development.sh
echo "🚀 啟動 DramaLing 開發環境..."
# 1. 檢查必要軟體
check_prerequisites() {
command -v node >/dev/null 2>&1 || { echo "需要安裝 Node.js"; exit 1; }
command -v dotnet >/dev/null 2>&1 || { echo "需要安裝 .NET SDK"; exit 1; }
}
# 2. 啟動後端 API (Port 5008)
start_backend() {
echo "🔧 啟動後端 API..."
cd backend/DramaLing.Api
dotnet restore
dotnet run &
BACKEND_PID=$!
echo "後端 PID: $BACKEND_PID"
}
# 3. 啟動前端 (Port 3000)
start_frontend() {
echo "🎨 啟動前端..."
cd ../../frontend
npm install
npm run dev &
FRONTEND_PID=$!
echo "前端 PID: $FRONTEND_PID"
}
# 4. 健康檢查
health_check() {
echo "🏥 執行健康檢查..."
sleep 10
# 檢查後端
if curl -f http://localhost:5008/health >/dev/null 2>&1; then
echo "✅ 後端服務正常"
else
echo "❌ 後端服務異常"
fi
# 檢查前端
if curl -f http://localhost:3000 >/dev/null 2>&1; then
echo "✅ 前端服務正常"
else
echo "❌ 前端服務異常"
fi
}
# 執行啟動流程
check_prerequisites
start_backend
start_frontend
health_check
echo "🎉 開發環境啟動完成！"
echo "前端: http://localhost:3000"
echo "後端API: http://localhost:5008"
echo "API文檔: http://localhost:5008/swagger"
```
---
## 🧪 **測試整合策略**
### **整合測試架構**
#### **API整合測試**
```csharp
[TestFixture]
public class AIAnalysisIntegrationTests : IClassFixture<WebApplicationFactory<Program>>
{
private readonly WebApplicationFactory<Program> _factory;
private readonly HttpClient _client;
[SetUp]
public void Setup()
{
_client = _factory.CreateClient();
}
[Test]
public async Task AnalyzeSentence_EndToEnd_ReturnsValidResponse()
{
// Arrange
var request = new
{
inputText = "She just join the team, so let's cut her some slack.",
analysisMode = "full"
};
// Act
var response = await _client.PostAsJsonAsync("/api/ai/analyze-sentence", request);
// Assert
response.EnsureSuccessStatusCode();
var result = await response.Content.ReadFromJsonAsync<AnalysisResponse>();
Assert.That(result.Success, Is.True);
Assert.That(result.Data.VocabularyAnalysis.Count, Is.GreaterThan(0));
Assert.That(result.Data.SentenceMeaning, Is.Not.Empty);
Assert.That(result.Data.Idioms.Count, Is.GreaterThan(0));
}
}
```
#### **前端E2E測試**
```typescript
// 使用 Playwright 或 Cypress
describe('AI Analysis E2E Flow', () => {
test('complete analysis workflow', async ({ page }) => {
// 1. 導航到分析頁面
await page.goto('http://localhost:3000/generate');
// 2. 輸入測試句子
await page.fill('[data-testid="text-input"]',
'She just join the team, so let\'s cut her some slack.');
// 3. 點擊分析按鈕
await page.click('[data-testid="analyze-button"]');
// 4. 等待分析完成
await page.waitForSelector('[data-testid="analysis-result"]', { timeout: 10000 });
// 5. 驗證結果
await expect(page.locator('[data-testid="grammar-correction"]')).toBeVisible();
await expect(page.locator('[data-testid="vocabulary-analysis"]')).toBeVisible();
await expect(page.locator('[data-testid="idioms-section"]')).toBeVisible();
await expect(page.locator('[data-testid="statistics-cards"]')).toBeVisible();
// 6. 測試詞彙點擊
await page.click('[data-testid="word-she"]');
await expect(page.locator('[data-testid="vocab-popup"]')).toBeVisible();
});
});
```
### **性能測試整合**
#### **負載測試配置**
```yaml
# 使用 k6 或 JMeter
負載測試場景:
- 正常負載: 100 用戶，持續 10 分鐘
- 壓力測試: 500 用戶，持續 5 分鐘
- 尖峰測試: 1000 用戶，持續 2 分鐘
性能指標:
- 回應時間P95: < 5秒
- 錯誤率: < 1%
- 吞吐量: > 100 RPS
- 資源使用: CPU < 80%, Memory < 70%
```
---
## 🚀 **部署架構**
### **環境配置**
#### **開發環境 (Development)**
```yaml
基礎設施:
- 本地開發機器
- SQLite 資料庫
- In-Memory 快取
- Gemini API (測試金鑰)
配置特點:
- 詳細日誌輸出
- 熱重載支援
- Swagger API 文檔
- CORS 寬鬆政策
```
#### **測試環境 (Staging)**
```yaml
基礎設施:
- 雲端虛擬機 或 Docker 容器
- PostgreSQL 資料庫
- Redis 快取
- Gemini API (測試金鑰)
配置特點:
- 生產環境模擬
- 效能監控啟用
- 自動化測試整合
- 安全掃描
```
#### **生產環境 (Production)**
```yaml
基礎設施:
- Kubernetes 叢集 或 雲端服務
- PostgreSQL 高可用性叢集
- Redis 叢集
- Gemini API (生產金鑰)
- CDN 和負載均衡
配置特點:
- 高可用性 (99.9%+)
- 自動擴容
- 全面監控和告警
- 災難恢復機制
```
### **容器化部署**
#### **Docker Compose 配置**
```yaml
# docker-compose.yml
version: '3.8'
services:
# 後端 API 服務
backend:
build:
context: ./backend/DramaLing.Api
dockerfile: Dockerfile
ports:
- "5008:5008"
environment:
- ASPNETCORE_ENVIRONMENT=Production
- GEMINI_API_KEY=${GEMINI_API_KEY}
- ConnectionStrings__DefaultConnection=${DB_CONNECTION}
depends_on:
- database
- redis
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:5008/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 40s
# 前端服務
frontend:
build:
context: ./frontend
dockerfile: Dockerfile
ports:
- "3000:3000"
environment:
- NEXT_PUBLIC_API_URL=http://backend:5008
depends_on:
- backend
# 資料庫服務
database:
image: postgres:15-alpine
environment:
- POSTGRES_DB=dramaling
- POSTGRES_USER=${DB_USER}
- POSTGRES_PASSWORD=${DB_PASSWORD}
volumes:
- postgres_data:/var/lib/postgresql/data
ports:
- "5432:5432"
# 快取服務
redis:
image: redis:7-alpine
ports:
- "6379:6379"
volumes:
- redis_data:/data
volumes:
postgres_data:
redis_data:
```
#### **Kubernetes 部署配置**
```yaml
# k8s-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: dramaling-backend
spec:
replicas: 3
selector:
matchLabels:
app: dramaling-backend
template:
metadata:
labels:
app: dramaling-backend
spec:
containers:
- name: backend
image: dramaling/backend:latest
ports:
- containerPort: 5008
env:
- name: GEMINI_API_KEY
valueFrom:
secretKeyRef:
name: ai-secrets
key: gemini-api-key
- name: ConnectionStrings__DefaultConnection
valueFrom:
configMapKeyRef:
name: app-config
key: db-connection
resources:
requests:
memory: "256Mi"
cpu: "250m"
limits:
memory: "512Mi"
cpu: "500m"
livenessProbe:
httpGet:
path: /health
port: 5008
initialDelaySeconds: 30
periodSeconds: 30
readinessProbe:
httpGet:
path: /health
port: 5008
initialDelaySeconds: 5
periodSeconds: 5
```
---
## 📊 **監控與可觀測性**
### **日誌整合**
#### **結構化日誌配置**
```json
// appsettings.Production.json
{
"Serilog": {
"Using": ["Serilog.Sinks.Console", "Serilog.Sinks.ApplicationInsights"],
"MinimumLevel": {
"Default": "Information",
"Override": {
"Microsoft": "Warning",
"System": "Warning",
"DramaLing": "Information"
}
},
"WriteTo": [
{
"Name": "Console",
"Args": {
"outputTemplate": "{Timestamp:yyyy-MM-dd HH:mm:ss} [{Level:u3}] {Message:lj} {Properties:j}{NewLine}{Exception}"
}
},
{
"Name": "ApplicationInsights",
"Args": {
"instrumentationKey": "{ApplicationInsights:InstrumentationKey}"
}
}
],
"Enrich": ["FromLogContext", "WithMachineName", "WithThreadId"]
}
}
```
#### **前端錯誤追蹤**
```typescript
// 錯誤邊界和監控
class ErrorBoundary extends React.Component {
componentDidCatch(error, errorInfo) {
// 發送錯誤到監控服務
console.error('React Error Boundary:', error, errorInfo);
// 可選：整合 Sentry 或其他錯誤追蹤服務
if (typeof window !== 'undefined' && window.gtag) {
window.gtag('event', 'exception', {
description: error.toString(),
fatal: false
});
}
}
}
```
### **健康檢查系統**
#### **深度健康檢查**
```csharp
public class SystemHealthCheck : IHealthCheck
{
private readonly IGeminiService _geminiService;
private readonly DramaLingDbContext _dbContext;
public async Task<HealthCheckResult> CheckHealthAsync(
HealthCheckContext context, CancellationToken cancellationToken = default)
{
var checks = new Dictionary<string, HealthStatus>();
// 檢查資料庫連接
try
{
await _dbContext.Database.CanConnectAsync(cancellationToken);
checks["database"] = HealthStatus.Healthy;
}
catch (Exception ex)
{
checks["database"] = HealthStatus.Unhealthy;
}
// 檢查 AI 服務
try
{
var isHealthy = await _geminiService.HealthCheckAsync();
checks["gemini_api"] = isHealthy ? HealthStatus.Healthy : HealthStatus.Degraded;
}
catch (Exception ex)
{
checks["gemini_api"] = HealthStatus.Unhealthy;
}
// 檢查記憶體使用
var memoryUsage = GC.GetTotalMemory(false);
checks["memory"] = memoryUsage < 500_000_000 ? HealthStatus.Healthy : HealthStatus.Degraded;
var overallStatus = checks.Values.All(s => s == HealthStatus.Healthy)
? HealthStatus.Healthy
: checks.Values.Any(s => s == HealthStatus.Unhealthy)
? HealthStatus.Unhealthy
: HealthStatus.Degraded;
return new HealthCheckResult(overallStatus,
description: $"System health: {string.Join(", ", checks.Select(c => $"{c.Key}:{c.Value}"))}",
data: checks.ToDictionary(c => c.Key, c => (object)c.Value.ToString()));
}
}
```
---
## 🔒 **安全整合**
### **HTTPS 配置**
```yaml
開發環境:
- HTTP: localhost:3000, localhost:5008
- 自簽證書: dotnet dev-certs https --trust
生產環境:
- HTTPS: 強制重定向
- TLS 1.3: 最低版本要求
- HSTS: 嚴格傳輸安全
- 證書: Let's Encrypt 或企業CA
```
### **CORS 政策**
```csharp
// 開發環境 CORS 配置
services.AddCors(options =>
{
options.AddPolicy("Development", policy =>
{
policy.WithOrigins("http://localhost:3000", "http://localhost:3001")
.AllowAnyHeader()
.AllowAnyMethod()
.AllowCredentials();
});
options.AddPolicy("Production", policy =>
{
policy.WithOrigins("https://dramaling.com", "https://app.dramaling.com")
.AllowAnyHeader()
.AllowAnyMethod()
.AllowCredentials();
});
});
```
---
## 📈 **監控整合**
### **應用程式監控**
#### **關鍵指標儀表板**
```yaml
業務指標:
- 每日分析次數
- 用戶活躍度
- 功能使用分佈
- AI分析成功率
技術指標:
- API回應時間分佈
- 資料庫查詢性能
- 記憶體和CPU使用
- 錯誤率和異常統計
用戶體驗指標:
- 頁面載入時間
- 首次內容繪製 (FCP)
- 最大內容繪製 (LCP)
- 累積佈局偏移 (CLS)
```
#### **告警配置**
```yaml
嚴重告警:
- API 錯誤率 > 5% (5分鐘內)
- 回應時間P95 > 10秒 (5分鐘內)
- 服務不可用 > 2分鐘
- 資料庫連接失敗
警告告警:
- CPU 使用率 > 80% (10分鐘內)
- 記憶體使用率 > 85% (10分鐘內)
- AI API 調用失敗率 > 10%
- 磁碟空間不足 < 10%
```
---
## 🔧 **故障排除指南**
### **常見問題和解決方案**
#### **連接問題**
```yaml
問題: CORS 錯誤
症狀: "Access to fetch blocked by CORS policy"
解決: 檢查後端 CORS 設定，確認前端域名在允許清單
問題: 連接被拒絕
症狀: "Connection refused" 或 "ECONNREFUSED"
解決: 確認後端服務正在運行，檢查埠號是否正確
問題: 超時錯誤
症狀: "Request timeout" 或響應超過 30 秒
解決: 檢查 AI API 金鑰，網路連接，增加超時設定
```
#### **資料問題**
```yaml
問題: AI 回應格式錯誤
症狀: "Cannot read property 'vocabularyAnalysis' of undefined"
解決: 檢查 Gemini API 回應格式，更新錯誤處理邏輯
問題: 詞彙分析為空
症狀: 分析結果不包含詞彙資訊
解決: 檢查 AI Prompt 設計，確認輸入文本有效
問題: 統計數字不一致
症狀: 統計卡片數字與實際標記不符
解決: 檢查前端統計計算邏輯，確認分類算法正確
```
### **調試工具**
#### **開發調試指令**
```bash
# 檢查服務狀態
curl -I http://localhost:5008/health
curl -I http://localhost:3000
# 測試 API 端點
curl -X POST http://localhost:5008/api/ai/analyze-sentence \
-H "Content-Type: application/json" \
-d '{"inputText":"Test sentence","analysisMode":"full"}'
# 檢查日誌
docker logs dramaling-backend
docker logs dramaling-frontend
# 檢查資源使用
docker stats
top -p $(pgrep dotnet)
```
#### **生產監控指令**
```bash
# 健康檢查
kubectl get pods -l app=dramaling
kubectl describe pod dramaling-backend-xxx
# 查看日誌
kubectl logs -f deployment/dramaling-backend
kubectl logs -f deployment/dramaling-frontend
# 性能監控
kubectl top pods
kubectl top nodes
```
---
## 📋 **部署檢查清單**
### **部署前檢查**
- [ ] 所有測試通過 (單元、整合、E2E)
- [ ] 安全掃描無嚴重漏洞
- [ ] 性能基準測試達標
- [ ] 配置檔案正確設定
- [ ] 環境變數和金鑰配置完成
- [ ] 資料庫遷移腳本準備
- [ ] 監控和告警配置完成
- [ ] 回滾計劃準備
### **部署後驗證**
- [ ] 健康檢查端點回應正常
- [ ] API 功能端到端測試通過
- [ ] 前端頁面載入和功能正常
- [ ] 監控指標顯示正常
- [ ] 日誌記錄正確產生
- [ ] 告警機制測試正常
- [ ] 負載測試驗證性能
- [ ] 安全掃描確認無新漏洞
---
## 🔄 **CI/CD 流程**
### **持續整合流程**
```yaml
觸發條件:
- 主分支推送 (main)
- Pull Request 建立
- 標籤建立 (v*.*.*)
建置步驟:
1. 程式碼檢出
2. 依賴安裝
3. 靜態分析 (ESLint, SonarQube)
4. 單元測試執行
5. 測試覆蓋率檢查
6. 安全掃描
7. 建置 Docker 映像
8. 整合測試執行
部署條件:
- 所有測試通過
- 程式碼覆蓋率 > 80%
- 安全掃描通過
- 人工審核批准 (生產部署)
```
### **持續部署流程**
```yaml
測試環境自動部署:
- 主分支每次推送自動部署
- 自動執行煙霧測試
- 通知團隊部署狀態
生產環境部署:
- 手動觸發或定期發布
- 藍綠部署或滾動更新
- 自動回滾機制
- 部署後監控和驗證
```
---
**文件版本**: v2.0
**DevOps負責人**: DramaLing DevOps團隊
**最後更新**: 2025-01-25
**下次審查**: 2025-02-25
**關聯文件**:
- 《AI句子分析功能產品需求規格》- 產品需求和用戶故事
- 《AI分析API技術實現規格》- API設計和技術實現
- 《AI驅動產品後端技術架構指南》- 架構設計指導原則