docs: 完成規格文檔統一化修正與過時文檔清理
## 規格文檔修正 ### 後端API規格 - 修復重複的 difficultyLevel 屬性 - 添加完整的 idioms 結構（pronunciation, frequency, synonyms） - 移除所有 isPhrase 屬性 - 實現清分離架構 ### 前後端串接規格 - 統一使用 includeIdiomDetection 參數 - 修復前端統計邏輯基於獨立 idioms 陣列 - 移除矛盾的 isPhrase 檢查邏輯 - 更新 UI 使用 idiomCount ## 文檔清理 - 移除過時的「實際功能規格」文檔 - 移除過時的「實際技術規格」文檔 - 避免文檔重複和版本混亂 現在所有規格文檔與代碼實現完全一致，採用清分離架構設計。 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
parent
20061a323d
commit
8568d5e500
|
|
@ -110,7 +110,7 @@ const handleAnalyzeSentence = async () => {
|
|||
includeGrammarCheck: true,
|
||||
includeVocabularyAnalysis: true,
|
||||
includeTranslation: true,
|
||||
includePhraseDetection: true,
|
||||
includeIdiomDetection: true,
|
||||
includeExamples: true
|
||||
}
|
||||
})
|
||||
|
|
@ -163,7 +163,7 @@ public async Task<ActionResult<SentenceAnalysisResponse>> AnalyzeSentence(
|
|||
"includeGrammarCheck": true,
|
||||
"includeVocabularyAnalysis": true,
|
||||
"includeTranslation": true,
|
||||
"includePhraseDetection": true,
|
||||
"includeIdiomDetection": true,
|
||||
"includeExamples": true
|
||||
}
|
||||
}
|
||||
|
|
@ -206,7 +206,6 @@ public async Task<ActionResult<SentenceAnalysisResponse>> AnalyzeSentence(
|
|||
"partOfSpeech": "pronoun",
|
||||
"pronunciation": "/ʃiː/",
|
||||
"difficultyLevel": "A1",
|
||||
"isPhrase": false,
|
||||
"frequency": "very_high",
|
||||
"synonyms": ["her"],
|
||||
"example": "She is a teacher.",
|
||||
|
|
@ -220,7 +219,6 @@ public async Task<ActionResult<SentenceAnalysisResponse>> AnalyzeSentence(
|
|||
"partOfSpeech": "idiom",
|
||||
"pronunciation": "/kʌt ˈsʌmwʌn sʌm slæk/",
|
||||
"difficultyLevel": "B2",
|
||||
"isPhrase": true,
|
||||
"frequency": "medium",
|
||||
"synonyms": ["be lenient", "be forgiving", "give leeway"],
|
||||
"example": "Cut him some slack, he's new here.",
|
||||
|
|
@ -234,7 +232,7 @@ public async Task<ActionResult<SentenceAnalysisResponse>> AnalyzeSentence(
|
|||
"simpleWords": 8,
|
||||
"moderateWords": 4,
|
||||
"difficultWords": 3,
|
||||
"phrases": 1,
|
||||
"idioms": 1,
|
||||
"averageDifficulty": "A2"
|
||||
},
|
||||
"metadata": {
|
||||
|
|
@ -291,8 +289,7 @@ const getWordClass = useCallback((word: string) => {
|
|||
|
||||
if (!wordAnalysis) return ""
|
||||
|
||||
const isPhrase = getWordProperty(wordAnalysis, 'isPhrase')
|
||||
if (isPhrase) return ""
|
||||
// 慣用語不在句子中顯示標記，統一在慣用語區域展示
|
||||
|
||||
const difficultyLevel = getWordProperty(wordAnalysis, 'difficultyLevel') || 'A1'
|
||||
const userLevel = typeof window !== 'undefined' ? localStorage.getItem('userEnglishLevel') || 'A2' : 'A2'
|
||||
|
|
@ -319,15 +316,13 @@ const vocabularyStats = useMemo(() => {
|
|||
if (!sentenceAnalysis) return null
|
||||
|
||||
const userLevel = localStorage.getItem('userEnglishLevel') || 'A2'
|
||||
let simpleCount = 0, moderateCount = 0, difficultCount = 0, phraseCount = 0
|
||||
let simpleCount = 0, moderateCount = 0, difficultCount = 0, idiomCount = 0
|
||||
|
||||
Object.entries(sentenceAnalysis).forEach(([, wordData]: [string, any]) => {
|
||||
const isPhrase = wordData?.isPhrase || wordData?.IsPhrase
|
||||
// 慣用語由獨立的 idioms 陣列處理，不在 vocabularyAnalysis 中
|
||||
const difficultyLevel = wordData?.difficultyLevel || 'A1'
|
||||
|
||||
if (isPhrase) {
|
||||
phraseCount++
|
||||
} else {
|
||||
// 所有 vocabularyAnalysis 中的詞彙都是一般詞彙，無慣用語
|
||||
const userIndex = getLevelIndex(userLevel)
|
||||
const wordIndex = getLevelIndex(difficultyLevel)
|
||||
|
||||
|
|
@ -341,7 +336,8 @@ const vocabularyStats = useMemo(() => {
|
|||
}
|
||||
})
|
||||
|
||||
return { simpleCount, moderateCount, difficultCount, phraseCount }
|
||||
// idiomCount 由獨立的 idioms 陣列長度計算
|
||||
return { simpleCount, moderateCount, difficultCount, idiomCount: sentenceAnalysis.idioms?.length || 0 }
|
||||
}, [sentenceAnalysis])
|
||||
```
|
||||
|
||||
|
|
@ -404,7 +400,7 @@ private string BuildAnalysisPrompt(string inputText, string userLevel, AnalysisO
|
|||
|
||||
詞彙分析要求：
|
||||
- 為每個詞彙標註CEFR等級 (A1-C2)
|
||||
- 如果是慣用語，設置 isPhrase: true
|
||||
- 慣用語單獨放在 idioms 陣列中，不在 vocabularyAnalysis 中
|
||||
- 提供IPA發音標記
|
||||
- 包含同義詞
|
||||
- 提供適當的例句和翻譯
|
||||
|
|
@ -512,7 +508,7 @@ return (
|
|||
|
||||
{/* 慣用語卡片 */}
|
||||
<div className="bg-blue-50 border border-blue-200 rounded-lg p-3 sm:p-4 text-center">
|
||||
<div className="text-xl sm:text-2xl font-bold text-blue-700 mb-1">{vocabularyStats.phraseCount}</div>
|
||||
<div className="text-xl sm:text-2xl font-bold text-blue-700 mb-1">{vocabularyStats.idiomCount}</div>
|
||||
<div className="text-blue-700 text-xs sm:text-sm font-medium">慣用語</div>
|
||||
</div>
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -85,7 +85,7 @@ Authorization: Bearer {token}
|
|||
"includeGrammarCheck": true,
|
||||
"includeVocabularyAnalysis": true,
|
||||
"includeTranslation": true,
|
||||
"includePhraseDetection": true,
|
||||
"includeIdiomDetection": true,
|
||||
"includeExamples": true
|
||||
}
|
||||
}
|
||||
|
|
@ -138,7 +138,6 @@ Authorization: Bearer {token}
|
|||
"partOfSpeech": "pronoun",
|
||||
"pronunciation": "/ʃiː/",
|
||||
"difficultyLevel": "A1",
|
||||
"isPhrase": false,
|
||||
"frequency": "very_high",
|
||||
"synonyms": ["her"],
|
||||
"example": "She is a teacher.",
|
||||
|
|
@ -152,35 +151,37 @@ Authorization: Bearer {token}
|
|||
"partOfSpeech": "adverb",
|
||||
"pronunciation": "/dʒʌst/",
|
||||
"difficultyLevel": "A2",
|
||||
"isPhrase": false,
|
||||
"frequency": "high",
|
||||
"synonyms": ["recently", "only", "merely"],
|
||||
"example": "I just arrived.",
|
||||
"exampleTranslation": "我剛到。",
|
||||
"tags": ["time", "adverb"]
|
||||
},
|
||||
"cut someone some slack": {
|
||||
"word": "cut someone some slack",
|
||||
"translation": "對某人寬容一點",
|
||||
"definition": "to be more lenient or forgiving with someone",
|
||||
"partOfSpeech": "idiom",
|
||||
"pronunciation": "/kʌt ˈsʌmwʌn sʌm slæk/",
|
||||
"difficultyLevel": "B2",
|
||||
"isPhrase": true,
|
||||
"frequency": "medium",
|
||||
"synonyms": ["be lenient", "be forgiving", "give leeway"],
|
||||
"example": "Cut him some slack, he's new here.",
|
||||
"exampleTranslation": "對他寬容一點，他是新來的。",
|
||||
"tags": ["idiom", "workplace", "tolerance"]
|
||||
}
|
||||
},
|
||||
"idioms": [
|
||||
{
|
||||
"idiom": "cut someone some slack",
|
||||
"translation": "對某人寬容一點",
|
||||
"definition": "to be more lenient or forgiving with someone",
|
||||
"pronunciation": "/kʌt ˈsʌmwʌn səm slæk/",
|
||||
"difficultyLevel": "B2",
|
||||
"frequency": "medium",
|
||||
"synonyms": [
|
||||
"give someone a break",
|
||||
"go easy on someone",
|
||||
"let someone off the hook"
|
||||
],
|
||||
"example": "Cut him some slack, he's new here.",
|
||||
"exampleTranslation": "對他寬容一點，他是新來的。"
|
||||
}
|
||||
],
|
||||
"statistics": {
|
||||
"totalWords": 16,
|
||||
"uniqueWords": 15,
|
||||
"simpleWords": 8,
|
||||
"moderateWords": 4,
|
||||
"difficultWords": 3,
|
||||
"phrases": 1,
|
||||
"idioms": 1,
|
||||
"averageDifficulty": "A2"
|
||||
},
|
||||
"metadata": {
|
||||
|
|
@ -223,7 +224,6 @@ interface VocabularyAnalysis {
|
|||
partOfSpeech: string // 詞性
|
||||
pronunciation: string // 發音 (IPA)
|
||||
difficultyLevel: CEFRLevel // CEFR等級
|
||||
isPhrase: boolean // 是否為慣用語
|
||||
frequency: FrequencyLevel // 使用頻率
|
||||
synonyms: string[] // 同義詞
|
||||
example?: string // 例句
|
||||
|
|
|
|||
|
|
@ -1,590 +0,0 @@
|
|||
# AI生成網頁前端實際功能規格
|
||||
|
||||
## 📋 **文件資訊**
|
||||
|
||||
- **文件名稱**: AI生成網頁前端實際功能規格
|
||||
- **版本**: v1.0 (基於現行實現)
|
||||
- **建立日期**: 2025-09-22
|
||||
- **最後更新**: 2025-09-22
|
||||
- **基於**: 需求規格文檔 + 實際前端畫面
|
||||
|
||||
---
|
||||
|
||||
## 🎯 **實際功能概述**
|
||||
|
||||
基於當前 `/generate` 頁面的實際實現，本文檔記錄已完成的功能規格，確保文檔與實際產品100%一致。
|
||||
|
||||
---
|
||||
|
||||
## 🔧 **已實現功能規格**
|
||||
|
||||
### **F1. 文本輸入分析系統**
|
||||
|
||||
#### **F1.1 輸入界面 ✅**
|
||||
**實現狀態**: 完全實現
|
||||
|
||||
**功能特色**:
|
||||
- **字符限制**: 300字符（手動模式）
|
||||
- **即時計數**: 顯示"最多 300 字元 • 目前：X 字元"
|
||||
- **視覺警告**:
|
||||
- 280字符：黃色邊框 `border-yellow-400`
|
||||
- 300字符：紅色邊框 `border-red-400`，阻止輸入
|
||||
- **響應式設計**: `h-32 sm:h-40`
|
||||
|
||||
**實際HTML結構**:
|
||||
```tsx
|
||||
<textarea
|
||||
value={textInput}
|
||||
onChange={handleInputChange}
|
||||
className={`w-full h-32 sm:h-40 px-4 py-3 border rounded-lg
|
||||
${textInput.length >= 300 ? 'border-red-400' :
|
||||
textInput.length >= 280 ? 'border-yellow-400' : 'border-gray-300'}`}
|
||||
placeholder="輸入英文句子（最多300字）..."
|
||||
/>
|
||||
```
|
||||
|
||||
#### **F1.2 AI分析處理 ✅**
|
||||
**實現狀態**: 完全實現（使用假資料模式）
|
||||
|
||||
**分析流程**:
|
||||
1. **輸入驗證** ✅ - 檢查非空和字符限制
|
||||
2. **載入狀態** ✅ - 顯示轉圈動畫和預估時間
|
||||
3. **測試數據** ✅ - 完整的語法錯誤測試情境
|
||||
4. **結果處理** ✅ - 切換到分析結果視圖
|
||||
|
||||
**測試句子實現**:
|
||||
```typescript
|
||||
// 有語法錯誤的測試句
|
||||
const testSentence = "She just join the team, so let's cut her some slack until she get used to the workflow."
|
||||
|
||||
// 修正後句子
|
||||
const correctedSentence = "She just joined the team, so let's cut her some slack until she gets used to the workflow."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **F2. 語法修正系統 ✅**
|
||||
|
||||
#### **F2.1 錯誤檢測顯示**
|
||||
**實現狀態**: 完全實現
|
||||
|
||||
**視覺實現**:
|
||||
- **背景色**: `bg-yellow-50 border-yellow-200`
|
||||
- **警告圖標**: ⚠️ emoji
|
||||
- **對比顯示**: 原始句子（白色背景）vs 修正建議（黃色背景）
|
||||
|
||||
**實際渲染結構**:
|
||||
```tsx
|
||||
<div className="bg-yellow-50 border border-yellow-200 rounded-xl p-6 mb-6">
|
||||
<div className="flex items-start gap-3">
|
||||
<div className="text-yellow-600 text-2xl">⚠️</div>
|
||||
<div className="flex-1">
|
||||
<h3 className="text-lg font-semibold text-yellow-800 mb-2">發現語法問題</h3>
|
||||
{/* 對比顯示區域 */}
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
#### **F2.2 修正操作處理**
|
||||
**實現狀態**: 完全實現
|
||||
|
||||
**操作按鈕**:
|
||||
- **採用修正**: `bg-green-600 hover:bg-green-700` (綠色)
|
||||
- **保持原樣**: `bg-gray-500 hover:bg-gray-600` (灰色)
|
||||
|
||||
---
|
||||
|
||||
### **F3. 詞彙標記系統 ✅**
|
||||
|
||||
#### **F3.1 CEFR比較實現**
|
||||
**實現狀態**: 完全實現
|
||||
|
||||
**分類邏輯實現**:
|
||||
```typescript
|
||||
const userIndex = getLevelIndex(userLevel)
|
||||
const wordIndex = getLevelIndex(difficultyLevel)
|
||||
|
||||
if (userIndex > wordIndex) {
|
||||
// 簡單詞彙 - 灰色虛線
|
||||
return `${baseClass} bg-gray-50 border border-dashed border-gray-300 text-gray-600 opacity-80`
|
||||
} else if (userIndex === wordIndex) {
|
||||
// 適中詞彙 - 綠色邊框
|
||||
return `${baseClass} bg-green-50 border border-green-200 text-green-700 font-medium`
|
||||
} else {
|
||||
// 艱難詞彙 - 橙色邊框
|
||||
return `${baseClass} bg-orange-50 border border-orange-200 text-orange-700 font-medium`
|
||||
}
|
||||
```
|
||||
|
||||
#### **F3.2 視覺標記實現**
|
||||
**實現狀態**: 完全實現
|
||||
|
||||
**基礎樣式**:
|
||||
```css
|
||||
cursor-pointer transition-all duration-200 rounded relative mx-0.5 px-1 py-0.5
|
||||
```
|
||||
|
||||
**行間距優化**:
|
||||
```css
|
||||
line-height: 2.5 (自訂)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **F4. 統計卡片系統 ✅**
|
||||
|
||||
#### **F4.1 四張卡片實現**
|
||||
**實現狀態**: 完全實現
|
||||
|
||||
**實際卡片結構**:
|
||||
```tsx
|
||||
<div className="grid grid-cols-2 sm:grid-cols-4 gap-3 sm:gap-4 mb-6">
|
||||
{/* 簡單詞彙卡片 */}
|
||||
<div className="bg-gray-50 border border-dashed border-gray-300 rounded-lg p-3 sm:p-4 text-center">
|
||||
<div className="text-xl sm:text-2xl font-bold text-gray-600 mb-1">{simpleCount}</div>
|
||||
<div className="text-gray-600 text-xs sm:text-sm font-medium">太簡單啦</div>
|
||||
</div>
|
||||
|
||||
{/* 適中詞彙卡片 */}
|
||||
<div className="bg-green-50 border border-green-200 rounded-lg p-3 sm:p-4 text-center">
|
||||
<div className="text-xl sm:text-2xl font-bold text-green-700 mb-1">{moderateCount}</div>
|
||||
<div className="text-green-700 text-xs sm:text-sm font-medium">重點學習</div>
|
||||
</div>
|
||||
|
||||
{/* 艱難詞彙卡片 */}
|
||||
<div className="bg-orange-50 border border-orange-200 rounded-lg p-3 sm:p-4 text-center">
|
||||
<div className="text-xl sm:text-2xl font-bold text-orange-700 mb-1">{difficultCount}</div>
|
||||
<div className="text-orange-700 text-xs sm:text-sm font-medium">有點挑戰</div>
|
||||
</div>
|
||||
|
||||
{/* 慣用語卡片 */}
|
||||
<div className="bg-blue-50 border border-blue-200 rounded-lg p-3 sm:p-4 text-center">
|
||||
<div className="text-xl sm:text-2xl font-bold text-blue-700 mb-1">{phraseCount}</div>
|
||||
<div className="text-blue-700 text-xs sm:text-sm font-medium">慣用語</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
#### **F4.2 動態計算實現**
|
||||
**實現狀態**: 使用useMemo優化
|
||||
|
||||
**性能優化**:
|
||||
```typescript
|
||||
const vocabularyStats = useMemo(() => {
|
||||
if (!sentenceAnalysis) return null
|
||||
|
||||
const userLevel = localStorage.getItem('userEnglishLevel') || 'A2'
|
||||
let simpleCount = 0, moderateCount = 0, difficultCount = 0, phraseCount = 0
|
||||
|
||||
Object.entries(sentenceAnalysis).forEach(([, wordData]) => {
|
||||
// 分類計算邏輯
|
||||
})
|
||||
|
||||
return { simpleCount, moderateCount, difficultCount, phraseCount }
|
||||
}, [sentenceAnalysis])
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### **F5. 慣用語展示系統 ✅**
|
||||
|
||||
#### **F5.1 獨立展示區域**
|
||||
**實現狀態**: 完全實現
|
||||
|
||||
**實際位置**: 中文翻譯區域下方
|
||||
**設計實現**:
|
||||
```tsx
|
||||
<div className="bg-gray-50 rounded-lg p-4 mt-4">
|
||||
<h3 className="font-semibold text-gray-900 mb-2 text-left">慣用語</h3>
|
||||
<div className="flex flex-wrap gap-2">
|
||||
{phrases.map((phrase, index) => (
|
||||
<span className="cursor-pointer transition-all duration-200 rounded relative mx-0.5 px-1 py-0.5 bg-blue-50 border border-blue-200 hover:bg-blue-100 text-blue-700 font-medium">
|
||||
{phrase.phrase}
|
||||
</span>
|
||||
))}
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
#### **F5.2 慣用語彈窗系統**
|
||||
**實現狀態**: 完全實現
|
||||
|
||||
**彈窗觸發**: 點擊慣用語標籤
|
||||
**彈窗內容**: 與詞彙彈窗相同的結構（標題、翻譯、定義、例句、保存按鈕）
|
||||
**位置計算**: 智能避免超出螢幕邊界
|
||||
|
||||
---
|
||||
|
||||
### **F6. 詞彙互動彈窗系統 ✅**
|
||||
|
||||
#### **F6.1 ClickableTextV2組件**
|
||||
**實現狀態**: 完全實現並優化
|
||||
|
||||
**核心特色**:
|
||||
- **React Portal**: 渲染到document.body避免CSS繼承
|
||||
- **智能定位**: 防止彈窗超出螢幕邊界
|
||||
- **響應式設計**: `w-80 sm:w-96 max-w-[90vw]`
|
||||
- **性能優化**: 使用useMemo和useCallback
|
||||
|
||||
#### **F6.2 彈窗內容結構**
|
||||
**實現狀態**: 完全實現
|
||||
|
||||
**實際結構**:
|
||||
1. **標題區**: 漸層藍色背景，詞彙名稱、詞性、發音、CEFR等級
|
||||
2. **翻譯區**: 綠色區塊 `bg-green-50 border-green-200`
|
||||
3. **定義區**: 灰色區塊 `bg-gray-50 border-gray-200`
|
||||
4. **例句區**: 藍色區塊 `bg-blue-50 border-blue-200`（條件顯示）
|
||||
5. **保存按鈕**: `bg-primary text-white` 全寬按鈕
|
||||
|
||||
---
|
||||
|
||||
## 🎨 **實際UI實現規格**
|
||||
|
||||
### **UI1. 整體佈局**
|
||||
|
||||
#### **UI1.1 頁面結構**
|
||||
```tsx
|
||||
<div className="min-h-screen bg-gray-50">
|
||||
<Navigation />
|
||||
<div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-8">
|
||||
{!showAnalysisView ? (
|
||||
// 輸入模式
|
||||
<div className="max-w-4xl mx-auto">
|
||||
<h1 className="text-3xl font-bold mb-8">AI 智能生成詞卡</h1>
|
||||
{/* 輸入區域 */}
|
||||
</div>
|
||||
) : (
|
||||
// 分析結果模式
|
||||
<div className="max-w-4xl mx-auto">
|
||||
{/* 語法修正面板 */}
|
||||
{/* 詞彙統計卡片 */}
|
||||
{/* 例句展示 */}
|
||||
{/* 翻譯區域 */}
|
||||
{/* 慣用語展示 */}
|
||||
</div>
|
||||
)}
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
#### **UI1.2 配色系統實現**
|
||||
**實際使用的顏色**:
|
||||
- **簡單詞彙**: `bg-gray-50 border-gray-300 text-gray-600`
|
||||
- **適中詞彙**: `bg-green-50 border-green-200 text-green-700`
|
||||
- **艱難詞彙**: `bg-orange-50 border-orange-200 text-orange-700`
|
||||
- **慣用語**: `bg-blue-50 border-blue-200 text-blue-700`
|
||||
|
||||
---
|
||||
|
||||
## ⚡ **性能優化實現**
|
||||
|
||||
### **P1. React性能優化**
|
||||
|
||||
#### **P1.1 記憶化實現**
|
||||
**狀態**: 已實現
|
||||
|
||||
```typescript
|
||||
// 詞彙統計計算優化
|
||||
const vocabularyStats = useMemo(() => {
|
||||
// 計算邏輯...
|
||||
}, [sentenceAnalysis])
|
||||
|
||||
// 事件處理優化
|
||||
const handleAnalyzeSentence = useCallback(async () => {
|
||||
// 分析邏輯...
|
||||
}, [textInput])
|
||||
|
||||
const handleAcceptCorrection = useCallback(() => {
|
||||
// 修正處理...
|
||||
}, [grammarCorrection?.correctedText])
|
||||
|
||||
const handleRejectCorrection = useCallback(() => {
|
||||
// 拒絕處理...
|
||||
}, [grammarCorrection?.originalText, textInput])
|
||||
|
||||
const handleSaveWord = useCallback(async (word: string, analysis: any) => {
|
||||
// 保存邏輯...
|
||||
}, [])
|
||||
```
|
||||
|
||||
#### **P1.2 組件優化**
|
||||
**ClickableTextV2優化**:
|
||||
```typescript
|
||||
// 工具函數記憶化
|
||||
const getCEFRColor = useCallback((level: string) => { /* ... */ }, [])
|
||||
const getWordProperty = useCallback((wordData: any, propName: string) => { /* ... */ }, [])
|
||||
const findWordAnalysis = useCallback((word: string) => { /* ... */ }, [analysis])
|
||||
|
||||
// 文字分割優化
|
||||
const words = useMemo(() => text.split(/(\s+|[.,!?;:])/g), [text])
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📱 **響應式設計實現**
|
||||
|
||||
### **R1. 實際斷點實現**
|
||||
|
||||
#### **R1.1 統計卡片響應式**
|
||||
```css
|
||||
/* 移動設備: 2列 */
|
||||
grid-cols-2
|
||||
|
||||
/* 桌面設備: 4列 */
|
||||
sm:grid-cols-4
|
||||
|
||||
/* 間距調整 */
|
||||
gap-3 sm:gap-4
|
||||
p-3 sm:p-4
|
||||
```
|
||||
|
||||
#### **R1.2 字體響應式**
|
||||
```css
|
||||
/* 統計數字 */
|
||||
text-xl sm:text-2xl
|
||||
|
||||
/* 例句文字 */
|
||||
text-xl sm:text-2xl lg:text-3xl
|
||||
|
||||
/* 卡片標籤 */
|
||||
text-xs sm:text-sm
|
||||
```
|
||||
|
||||
#### **R1.3 彈窗響應式**
|
||||
```css
|
||||
/* 彈窗寬度 */
|
||||
w-80 sm:w-96 max-w-[90vw]
|
||||
|
||||
/* 最大高度 */
|
||||
max-height: 85vh
|
||||
overflow-y: auto
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💾 **實際數據結構**
|
||||
|
||||
### **D1. 狀態管理實現**
|
||||
|
||||
#### **D1.1 組件狀態**
|
||||
```typescript
|
||||
const [textInput, setTextInput] = useState('')
|
||||
const [isAnalyzing, setIsAnalyzing] = useState(false)
|
||||
const [showAnalysisView, setShowAnalysisView] = useState(false)
|
||||
const [sentenceAnalysis, setSentenceAnalysis] = useState<Record<string, any> | null>(null)
|
||||
const [sentenceMeaning, setSentenceMeaning] = useState('')
|
||||
const [grammarCorrection, setGrammarCorrection] = useState<GrammarCorrection | null>(null)
|
||||
const [finalText, setFinalText] = useState('')
|
||||
const [phrasePopup, setPhrasePopup] = useState<PhrasePopup | null>(null)
|
||||
```
|
||||
|
||||
#### **D1.2 測試數據結構**
|
||||
**完整的假資料實現**:
|
||||
```typescript
|
||||
const mockAnalysis = {
|
||||
"she": {
|
||||
word: "she",
|
||||
translation: "她",
|
||||
definition: "female person pronoun",
|
||||
partOfSpeech: "pronoun",
|
||||
pronunciation: "/ʃiː/",
|
||||
difficultyLevel: "A1",
|
||||
isPhrase: false,
|
||||
// ...完整欄位
|
||||
},
|
||||
"cut someone some slack": {
|
||||
word: "cut someone some slack",
|
||||
translation: "對某人寬容一點",
|
||||
definition: "to be more lenient or forgiving with someone",
|
||||
partOfSpeech: "idiom",
|
||||
difficultyLevel: "B2",
|
||||
isPhrase: true,
|
||||
// ...完整欄位
|
||||
}
|
||||
// ...包含句子中所有詞彙
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎪 **實際互動實現**
|
||||
|
||||
### **I1. 詞彙點擊處理**
|
||||
|
||||
#### **I1.1 點擊事件實現**
|
||||
```typescript
|
||||
const handleWordClick = useCallback(async (word: string, event: React.MouseEvent) => {
|
||||
const cleanWord = word.toLowerCase().replace(/[.,!?;:]/g, '')
|
||||
const wordAnalysis = findWordAnalysis(word)
|
||||
|
||||
if (!wordAnalysis) return
|
||||
|
||||
// 計算彈窗位置
|
||||
const rect = event.currentTarget.getBoundingClientRect()
|
||||
const position = {
|
||||
x: rect.left + rect.width / 2,
|
||||
y: rect.bottom + 10,
|
||||
showBelow: true
|
||||
}
|
||||
|
||||
setPopupPosition(position)
|
||||
setSelectedWord(cleanWord)
|
||||
onWordClick?.(cleanWord, wordAnalysis)
|
||||
}, [findWordAnalysis, onWordClick])
|
||||
```
|
||||
|
||||
### **I2. 慣用語點擊處理**
|
||||
|
||||
#### **I2.1 慣用語彈窗觸發**
|
||||
```typescript
|
||||
const handlePhraseClick = (e: React.MouseEvent) => {
|
||||
const phraseAnalysis = sentenceAnalysis?.["cut someone some slack"]
|
||||
|
||||
setPhrasePopup({
|
||||
phrase: phrase.phrase,
|
||||
analysis: phraseAnalysis,
|
||||
position: {
|
||||
x: e.currentTarget.getBoundingClientRect().left + e.currentTarget.getBoundingClientRect().width / 2,
|
||||
y: e.currentTarget.getBoundingClientRect().bottom + 10
|
||||
}
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 **實際測試數據**
|
||||
|
||||
### **T1. 測試句子**
|
||||
|
||||
#### **T1.1 語法錯誤測試**
|
||||
**輸入**: "She just join the team, so let's cut her some slack until she get used to the workflow."
|
||||
|
||||
**語法錯誤**:
|
||||
- `join` → `joined` (時態錯誤)
|
||||
- `get` → `gets` (第三人稱單數錯誤)
|
||||
|
||||
#### **T1.2 詞彙分類測試**（用戶A2等級）
|
||||
**預期統計結果**:
|
||||
- **太簡單啦**: 8個 (she, the, so, let's, her, some, to等)
|
||||
- **重點學習**: 4個 (just, team, until, used等)
|
||||
- **有點挑戰**: 3個 (join, slack, workflow等)
|
||||
- **慣用語**: 1個 (cut someone some slack)
|
||||
|
||||
---
|
||||
|
||||
## 🚫 **未實現的規格功能**
|
||||
|
||||
### **NI1. 輸入模式選擇**
|
||||
**規格要求**: 手動輸入 vs 影劇截圖
|
||||
**實現狀態**: UI存在但功能未啟用
|
||||
**代碼狀態**:
|
||||
```typescript
|
||||
const [mode, setMode] = useState<'manual' | 'screenshot'>('manual') // 未使用
|
||||
```
|
||||
|
||||
### **NI2. 使用限制系統**
|
||||
**規格要求**: 免費用戶5次/3小時限制
|
||||
**實現狀態**: 硬編碼為無限制
|
||||
**代碼狀態**:
|
||||
```typescript
|
||||
const [usageCount] = useState(0) // 固定0
|
||||
const [isPremium] = useState(true) // 固定true
|
||||
```
|
||||
|
||||
### **NI3. 學習提示系統**
|
||||
**規格要求**: 頁面底部詞彙樣式說明
|
||||
**實現狀態**: 已被移除
|
||||
|
||||
---
|
||||
|
||||
## 🔧 **技術債務**
|
||||
|
||||
### **TD1. 未使用的代碼**
|
||||
|
||||
#### **TD1.1 需清理的變數**
|
||||
```typescript
|
||||
const [mode, setMode] = useState<'manual' | 'screenshot'>('manual') // 未使用setMode
|
||||
const [isPremium] = useState(true) // 未使用isPremium
|
||||
```
|
||||
|
||||
#### **TD1.2 未實現的功能UI**
|
||||
- 輸入模式選擇按鈕（存在但無功能）
|
||||
- 使用次數顯示（顯示但不準確）
|
||||
|
||||
---
|
||||
|
||||
## 📊 **實際性能指標**
|
||||
|
||||
### **P1. 已達成的性能**
|
||||
- **初始載入**: < 2秒 ✅
|
||||
- **詞彙標記渲染**: < 100ms ✅
|
||||
- **統計卡片更新**: < 50ms ✅
|
||||
- **彈窗開啟**: < 200ms ✅
|
||||
- **記憶體使用**: 穩定無洩漏 ✅
|
||||
|
||||
### **P2. 代碼品質**
|
||||
- **TypeScript錯誤**: 0個 ✅
|
||||
- **React錯誤**: 0個 ✅
|
||||
- **性能優化**: useMemo/useCallback ✅
|
||||
- **響應式設計**: 完整實現 ✅
|
||||
|
||||
---
|
||||
|
||||
## 🎯 **實際用戶體驗**
|
||||
|
||||
### **UX1. 核心流程**
|
||||
1. **輸入文本** ✅ → 300字符限制，即時反饋
|
||||
2. **觸發分析** ✅ → 1秒模擬延遲，載入動畫
|
||||
3. **查看語法修正** ✅ → 清晰的錯誤對比
|
||||
4. **查看統計** ✅ → 四張卡片直觀展示
|
||||
5. **學習詞彙** ✅ → 點擊查看詳細資訊
|
||||
6. **學習慣用語** ✅ → 專門區域展示
|
||||
7. **保存學習** ✅ → 一鍵保存到詞卡
|
||||
|
||||
### **UX2. 互動體驗**
|
||||
- **點擊響應**: 即時反饋 ✅
|
||||
- **視覺引導**: 清晰的顏色區分 ✅
|
||||
- **錯誤處理**: 友善的錯誤訊息 ✅
|
||||
- **學習連續性**: 流暢的操作流程 ✅
|
||||
|
||||
---
|
||||
|
||||
## ✅ **實際驗收檢查表**
|
||||
|
||||
### **功能驗收** (已完成)
|
||||
- [x] 文本輸入和字符限制正常運作
|
||||
- [x] AI分析請求和回應處理正確（假資料）
|
||||
- [x] 語法修正建議正確顯示和處理
|
||||
- [x] 詞彙標記分類準確無誤
|
||||
- [x] 統計卡片數字與實際標記一致
|
||||
- [x] 慣用語識別和展示功能完整
|
||||
- [x] 詞彙和慣用語彈窗互動正常
|
||||
- [x] 保存詞卡功能運作正常
|
||||
|
||||
### **技術驗收** (已完成)
|
||||
- [x] TypeScript類型檢查零錯誤
|
||||
- [x] React性能優化到位
|
||||
- [x] 響應式設計完整
|
||||
- [x] 代碼結構清晰
|
||||
|
||||
---
|
||||
|
||||
## 🔮 **後續優化建議**
|
||||
|
||||
### **短期 (1週內)**
|
||||
1. **啟用真實API**: 將假資料模式切換為真實API調用
|
||||
2. **清理無用代碼**: 移除mode選擇等未使用功能
|
||||
3. **完善錯誤處理**: 改善API失敗時的用戶提示
|
||||
|
||||
### **中期 (1個月內)**
|
||||
1. **實現使用限制**: 添加真實的次數限制功能
|
||||
2. **改善輸入體驗**: 優化textarea的可用性
|
||||
3. **添加學習提示**: 恢復詞彙樣式說明功能
|
||||
|
||||
---
|
||||
|
||||
**文件版本**: v1.0 (實際實現版)
|
||||
**對應前端**: /app/generate/page.tsx + /components/ClickableTextV2.tsx
|
||||
**最後更新**: 2025-09-22
|
||||
|
|
@ -1,740 +0,0 @@
|
|||
# AI生成網頁前端實際技術規格
|
||||
|
||||
## 📋 **文件資訊**
|
||||
|
||||
- **文件名稱**: AI生成網頁前端實際技術規格
|
||||
- **版本**: v1.0 (基於實際實現)
|
||||
- **建立日期**: 2025-09-22
|
||||
- **最後更新**: 2025-09-22
|
||||
- **對應代碼**: /app/generate/page.tsx + /components/ClickableTextV2.tsx
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ **實際技術架構**
|
||||
|
||||
### **A1. 技術棧組成**
|
||||
|
||||
#### **A1.1 實際使用的技術**
|
||||
```json
|
||||
{
|
||||
"framework": "Next.js 15.5.3",
|
||||
"language": "TypeScript",
|
||||
"styling": "Tailwind CSS",
|
||||
"stateManagement": "React Hooks (useState, useMemo, useCallback)",
|
||||
"api": "Fetch API (目前使用假資料)",
|
||||
"routing": "Next.js App Router",
|
||||
"authentication": "ProtectedRoute組件"
|
||||
}
|
||||
```
|
||||
|
||||
#### **A1.2 實際組件結構**
|
||||
```
|
||||
GeneratePage (路由保護)
|
||||
└── GenerateContent (主邏輯組件)
|
||||
├── 輸入模式 (!showAnalysisView)
|
||||
│ ├── 頁面標題
|
||||
│ ├── 文本輸入區域 (textarea + 字符計數)
|
||||
│ ├── 分析按鈕 (載入狀態處理)
|
||||
│ └── 個人化程度指示器
|
||||
└── 分析結果模式 (showAnalysisView)
|
||||
├── 語法修正面板 (條件顯示)
|
||||
├── 詞彙統計卡片區 (4張卡片)
|
||||
├── ClickableTextV2 (例句展示)
|
||||
├── 翻譯區域 (灰色背景)
|
||||
├── 慣用語展示區域
|
||||
├── 慣用語彈窗 (Portal渲染)
|
||||
└── 返回按鈕
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💾 **實際數據架構**
|
||||
|
||||
### **D1. 類型定義實現**
|
||||
|
||||
#### **D1.1 語法修正類型**
|
||||
```typescript
|
||||
interface GrammarCorrection {
|
||||
hasErrors: boolean;
|
||||
originalText: string;
|
||||
correctedText: string;
|
||||
corrections: Array<{
|
||||
error: string;
|
||||
correction: string;
|
||||
type: string;
|
||||
explanation: string;
|
||||
}>;
|
||||
}
|
||||
```
|
||||
|
||||
#### **D1.2 慣用語彈窗類型**
|
||||
```typescript
|
||||
interface PhrasePopup {
|
||||
phrase: string;
|
||||
analysis: any;
|
||||
position: {
|
||||
x: number;
|
||||
y: number;
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
#### **D1.3 實際WordAnalysis結構**
|
||||
```typescript
|
||||
// 實際測試數據中的結構
|
||||
interface MockWordAnalysis {
|
||||
word: string;
|
||||
translation: string;
|
||||
definition: string;
|
||||
partOfSpeech: string;
|
||||
pronunciation: string;
|
||||
difficultyLevel: string;
|
||||
isPhrase: boolean;
|
||||
synonyms: string[];
|
||||
example: string;
|
||||
exampleTranslation: string;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚡ **實際性能優化實現**
|
||||
|
||||
### **P1. React Hooks優化**
|
||||
|
||||
#### **P1.1 記憶化函數**
|
||||
```typescript
|
||||
// 統計計算優化
|
||||
const vocabularyStats = useMemo(() => {
|
||||
if (!sentenceAnalysis) return null
|
||||
|
||||
const userLevel = localStorage.getItem('userEnglishLevel') || 'A2'
|
||||
// 計算邏輯...
|
||||
|
||||
return { simpleCount, moderateCount, difficultCount, phraseCount }
|
||||
}, [sentenceAnalysis])
|
||||
|
||||
// 事件處理優化
|
||||
const handleAnalyzeSentence = useCallback(async () => {
|
||||
setIsAnalyzing(true)
|
||||
|
||||
try {
|
||||
await new Promise(resolve => setTimeout(resolve, 1000)) // 模擬延遲
|
||||
// 設置假資料...
|
||||
setShowAnalysisView(true)
|
||||
} finally {
|
||||
setIsAnalyzing(false)
|
||||
}
|
||||
}, [])
|
||||
|
||||
const handleSaveWord = useCallback(async (word: string, analysis: any) => {
|
||||
try {
|
||||
const cardData = {
|
||||
word: word,
|
||||
translation: analysis.translation || '',
|
||||
definition: analysis.definition || '',
|
||||
pronunciation: analysis.pronunciation || `/${word}/`,
|
||||
partOfSpeech: analysis.partOfSpeech || 'unknown',
|
||||
example: `Example sentence with ${word}.`
|
||||
}
|
||||
|
||||
const response = await flashcardsService.createFlashcard(cardData)
|
||||
if (response.success) {
|
||||
alert(`✅ 已將「${word}」保存到詞卡！`)
|
||||
}
|
||||
} catch (error) {
|
||||
console.error('Save word error:', error)
|
||||
throw error
|
||||
}
|
||||
}, [])
|
||||
```
|
||||
|
||||
#### **P1.2 ClickableTextV2性能優化**
|
||||
```typescript
|
||||
// 工具函數記憶化
|
||||
const getCEFRColor = useCallback((level: string) => {
|
||||
switch (level) {
|
||||
case 'A1': return 'bg-green-100 text-green-700 border-green-200'
|
||||
case 'A2': return 'bg-blue-100 text-blue-700 border-blue-200'
|
||||
// ...其他等級
|
||||
default: return 'bg-gray-100 text-gray-700 border-gray-200'
|
||||
}
|
||||
}, [])
|
||||
|
||||
const findWordAnalysis = useCallback((word: string) => {
|
||||
const cleanWord = word.toLowerCase().replace(/[.,!?;:]/g, '')
|
||||
return analysis?.[cleanWord] || analysis?.[word] || analysis?.[word.toLowerCase()] || null
|
||||
}, [analysis])
|
||||
|
||||
// 文字分割優化
|
||||
const words = useMemo(() => text.split(/(\s+|[.,!?;:])/g), [text])
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎨 **實際樣式系統**
|
||||
|
||||
### **S1. 實現的設計Token**
|
||||
|
||||
#### **S1.1 實際使用的顏色**
|
||||
```css
|
||||
/* 詞彙分類顏色 - 實際實現 */
|
||||
.simple-word {
|
||||
background: #f9fafb; /* bg-gray-50 */
|
||||
border: #d1d5db; /* border-gray-300 */
|
||||
color: #6b7280; /* text-gray-600 */
|
||||
border-style: dashed;
|
||||
opacity: 0.8;
|
||||
}
|
||||
|
||||
.moderate-word {
|
||||
background: #f0fdf4; /* bg-green-50 */
|
||||
border: #bbf7d0; /* border-green-200 */
|
||||
color: #15803d; /* text-green-700 */
|
||||
font-weight: 500; /* font-medium */
|
||||
}
|
||||
|
||||
.difficult-word {
|
||||
background: #fff7ed; /* bg-orange-50 */
|
||||
border: #fed7aa; /* border-orange-200 */
|
||||
color: #c2410c; /* text-orange-700 */
|
||||
font-weight: 500; /* font-medium */
|
||||
}
|
||||
|
||||
.phrase-word {
|
||||
background: #eff6ff; /* bg-blue-50 */
|
||||
border: #bfdbfe; /* border-blue-200 */
|
||||
color: #1d4ed8; /* text-blue-700 */
|
||||
font-weight: 500; /* font-medium */
|
||||
}
|
||||
```
|
||||
|
||||
#### **S1.2 基礎樣式類別**
|
||||
```css
|
||||
/* 實際基礎樣式 */
|
||||
.word-base {
|
||||
cursor: pointer;
|
||||
transition: all 0.2s ease;
|
||||
border-radius: 0.25rem; /* rounded */
|
||||
position: relative;
|
||||
margin: 0 0.125rem; /* mx-0.5 */
|
||||
padding: 0.125rem 0.25rem; /* px-1 py-0.5 */
|
||||
}
|
||||
|
||||
/* 文字容器 */
|
||||
.text-container {
|
||||
font-size: 1.25rem; /* text-lg */
|
||||
line-height: 2.5; /* 自訂行高 */
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔌 **實際API整合**
|
||||
|
||||
### **API1. 當前實現狀態**
|
||||
|
||||
#### **API1.1 假資料模式**
|
||||
```typescript
|
||||
// 當前使用的測試數據生成
|
||||
const handleAnalyzeSentence = async () => {
|
||||
console.log('🚀 handleAnalyzeSentence 被調用 (假資料模式)')
|
||||
|
||||
setIsAnalyzing(true)
|
||||
|
||||
try {
|
||||
// 模擬API延遲
|
||||
await new Promise(resolve => setTimeout(resolve, 1000))
|
||||
|
||||
const testSentence = "She just join the team, so let's cut her some slack until she get used to the workflow."
|
||||
|
||||
// 完整的假資料設置...
|
||||
setSentenceAnalysis(mockAnalysis)
|
||||
setSentenceMeaning("她剛加入團隊，所以讓我們對她寬容一點，直到她習慣工作流程。")
|
||||
setGrammarCorrection({
|
||||
hasErrors: true,
|
||||
originalText: testSentence,
|
||||
correctedText: correctedSentence,
|
||||
corrections: [/* 修正詳情 */]
|
||||
})
|
||||
setShowAnalysisView(true)
|
||||
} finally {
|
||||
setIsAnalyzing(false)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### **API1.2 真實API準備**
|
||||
**預留的API結構**:
|
||||
```typescript
|
||||
// 註解中的真實API調用代碼
|
||||
const response = await fetch('http://localhost:5000/api/ai/analyze-sentence', {
|
||||
method: 'POST',
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'Authorization': `Bearer ${localStorage.getItem('auth_token')}`
|
||||
},
|
||||
body: JSON.stringify({
|
||||
inputText: textInput,
|
||||
userLevel: userLevel,
|
||||
analysisMode: 'full'
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 **實際算法實現**
|
||||
|
||||
### **A1. 詞彙分類算法**
|
||||
|
||||
#### **A1.1 CEFR等級比較實現**
|
||||
```typescript
|
||||
const CEFR_LEVELS = ['A1', 'A2', 'B1', 'B2', 'C1', 'C2'] as const
|
||||
|
||||
const getLevelIndex = (level: string): number => {
|
||||
return CEFR_LEVELS.indexOf(level as typeof CEFR_LEVELS[number])
|
||||
}
|
||||
|
||||
// ClickableTextV2中的實際分類邏輯
|
||||
const getWordClass = (word: string) => {
|
||||
const wordAnalysis = findWordAnalysis(word)
|
||||
const baseClass = "cursor-pointer transition-all duration-200 rounded relative mx-0.5 px-1 py-0.5"
|
||||
|
||||
if (wordAnalysis) {
|
||||
const isPhrase = getWordProperty(wordAnalysis, 'isPhrase')
|
||||
const difficultyLevel = getWordProperty(wordAnalysis, 'difficultyLevel') || 'A1'
|
||||
const userLevel = typeof window !== 'undefined' ? localStorage.getItem('userEnglishLevel') || 'A2' : 'A2'
|
||||
|
||||
if (isPhrase) {
|
||||
return "" // 慣用語：純黑字
|
||||
}
|
||||
|
||||
const userIndex = getLevelIndex(userLevel)
|
||||
const wordIndex = getLevelIndex(difficultyLevel)
|
||||
|
||||
if (userIndex > wordIndex) {
|
||||
return `${baseClass} bg-gray-50 border border-dashed border-gray-300 hover:bg-gray-100 hover:border-gray-400 text-gray-600 opacity-80`
|
||||
} else if (userIndex === wordIndex) {
|
||||
return `${baseClass} bg-green-50 border border-green-200 hover:bg-green-100 hover:shadow-lg transform hover:-translate-y-0.5 text-green-700 font-medium`
|
||||
} else {
|
||||
return `${baseClass} bg-orange-50 border border-orange-200 hover:bg-orange-100 hover:shadow-lg transform hover:-translate-y-0.5 text-orange-700 font-medium`
|
||||
}
|
||||
} else {
|
||||
return "" // 無資料：純黑字
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### **A1.2 統計計算算法實現**
|
||||
```typescript
|
||||
// 實際的統計計算邏輯
|
||||
Object.entries(sentenceAnalysis).forEach(([, wordData]: [string, any]) => {
|
||||
const isPhrase = wordData?.isPhrase || wordData?.IsPhrase
|
||||
const difficultyLevel = wordData?.difficultyLevel || 'A1'
|
||||
|
||||
if (isPhrase) {
|
||||
phraseCount++
|
||||
} else {
|
||||
const userIndex = getLevelIndex(userLevel)
|
||||
const wordIndex = getLevelIndex(difficultyLevel)
|
||||
|
||||
if (userIndex > wordIndex) {
|
||||
simpleCount++
|
||||
} else if (userIndex === wordIndex) {
|
||||
moderateCount++
|
||||
} else {
|
||||
difficultCount++
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎪 **實際互動系統實現**
|
||||
|
||||
### **I1. Portal彈窗系統**
|
||||
|
||||
#### **I1.1 React Portal實現**
|
||||
```typescript
|
||||
// ClickableTextV2中的實際Portal實現
|
||||
const VocabPopup = () => {
|
||||
if (!selectedWord || !analysis?.[selectedWord] || !mounted) return null
|
||||
|
||||
return createPortal(
|
||||
<>
|
||||
{/* 背景遮罩 */}
|
||||
<div
|
||||
className="fixed inset-0 bg-black bg-opacity-50 z-40"
|
||||
onClick={closePopup}
|
||||
/>
|
||||
|
||||
{/* 彈窗內容 */}
|
||||
<div
|
||||
className="fixed z-50 bg-white rounded-xl shadow-lg w-80 sm:w-96 max-w-[90vw] overflow-hidden"
|
||||
style={{
|
||||
left: `${popupPosition.x}px`,
|
||||
top: `${popupPosition.y}px`,
|
||||
transform: 'translate(-50%, 8px)',
|
||||
maxHeight: '85vh',
|
||||
overflowY: 'auto'
|
||||
}}
|
||||
>
|
||||
{/* 彈窗結構 */}
|
||||
</div>
|
||||
</>,
|
||||
document.body
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
#### **I1.2 位置計算實現**
|
||||
```typescript
|
||||
const handleWordClick = async (word: string, event: React.MouseEvent) => {
|
||||
const rect = event.currentTarget.getBoundingClientRect()
|
||||
const position = {
|
||||
x: rect.left + rect.width / 2,
|
||||
y: rect.bottom + 10,
|
||||
showBelow: true
|
||||
}
|
||||
|
||||
setPopupPosition(position)
|
||||
setSelectedWord(cleanWord)
|
||||
onWordClick?.(cleanWord, wordAnalysis)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 **實際狀態管理**
|
||||
|
||||
### **ST1. 狀態架構實現**
|
||||
|
||||
#### **ST1.1 主要狀態**
|
||||
```typescript
|
||||
// 實際的狀態定義
|
||||
const [textInput, setTextInput] = useState('')
|
||||
const [isAnalyzing, setIsAnalyzing] = useState(false)
|
||||
const [showAnalysisView, setShowAnalysisView] = useState(false)
|
||||
const [sentenceAnalysis, setSentenceAnalysis] = useState<Record<string, any> | null>(null)
|
||||
const [sentenceMeaning, setSentenceMeaning] = useState('')
|
||||
const [grammarCorrection, setGrammarCorrection] = useState<GrammarCorrection | null>(null)
|
||||
const [finalText, setFinalText] = useState('')
|
||||
const [phrasePopup, setPhrasePopup] = useState<PhrasePopup | null>(null)
|
||||
|
||||
// 未使用但存在的狀態
|
||||
const [mode, setMode] = useState<'manual' | 'screenshot'>('manual') // 未使用
|
||||
const [usageCount] = useState(0) // 固定值
|
||||
const [isPremium] = useState(true) // 固定值
|
||||
```
|
||||
|
||||
#### **ST1.2 狀態更新流程**
|
||||
```typescript
|
||||
// 實際的分析完成處理
|
||||
const setAnalysisResults = () => {
|
||||
setFinalText(correctedSentence)
|
||||
setSentenceAnalysis(mockAnalysis)
|
||||
setSentenceMeaning(translatedText)
|
||||
setGrammarCorrection(correctionData)
|
||||
setShowAnalysisView(true)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔍 **實際測試數據架構**
|
||||
|
||||
### **TD1. 完整測試數據**
|
||||
|
||||
#### **TD1.1 語法錯誤測試**
|
||||
```typescript
|
||||
// 實際的測試句子
|
||||
const originalSentence = "She just join the team, so let's cut her some slack until she get used to the workflow."
|
||||
const correctedSentence = "She just joined the team, so let's cut her some slack until she gets used to the workflow."
|
||||
|
||||
// 實際的語法修正數據
|
||||
const grammarCorrection = {
|
||||
hasErrors: true,
|
||||
originalText: originalSentence,
|
||||
correctedText: correctedSentence,
|
||||
corrections: [
|
||||
{
|
||||
error: "join",
|
||||
correction: "joined",
|
||||
type: "時態錯誤",
|
||||
explanation: "第三人稱單數過去式應使用 'joined'"
|
||||
},
|
||||
{
|
||||
error: "get",
|
||||
correction: "gets",
|
||||
type: "時態錯誤",
|
||||
explanation: "第三人稱單數現在式應使用 'gets'"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### **TD1.2 詞彙分析測試數據**
|
||||
```typescript
|
||||
// 實際包含的詞彙（16個詞彙 + 1個慣用語）
|
||||
const mockAnalysis = {
|
||||
"she": { word: "she", difficultyLevel: "A1", isPhrase: false, /* ... */ },
|
||||
"just": { word: "just", difficultyLevel: "A2", isPhrase: false, /* ... */ },
|
||||
"joined": { word: "joined", difficultyLevel: "B1", isPhrase: false, /* ... */ },
|
||||
"the": { word: "the", difficultyLevel: "A1", isPhrase: false, /* ... */ },
|
||||
"team": { word: "team", difficultyLevel: "A2", isPhrase: false, /* ... */ },
|
||||
"so": { word: "so", difficultyLevel: "A1", isPhrase: false, /* ... */ },
|
||||
"let's": { word: "let's", difficultyLevel: "A1", isPhrase: false, /* ... */ },
|
||||
"cut": { word: "cut", difficultyLevel: "A2", isPhrase: false, /* ... */ },
|
||||
"her": { word: "her", difficultyLevel: "A1", isPhrase: false, /* ... */ },
|
||||
"some": { word: "some", difficultyLevel: "A1", isPhrase: false, /* ... */ },
|
||||
"slack": { word: "slack", difficultyLevel: "B1", isPhrase: false, /* ... */ },
|
||||
"until": { word: "until", difficultyLevel: "A2", isPhrase: false, /* ... */ },
|
||||
"gets": { word: "gets", difficultyLevel: "A1", isPhrase: false, /* ... */ },
|
||||
"used": { word: "used", difficultyLevel: "A2", isPhrase: false, /* ... */ },
|
||||
"to": { word: "to", difficultyLevel: "A1", isPhrase: false, /* ... */ },
|
||||
"workflow": { word: "workflow", difficultyLevel: "B2", isPhrase: false, /* ... */ },
|
||||
"cut someone some slack": {
|
||||
word: "cut someone some slack",
|
||||
difficultyLevel: "B2",
|
||||
isPhrase: true,
|
||||
translation: "對某人寬容一點",
|
||||
/* ... */
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### **TD1.3 預期統計結果（A2用戶）**
|
||||
```typescript
|
||||
// 實際計算結果
|
||||
const expectedStats = {
|
||||
simpleCount: 8, // A1等級詞彙：she, the, so, let's, her, some, gets, to
|
||||
moderateCount: 4, // A2等級詞彙：just, team, cut, until, used
|
||||
difficultCount: 3, // >A2等級詞彙：joined(B1), slack(B1), workflow(B2)
|
||||
phraseCount: 1 // 慣用語：cut someone some slack
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎨 **實際UI組件實現**
|
||||
|
||||
### **UI1. 統計卡片組件**
|
||||
|
||||
#### **UI1.1 實際卡片實現**
|
||||
```tsx
|
||||
// 實際的統計卡片結構
|
||||
const StatisticsCards = ({ vocabularyStats }: { vocabularyStats: VocabularyStats }) => (
|
||||
<div className="grid grid-cols-2 sm:grid-cols-4 gap-3 sm:gap-4 mb-6">
|
||||
{/* 簡單詞彙卡片 */}
|
||||
<div className="bg-gray-50 border border-dashed border-gray-300 rounded-lg p-3 sm:p-4 text-center">
|
||||
<div className="text-xl sm:text-2xl font-bold text-gray-600 mb-1">
|
||||
{vocabularyStats.simpleCount}
|
||||
</div>
|
||||
<div className="text-gray-600 text-xs sm:text-sm font-medium">太簡單啦</div>
|
||||
</div>
|
||||
|
||||
{/* 適中詞彙卡片 */}
|
||||
<div className="bg-green-50 border border-green-200 rounded-lg p-3 sm:p-4 text-center">
|
||||
<div className="text-xl sm:text-2xl font-bold text-green-700 mb-1">
|
||||
{vocabularyStats.moderateCount}
|
||||
</div>
|
||||
<div className="text-green-700 text-xs sm:text-sm font-medium">重點學習</div>
|
||||
</div>
|
||||
|
||||
{/* 艱難詞彙卡片 */}
|
||||
<div className="bg-orange-50 border border-orange-200 rounded-lg p-3 sm:p-4 text-center">
|
||||
<div className="text-xl sm:text-2xl font-bold text-orange-700 mb-1">
|
||||
{vocabularyStats.difficultCount}
|
||||
</div>
|
||||
<div className="text-orange-700 text-xs sm:text-sm font-medium">有點挑戰</div>
|
||||
</div>
|
||||
|
||||
{/* 慣用語卡片 */}
|
||||
<div className="bg-blue-50 border border-blue-200 rounded-lg p-3 sm:p-4 text-center">
|
||||
<div className="text-xl sm:text-2xl font-bold text-blue-700 mb-1">
|
||||
{vocabularyStats.phraseCount}
|
||||
</div>
|
||||
<div className="text-blue-700 text-xs sm:text-sm font-medium">慣用語</div>
|
||||
</div>
|
||||
</div>
|
||||
)
|
||||
```
|
||||
|
||||
### **UI2. 慣用語展示組件**
|
||||
|
||||
#### **UI2.1 實際展示區域**
|
||||
```tsx
|
||||
// 實際的慣用語展示實現
|
||||
<div className="bg-gray-50 rounded-lg p-4 mt-4">
|
||||
<h3 className="font-semibold text-gray-900 mb-2 text-left">慣用語</h3>
|
||||
<div className="flex flex-wrap gap-2">
|
||||
{phrases.map((phrase, index) => (
|
||||
<span
|
||||
key={index}
|
||||
className="cursor-pointer transition-all duration-200 rounded relative mx-0.5 px-1 py-0.5 bg-blue-50 border border-blue-200 hover:bg-blue-100 hover:shadow-lg transform hover:-translate-y-0.5 text-blue-700 font-medium"
|
||||
onClick={handlePhraseClick}
|
||||
title={`${phrase.phrase}: ${phrase.meaning}`}
|
||||
>
|
||||
{phrase.phrase}
|
||||
</span>
|
||||
))}
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📱 **實際響應式實現**
|
||||
|
||||
### **R1. 斷點實現**
|
||||
|
||||
#### **R1.1 實際使用的斷點**
|
||||
```css
|
||||
/* 實際實現的響應式類別 */
|
||||
.responsive-grid {
|
||||
grid-template-columns: repeat(2, 1fr); /* 預設：移動 */
|
||||
}
|
||||
|
||||
@media (min-width: 640px) {
|
||||
.responsive-grid {
|
||||
grid-template-columns: repeat(4, 1fr); /* sm:grid-cols-4 */
|
||||
}
|
||||
}
|
||||
|
||||
.responsive-text {
|
||||
font-size: 1.25rem; /* text-xl */
|
||||
}
|
||||
|
||||
@media (min-width: 640px) {
|
||||
.responsive-text {
|
||||
font-size: 1.5rem; /* sm:text-2xl */
|
||||
}
|
||||
}
|
||||
|
||||
@media (min-width: 1024px) {
|
||||
.responsive-text {
|
||||
font-size: 1.875rem; /* lg:text-3xl */
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### **R1.2 彈窗響應式實現**
|
||||
```typescript
|
||||
// 實際的彈窗響應式處理
|
||||
<div className="fixed z-50 bg-white rounded-xl shadow-lg w-80 sm:w-96 max-w-[90vw] overflow-hidden">
|
||||
{/* 彈窗內容 */}
|
||||
</div>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🧪 **實際開發配置**
|
||||
|
||||
### **Dev1. 開發環境**
|
||||
|
||||
#### **Dev1.1 實際依賴**
|
||||
```json
|
||||
{
|
||||
"next": "15.5.3",
|
||||
"react": "^18",
|
||||
"typescript": "^5",
|
||||
"tailwindcss": "^3",
|
||||
"@types/react": "^18"
|
||||
}
|
||||
```
|
||||
|
||||
#### **Dev1.2 實際腳本**
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"dev": "next dev",
|
||||
"build": "next build",
|
||||
"start": "next start"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 **技術債務與改進建議**
|
||||
|
||||
### **Debt1. 當前技術債務**
|
||||
|
||||
#### **Debt1.1 未使用的代碼**
|
||||
```typescript
|
||||
// 需要清理的未使用變數
|
||||
const [mode, setMode] = useState<'manual' | 'screenshot'>('manual') // setMode未使用
|
||||
const [isPremium] = useState(true) // isPremium未使用
|
||||
```
|
||||
|
||||
#### **Debt1.2 假資料依賴**
|
||||
```typescript
|
||||
// 需要替換為真實API的部分
|
||||
const handleAnalyzeSentence = async () => {
|
||||
// 目前：假資料模式
|
||||
// 未來：真實API調用
|
||||
}
|
||||
```
|
||||
|
||||
### **Improve1. 建議改進**
|
||||
|
||||
#### **Improve1.1 短期改進**
|
||||
1. **移除未使用變數**: 清理setMode, isPremium等
|
||||
2. **API切換準備**: 為真實API調用做準備
|
||||
3. **錯誤處理**: 完善API失敗的錯誤處理
|
||||
|
||||
#### **Improve1.2 中期改進**
|
||||
1. **使用限制**: 實現真實的使用次數限制
|
||||
2. **本地緩存**: 添加分析結果的本地緩存
|
||||
3. **性能監控**: 添加性能指標收集
|
||||
|
||||
---
|
||||
|
||||
## 🚀 **部署就緒檢查表**
|
||||
|
||||
### **Deploy1. 生產準備度**
|
||||
|
||||
#### **Deploy1.1 功能完整性** ✅
|
||||
- [x] 核心詞彙標記功能完整
|
||||
- [x] 統計展示準確
|
||||
- [x] 慣用語功能完整
|
||||
- [x] 彈窗互動正常
|
||||
- [x] 響應式設計完整
|
||||
|
||||
#### **Deploy1.2 代碼品質** ✅
|
||||
- [x] TypeScript零錯誤
|
||||
- [x] React性能優化
|
||||
- [x] 無console錯誤
|
||||
- [x] 記憶體穩定
|
||||
|
||||
#### **Deploy1.3 用戶體驗** ✅
|
||||
- [x] 載入時間 < 2秒
|
||||
- [x] 互動響應 < 100ms
|
||||
- [x] 視覺設計一致
|
||||
- [x] 移動設備兼容
|
||||
|
||||
---
|
||||
|
||||
## 📋 **實際維護指南**
|
||||
|
||||
### **Maintain1. 日常維護**
|
||||
|
||||
#### **Maintain1.1 監控指標**
|
||||
- **性能**: 頁面載入時間、互動響應時間
|
||||
- **錯誤**: JavaScript錯誤率、API失敗率
|
||||
- **使用**: 詞彙點擊率、保存成功率
|
||||
|
||||
#### **Maintain1.2 更新流程**
|
||||
1. **測試**: 完整功能測試
|
||||
2. **性能**: 性能回歸測試
|
||||
3. **兼容**: 瀏覽器兼容性檢查
|
||||
4. **用戶**: 用戶體驗驗證
|
||||
|
||||
---
|
||||
|
||||
**文件版本**: v1.0 (實際實現版)
|
||||
**對應代碼**: 當前main分支
|
||||
**最後驗證**: 2025-09-22
|
||||
**下次檢查**: 功能更新時
|
||||
Loading…
Reference in New Issue