173 lines
5.9 KiB
Markdown
173 lines
5.9 KiB
Markdown
# API 資料解析問題診斷報告
|
||
|
||
## 執行摘要
|
||
日期：2025-09-30
|
||
問題：前端無法正確顯示後端 API 返回的詞彙分析資料
|
||
|
||
## 一、問題描述
|
||
|
||
使用者回報在句子分析功能中，雖然後端 API 成功返回資料，但前端頁面上的詞彙沒有正確顯示：
|
||
- 詞彙沒有顯示難度等級的顏色標記
|
||
- 高頻詞彙的星星標記 ⭐ 沒有出現
|
||
- 點擊詞彙可能無法顯示詳細資訊
|
||
|
||
## 二、API 資料結構分析
|
||
|
||
### 後端返回的資料格式
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"analysisId": "4ed620c7-2be2-4ded-9d90-1a4156341c87",
|
||
"originalText": "How are you?",
|
||
"sentenceMeaning": "你好嗎？",
|
||
"vocabularyAnalysis": {
|
||
"How": {
|
||
"word": "How",
|
||
"translation": "如何",
|
||
"definition": "In what way or manner; by what means.",
|
||
"partOfSpeech": "adverb",
|
||
"pronunciation": "/haʊ/",
|
||
"difficultyLevel": "A1", // 注意：是 difficultyLevel，不是 cefrLevel
|
||
"frequency": "high",
|
||
"synonyms": ["in what way", "by what means"],
|
||
"example": "How do you do?",
|
||
"exampleTranslation": "你好嗎？"
|
||
},
|
||
"are": { ... },
|
||
"you": { ... }
|
||
},
|
||
"idioms": [],
|
||
"grammarCorrection": null
|
||
}
|
||
}
|
||
```
|
||
|
||
### 關鍵觀察
|
||
1. **詞彙鍵值**：vocabularyAnalysis 的鍵是大寫開頭（"How", "are", "you"）
|
||
2. **欄位名稱**：使用 `difficultyLevel` 而非 `cefrLevel`
|
||
3. **所有詞彙都標記為 `frequency: "high"`**
|
||
|
||
## 三、發現的問題
|
||
|
||
### 問題 1：欄位名稱不匹配
|
||
**位置：** `frontend/components/ClickableTextV2.tsx` 第 167 行
|
||
**問題：** 程式碼尋找 `cefrLevel` 但後端提供 `difficultyLevel`
|
||
```javascript
|
||
// 錯誤的程式碼
|
||
const wordCefr = getWordProperty(wordAnalysis, 'cefrLevel') // ❌
|
||
|
||
// 應該改為
|
||
const wordCefr = getWordProperty(wordAnalysis, 'difficultyLevel') // ✅
|
||
```
|
||
|
||
### 問題 2：詞彙匹配邏輯
|
||
**位置：** `frontend/components/ClickableTextV2.tsx` 第 115-125 行
|
||
**問題：** `findWordAnalysis` 函數的查找順序可能無法正確匹配
|
||
|
||
當前查找順序：
|
||
1. `analysis?.[word]` - 原始詞彙（例如 "How"）
|
||
2. `analysis?.[capitalizedWord]` - 首字母大寫（例如 "How"）
|
||
3. `analysis?.[cleanWord]` - 清理後小寫（例如 "how"）
|
||
4. `analysis?.[word.toLowerCase()]` - 全小寫（例如 "how"）
|
||
5. `analysis?.[word.toUpperCase()]` - 全大寫（例如 "HOW"）
|
||
|
||
**潛在問題：**
|
||
- "you?" 會因為問號而無法匹配到 "you"
|
||
- 需要先清理標點符號
|
||
|
||
### 問題 3：星星顯示邏輯（已部分修復）
|
||
**位置：** `frontend/components/ClickableTextV2.tsx` 第 161-180 行
|
||
**現況：**
|
||
- 第 172-173 行的邏輯會檢查使用者程度是否大於詞彙程度
|
||
- 對於 A2 使用者，A1 詞彙會被判定為「簡單」而不顯示星星
|
||
|
||
### 問題 4：樣式類別返回空字串
|
||
**位置：** `frontend/components/ClickableTextV2.tsx` 第 136 行
|
||
**問題：** 當 `wordAnalysis` 為 null 時，返回空字串，導致詞彙沒有任何樣式
|
||
|
||
## 四、建議修復方案
|
||
|
||
### 立即修復（優先級高）
|
||
|
||
1. **修正欄位名稱**
|
||
- 檔案：`ClickableTextV2.tsx` 第 167 行
|
||
- 將 `cefrLevel` 改為 `difficultyLevel`
|
||
|
||
2. **改進詞彙匹配**
|
||
- 在 `findWordAnalysis` 函數開始時先清理標點符號
|
||
- 確保 "you?" 能匹配到 "you"
|
||
|
||
3. **簡化星星顯示邏輯**
|
||
- 移除複雜的程度比較
|
||
- 直接顯示所有 `frequency: "high"` 的詞彙
|
||
|
||
### 建議的程式碼修改
|
||
|
||
```javascript
|
||
// 1. 改進 findWordAnalysis 函數
|
||
const findWordAnalysis = useCallback((word: string) => {
|
||
// 先清理標點符號
|
||
const cleanWord = word.replace(/[.,!?;:'"]/g, '')
|
||
const lowerWord = cleanWord.toLowerCase()
|
||
const capitalizedWord = cleanWord.charAt(0).toUpperCase() + cleanWord.slice(1).toLowerCase()
|
||
|
||
// 嘗試各種可能的鍵值
|
||
return analysis?.[cleanWord] || // 清理後的原始大小寫
|
||
analysis?.[capitalizedWord] || // 首字母大寫
|
||
analysis?.[lowerWord] || // 全小寫
|
||
analysis?.[cleanWord.toUpperCase()] || // 全大寫
|
||
null
|
||
}, [analysis])
|
||
|
||
// 2. 修正星星顯示函數
|
||
const shouldShowStar = useCallback((word: string) => {
|
||
try {
|
||
const wordAnalysis = findWordAnalysis(word)
|
||
if (!wordAnalysis) return false
|
||
|
||
const frequency = getWordProperty(wordAnalysis, 'frequency')
|
||
// 簡化邏輯：只要是高頻詞就顯示星星
|
||
return frequency === 'high'
|
||
} catch (error) {
|
||
console.warn('Error checking word frequency:', error)
|
||
return false
|
||
}
|
||
}, [findWordAnalysis, getWordProperty])
|
||
```
|
||
|
||
## 五、測試建議
|
||
|
||
### 測試案例
|
||
1. 輸入 "How are you?" - 應該三個詞都顯示星星
|
||
2. 輸入 "What's your name?" - 測試縮寫和標點符號處理
|
||
3. 輸入混合大小寫 "HeLLo WoRLD" - 測試大小寫匹配
|
||
4. 點擊每個詞彙確認彈出視窗正確顯示
|
||
|
||
### 驗證清單
|
||
- [ ] 詞彙有正確的顏色標記（灰色/綠色/橙色）
|
||
- [ ] 高頻詞顯示星星標記 ⭐
|
||
- [ ] 點擊詞彙能顯示詳細資訊
|
||
- [ ] 中文翻譯正確顯示
|
||
- [ ] 詞彙統計數字正確
|
||
|
||
## 六、長期改進建議
|
||
|
||
1. **統一欄位命名規範**
|
||
- 前後端統一使用 `difficultyLevel` 或 `cefrLevel`
|
||
- 建立 TypeScript 介面定義確保型別安全
|
||
|
||
2. **加強錯誤處理**
|
||
- 加入更多 console.log 進行除錯
|
||
- 提供使用者友善的錯誤訊息
|
||
|
||
3. **效能優化**
|
||
- 考慮使用 memo 快取詞彙分析結果
|
||
- 減少不必要的重新渲染
|
||
|
||
## 七、結論
|
||
|
||
主要問題是前端程式碼中的欄位名稱（`cefrLevel`）與後端API返回的欄位名稱（`difficultyLevel`）不匹配，導致無法正確讀取詞彙資料。修正這些欄位名稱並改進詞彙匹配邏輯後，應該能解決資料顯示問題。
|
||
|
||
---
|
||
報告完成時間：2025-09-30 17:15 |