779 lines
20 KiB
Markdown
779 lines
20 KiB
Markdown
# 複習系統前端規格書
|
||
|
||
**版本**: 1.0
|
||
**對應**: 技術實作規格.md + 產品需求規格.md
|
||
**技術棧**: React 18 + TypeScript + Tailwind CSS
|
||
**狀態管理**: React useState (極簡架構)
|
||
**最後更新**: 2025-10-03
|
||
|
||
---
|
||
|
||
## 📱 **前端架構設計**
|
||
|
||
### **目錄結構**
|
||
```
|
||
app/review-simple/
|
||
├── page.tsx # 主頁面邏輯
|
||
├── data.ts # 數據和類型定義
|
||
├── globals.css # 翻卡動畫樣式
|
||
└── components/
|
||
├── SimpleFlipCard.tsx # 翻卡記憶組件
|
||
├── SimpleChoiceTest.tsx # 詞彙選擇組件 (階段2)
|
||
├── SimpleProgress.tsx # 進度顯示組件
|
||
├── SimpleResults.tsx # 結果統計組件
|
||
└── SimpleTestHeader.tsx # 測試標題組件
|
||
```
|
||
|
||
---
|
||
|
||
## 🗃️ **數據結構設計**
|
||
|
||
### **卡片狀態接口**
|
||
```typescript
|
||
interface CardState extends ApiFlashcard {
|
||
// 前端狀態管理欄位
|
||
skipCount: number // 跳過次數
|
||
wrongCount: number // 答錯次數
|
||
successCount: number // 答對次數
|
||
isCompleted: boolean // 是否已完成
|
||
originalOrder: number // 原始順序索引
|
||
|
||
// 計算屬性
|
||
delayScore: number // 延遲分數 = skipCount + wrongCount
|
||
lastAttemptAt: Date // 最後嘗試時間
|
||
}
|
||
```
|
||
|
||
### **學習會話狀態**
|
||
```typescript
|
||
interface ReviewSessionState {
|
||
// 卡片管理
|
||
cards: CardState[]
|
||
currentIndex: number
|
||
|
||
// 進度統計
|
||
score: {
|
||
correct: number // 答對總數
|
||
total: number // 嘗試總數
|
||
}
|
||
|
||
// 會話控制
|
||
isComplete: boolean
|
||
startTime: Date
|
||
|
||
// UI狀態
|
||
currentMode: 'flip' | 'choice' // 階段2需要
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## ⚙️ **核心邏輯函數**
|
||
|
||
### **延遲計數管理**
|
||
```typescript
|
||
// 跳過處理
|
||
const handleSkip = useCallback((cards: CardState[], currentIndex: number) => {
|
||
const updatedCards = cards.map((card, index) =>
|
||
index === currentIndex
|
||
? {
|
||
...card,
|
||
skipCount: card.skipCount + 1,
|
||
delayScore: card.skipCount + 1 + card.wrongCount,
|
||
lastAttemptAt: new Date()
|
||
}
|
||
: card
|
||
)
|
||
|
||
return {
|
||
updatedCards,
|
||
nextIndex: getNextCardIndex(updatedCards, currentIndex)
|
||
}
|
||
}, [])
|
||
|
||
// 答錯處理
|
||
const handleWrongAnswer = useCallback((cards: CardState[], currentIndex: number) => {
|
||
const updatedCards = cards.map((card, index) =>
|
||
index === currentIndex
|
||
? {
|
||
...card,
|
||
wrongCount: card.wrongCount + 1,
|
||
delayScore: card.skipCount + card.wrongCount + 1,
|
||
lastAttemptAt: new Date()
|
||
}
|
||
: card
|
||
)
|
||
|
||
return {
|
||
updatedCards,
|
||
nextIndex: getNextCardIndex(updatedCards, currentIndex)
|
||
}
|
||
}, [])
|
||
|
||
// 答對處理
|
||
const handleCorrectAnswer = useCallback((cards: CardState[], currentIndex: number) => {
|
||
const updatedCards = cards.map((card, index) =>
|
||
index === currentIndex
|
||
? {
|
||
...card,
|
||
isCompleted: true,
|
||
successCount: card.successCount + 1,
|
||
lastAttemptAt: new Date()
|
||
}
|
||
: card
|
||
)
|
||
|
||
return {
|
||
updatedCards,
|
||
nextIndex: getNextCardIndex(updatedCards, currentIndex)
|
||
}
|
||
}, [])
|
||
```
|
||
|
||
### **智能排序系統**
|
||
```typescript
|
||
// 卡片優先級排序 (您的核心需求)
|
||
const sortCardsByPriority = useCallback((cards: CardState[]): CardState[] => {
|
||
return cards.sort((a, b) => {
|
||
// 1. 已完成的卡片排到最後
|
||
if (a.isCompleted && !b.isCompleted) return 1
|
||
if (!a.isCompleted && b.isCompleted) return -1
|
||
|
||
// 2. 未完成卡片按延遲分數排序 (越少越前面)
|
||
const aDelayScore = a.skipCount + a.wrongCount
|
||
const bDelayScore = b.skipCount + b.wrongCount
|
||
|
||
if (aDelayScore !== bDelayScore) {
|
||
return aDelayScore - bDelayScore
|
||
}
|
||
|
||
// 3. 延遲分數相同時按原始順序
|
||
return a.originalOrder - b.originalOrder
|
||
})
|
||
}, [])
|
||
|
||
// 獲取下一張卡片索引
|
||
const getNextCardIndex = (cards: CardState[], currentIndex: number): number => {
|
||
const sortedCards = sortCardsByPriority(cards)
|
||
const incompleteCards = sortedCards.filter(card => !card.isCompleted)
|
||
|
||
if (incompleteCards.length === 0) return -1 // 全部完成
|
||
|
||
// 返回排序後第一張未完成卡片的索引
|
||
const nextCard = incompleteCards[0]
|
||
return cards.findIndex(card => card.id === nextCard.id)
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 **組件設計規格**
|
||
|
||
### **SimpleFlipCard.tsx (階段1)**
|
||
```typescript
|
||
interface SimpleFlipCardProps {
|
||
card: CardState
|
||
onAnswer: (confidence: 1|2|3) => void // 簡化為3選項
|
||
onSkip: () => void
|
||
}
|
||
|
||
// 內部狀態
|
||
const [isFlipped, setIsFlipped] = useState(false)
|
||
const [selectedConfidence, setSelectedConfidence] = useState<number | null>(null)
|
||
const [cardHeight, setCardHeight] = useState<number>(400)
|
||
|
||
// 信心度選項 (簡化版)
|
||
const confidenceOptions = [
|
||
{ level: 1, label: '模糊', color: 'bg-orange-100 text-orange-700 border-orange-200' },
|
||
{ level: 2, label: '一般', color: 'bg-yellow-100 text-yellow-700 border-yellow-200' },
|
||
{ level: 3, label: '熟悉', color: 'bg-green-100 text-green-700 border-green-200' }
|
||
]
|
||
```
|
||
|
||
### **SimpleChoiceTest.tsx (階段2)**
|
||
```typescript
|
||
interface SimpleChoiceTestProps {
|
||
card: CardState
|
||
options: string[] // 4選1選項
|
||
onAnswer: (answer: string) => void
|
||
onSkip: () => void
|
||
}
|
||
|
||
// 內部狀態
|
||
const [selectedAnswer, setSelectedAnswer] = useState<string | null>(null)
|
||
const [showResult, setShowResult] = useState(false)
|
||
|
||
// 答案驗證
|
||
const isCorrect = useMemo(() => selectedAnswer === card.word, [selectedAnswer, card.word])
|
||
```
|
||
|
||
### **SimpleProgress.tsx**
|
||
```typescript
|
||
interface SimpleProgressProps {
|
||
cards: CardState[]
|
||
currentIndex: number
|
||
score: { correct: number; total: number }
|
||
}
|
||
|
||
// 進度計算
|
||
const completedCount = cards.filter(card => card.isCompleted).length
|
||
const totalCount = cards.length
|
||
const progressPercentage = (completedCount / totalCount) * 100
|
||
|
||
// 延遲統計 (顯示跳過次數)
|
||
const delayedCards = cards.filter(card => card.skipCount + card.wrongCount > 0)
|
||
const totalSkips = cards.reduce((sum, card) => sum + card.skipCount, 0)
|
||
const totalWrongs = cards.reduce((sum, card) => sum + card.wrongCount, 0)
|
||
```
|
||
|
||
---
|
||
|
||
## 🌐 **API呼叫策略** (各階段明確區分)
|
||
|
||
### **階段1: 純靜態數據 (當前MVP)**
|
||
```typescript
|
||
// 完全不呼叫任何API
|
||
export default function SimpleReviewPage() {
|
||
useEffect(() => {
|
||
// 直接使用靜態數據，無網路依賴
|
||
const staticCards = SIMPLE_CARDS.map((card, index) => ({
|
||
...card,
|
||
skipCount: 0,
|
||
wrongCount: 0,
|
||
// ... 其他前端狀態
|
||
}))
|
||
setCards(staticCards)
|
||
}, [])
|
||
|
||
// 答題完成時：只更新前端狀態，不呼叫API
|
||
const handleAnswer = (confidence: number) => {
|
||
// 純前端邏輯，無API調用
|
||
updateLocalState(confidence)
|
||
}
|
||
}
|
||
```
|
||
|
||
### **階段2: 本地持久化 (localStorage)**
|
||
```typescript
|
||
// 仍然不呼叫API，只添加本地存儲
|
||
export default function SimpleReviewPage() {
|
||
useEffect(() => {
|
||
// 1. 嘗試從localStorage載入
|
||
const savedProgress = loadFromLocalStorage()
|
||
|
||
if (savedProgress && isSameDay(savedProgress.timestamp)) {
|
||
setCards(savedProgress.cards)
|
||
setCurrentIndex(savedProgress.currentIndex)
|
||
} else {
|
||
// 2. 無有效存檔則使用靜態數據
|
||
setCards(SIMPLE_CARDS.map(addStateFields))
|
||
}
|
||
}, [])
|
||
|
||
// 答題時：更新狀態 + 保存到localStorage
|
||
const handleAnswer = (confidence: number) => {
|
||
const newState = updateLocalState(confidence)
|
||
saveToLocalStorage(newState) // 本地持久化
|
||
// 仍然不呼叫API
|
||
}
|
||
}
|
||
```
|
||
|
||
### **階段3: API集成 (遠期)**
|
||
```typescript
|
||
// 明確的API呼叫時機和策略
|
||
export default function SimpleReviewPage() {
|
||
const [dataSource, setDataSource] = useState<'static' | 'api'>('static')
|
||
|
||
useEffect(() => {
|
||
const loadCards = async () => {
|
||
setLoading(true)
|
||
|
||
try {
|
||
// 嘗試API呼叫
|
||
const response = await fetch('/api/flashcards/due?limit=10', {
|
||
headers: {
|
||
'Authorization': `Bearer ${getAuthToken()}`
|
||
}
|
||
})
|
||
|
||
if (response.ok) {
|
||
const apiData = await response.json()
|
||
setCards(apiData.data.flashcards.map(addStateFields))
|
||
setDataSource('api')
|
||
} else {
|
||
throw new Error('API failed')
|
||
}
|
||
} catch (error) {
|
||
console.warn('API unavailable, using static data:', error)
|
||
// 降級到靜態數據
|
||
setCards(SIMPLE_CARDS.map(addStateFields))
|
||
setDataSource('static')
|
||
} finally {
|
||
setLoading(false)
|
||
}
|
||
}
|
||
|
||
loadCards()
|
||
}, [])
|
||
|
||
// 答題時的API呼叫邏輯
|
||
const handleAnswer = async (confidence: number) => {
|
||
// 1. 立即更新前端狀態 (即時響應)
|
||
const newState = updateLocalState(confidence)
|
||
|
||
// 2. 如果使用API，同步到後端
|
||
if (dataSource === 'api') {
|
||
try {
|
||
await fetch(`/api/flashcards/${currentCard.id}/review`, {
|
||
method: 'POST',
|
||
headers: {
|
||
'Authorization': `Bearer ${getAuthToken()}`,
|
||
'Content-Type': 'application/json'
|
||
},
|
||
body: JSON.stringify({
|
||
confidence: confidence,
|
||
isCorrect: confidence >= 2
|
||
})
|
||
})
|
||
} catch (error) {
|
||
console.warn('Failed to sync to backend:', error)
|
||
// 前端狀態已更新，API失敗不影響用戶體驗
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### **API呼叫判斷邏輯**
|
||
```typescript
|
||
// 何時使用API vs 靜態數據
|
||
const determineDataSource = () => {
|
||
// 檢查是否有認證Token
|
||
const hasAuth = getAuthToken() !== null
|
||
|
||
// 檢查是否在生產環境
|
||
const isProduction = process.env.NODE_ENV === 'production'
|
||
|
||
// 檢查是否明確要求使用API
|
||
const forceApi = window.location.search.includes('api=true')
|
||
|
||
return (hasAuth && isProduction) || forceApi ? 'api' : 'static'
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 **狀態管理設計**
|
||
|
||
### **主頁面狀態 (page.tsx)**
|
||
```typescript
|
||
export default function SimpleReviewPage() {
|
||
// 核心狀態
|
||
const [cards, setCards] = useState<CardState[]>([])
|
||
const [currentIndex, setCurrentIndex] = useState(0)
|
||
const [score, setScore] = useState({ correct: 0, total: 0 })
|
||
const [isComplete, setIsComplete] = useState(false)
|
||
const [mode, setMode] = useState<'flip' | 'choice'>('flip') // 階段2需要
|
||
|
||
// 初始化卡片狀態
|
||
useEffect(() => {
|
||
const initialCards: CardState[] = SIMPLE_CARDS.map((card, index) => ({
|
||
...card,
|
||
skipCount: 0,
|
||
wrongCount: 0,
|
||
successCount: 0,
|
||
isCompleted: false,
|
||
originalOrder: index,
|
||
delayScore: 0,
|
||
lastAttemptAt: new Date()
|
||
}))
|
||
setCards(initialCards)
|
||
}, [])
|
||
|
||
// 答題處理
|
||
const handleAnswer = useCallback((confidence: number) => {
|
||
const isCorrect = confidence >= 2 // 一般以上算答對
|
||
|
||
if (isCorrect) {
|
||
const result = handleCorrectAnswer(cards, currentIndex)
|
||
setCards(result.updatedCards)
|
||
setCurrentIndex(result.nextIndex)
|
||
} else {
|
||
const result = handleWrongAnswer(cards, currentIndex)
|
||
setCards(result.updatedCards)
|
||
setCurrentIndex(result.nextIndex)
|
||
}
|
||
|
||
// 更新分數統計
|
||
setScore(prev => ({
|
||
correct: prev.correct + (isCorrect ? 1 : 0),
|
||
total: prev.total + 1
|
||
}))
|
||
|
||
// 檢查是否完成
|
||
checkIfComplete(result.updatedCards)
|
||
}, [cards, currentIndex])
|
||
|
||
// 跳過處理
|
||
const handleSkipCard = useCallback(() => {
|
||
const result = handleSkip(cards, currentIndex)
|
||
setCards(result.updatedCards)
|
||
setCurrentIndex(result.nextIndex)
|
||
|
||
checkIfComplete(result.updatedCards)
|
||
}, [cards, currentIndex])
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🎨 **UI/UX規格**
|
||
|
||
### **翻卡動畫CSS** (您調教過的)
|
||
```css
|
||
/* 3D翻卡動畫 */
|
||
.flip-card-container {
|
||
perspective: 1000px;
|
||
}
|
||
|
||
.flip-card {
|
||
transform-style: preserve-3d;
|
||
transition: transform 0.6s cubic-bezier(0.4, 0, 0.2, 1);
|
||
}
|
||
|
||
.flip-card.flipped {
|
||
transform: rotateY(180deg);
|
||
}
|
||
|
||
.flip-card-front,
|
||
.flip-card-back {
|
||
backface-visibility: hidden;
|
||
position: absolute;
|
||
width: 100%;
|
||
height: 100%;
|
||
}
|
||
|
||
.flip-card-back {
|
||
transform: rotateY(180deg);
|
||
}
|
||
```
|
||
|
||
### **響應式設計規格**
|
||
```typescript
|
||
// 智能高度計算 (您的原設計)
|
||
const calculateCardHeight = useCallback(() => {
|
||
if (backRef.current) {
|
||
const backHeight = backRef.current.scrollHeight
|
||
const minHeight = window.innerWidth <= 480 ? 300 :
|
||
window.innerWidth <= 768 ? 350 : 400
|
||
return Math.max(minHeight, backHeight)
|
||
}
|
||
return 400
|
||
}, [])
|
||
|
||
// 信心度按鈕響應式
|
||
const buttonLayout = window.innerWidth <= 640
|
||
? 'grid-cols-1 gap-2' // 手機版: 垂直排列
|
||
: 'grid-cols-3 gap-3' // 桌面版: 水平排列
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 **本地存儲設計** (階段2+)
|
||
|
||
### **進度持久化**
|
||
```typescript
|
||
// localStorage 結構
|
||
interface StoredProgress {
|
||
sessionId: string
|
||
cards: CardState[]
|
||
currentIndex: number
|
||
score: { correct: number; total: number }
|
||
lastSaveTime: string
|
||
}
|
||
|
||
// 儲存進度
|
||
const saveProgress = (cards: CardState[], currentIndex: number, score: any) => {
|
||
const progress: StoredProgress = {
|
||
sessionId: `review_${Date.now()}`,
|
||
cards,
|
||
currentIndex,
|
||
score,
|
||
lastSaveTime: new Date().toISOString()
|
||
}
|
||
|
||
localStorage.setItem('review-progress', JSON.stringify(progress))
|
||
}
|
||
|
||
// 載入進度
|
||
const loadProgress = (): StoredProgress | null => {
|
||
const saved = localStorage.getItem('review-progress')
|
||
if (!saved) return null
|
||
|
||
try {
|
||
const progress = JSON.parse(saved)
|
||
// 檢查是否是當日進度 (避免過期數據)
|
||
const saveTime = new Date(progress.lastSaveTime)
|
||
const now = new Date()
|
||
const isToday = saveTime.toDateString() === now.toDateString()
|
||
|
||
return isToday ? progress : null
|
||
} catch {
|
||
return null
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 **路由和導航設計**
|
||
|
||
### **頁面路由**
|
||
```typescript
|
||
// 路由配置
|
||
const reviewRoutes = {
|
||
main: '/review-simple', // 主複習頁面
|
||
maintenance: '/review', // 維護頁面 (舊版本隔離)
|
||
backup: '/review-old' // 備份頁面 (複雜版本)
|
||
}
|
||
|
||
// 導航更新
|
||
const navigationItems = [
|
||
{ href: '/dashboard', label: '儀表板' },
|
||
{ href: '/flashcards', label: '詞卡' },
|
||
{ href: '/review-simple', label: '複習' }, // 指向可用版本
|
||
{ href: '/generate', label: 'AI 生成' }
|
||
]
|
||
```
|
||
|
||
### **頁面跳轉邏輯**
|
||
```typescript
|
||
// 會話完成後的跳轉
|
||
const handleComplete = () => {
|
||
setIsComplete(true)
|
||
// 可選: 3秒後自動跳轉
|
||
setTimeout(() => {
|
||
router.push('/dashboard')
|
||
}, 3000)
|
||
}
|
||
|
||
// 中途退出處理
|
||
const handleExit = () => {
|
||
if (window.confirm('確定要退出複習嗎？進度將不會保存。')) {
|
||
router.push('/flashcards')
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 **性能優化規格**
|
||
|
||
### **React性能優化**
|
||
```typescript
|
||
// 使用 memo 避免不必要重渲染
|
||
export const SimpleFlipCard = memo(SimpleFlipCardComponent)
|
||
export const SimpleProgress = memo(SimpleProgressComponent)
|
||
|
||
// useCallback 穩定化函數引用
|
||
const handleAnswer = useCallback((confidence: number) => {
|
||
// ... 邏輯
|
||
}, [cards, currentIndex])
|
||
|
||
// useMemo 緩存計算結果
|
||
const sortedCards = useMemo(() =>
|
||
sortCardsByPriority(cards),
|
||
[cards]
|
||
)
|
||
|
||
const currentCard = useMemo(() =>
|
||
cards[currentIndex],
|
||
[cards, currentIndex]
|
||
)
|
||
```
|
||
|
||
### **載入性能目標**
|
||
```typescript
|
||
// 性能指標
|
||
const PERFORMANCE_TARGETS = {
|
||
INITIAL_LOAD: 1500, // 初始載入 < 1.5秒
|
||
CARD_FLIP: 300, // 翻卡動畫 < 300ms
|
||
SORT_OPERATION: 100, // 排序計算 < 100ms
|
||
STATE_UPDATE: 50, // 狀態更新 < 50ms
|
||
NAVIGATION: 200 // 頁面跳轉 < 200ms
|
||
}
|
||
|
||
// 性能監控
|
||
const measurePerformance = (operation: string, fn: Function) => {
|
||
const start = performance.now()
|
||
const result = fn()
|
||
const end = performance.now()
|
||
|
||
console.log(`${operation}: ${end - start}ms`)
|
||
return result
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 **測試架構**
|
||
|
||
### **測試文件結構**
|
||
```
|
||
__tests__/
|
||
├── delay-counting-system.test.ts # 延遲計數邏輯測試
|
||
├── card-sorting.test.ts # 排序算法測試
|
||
├── confidence-mapping.test.ts # 信心度映射測試
|
||
└── components/
|
||
├── SimpleFlipCard.test.tsx # 翻卡組件測試
|
||
├── SimpleProgress.test.tsx # 進度組件測試
|
||
└── integration.test.tsx # 完整流程集成測試
|
||
```
|
||
|
||
### **Mock數據設計**
|
||
```typescript
|
||
// 測試用的 Mock 數據
|
||
export const MOCK_CARDS: CardState[] = [
|
||
{
|
||
id: 'test-1',
|
||
word: 'evidence',
|
||
definition: 'facts or information indicating truth',
|
||
skipCount: 0,
|
||
wrongCount: 0,
|
||
successCount: 0,
|
||
isCompleted: false,
|
||
originalOrder: 0,
|
||
delayScore: 0,
|
||
// ... 其他 API 欄位
|
||
},
|
||
{
|
||
id: 'test-2',
|
||
word: 'priority',
|
||
definition: 'the fact of being more important',
|
||
skipCount: 2,
|
||
wrongCount: 1,
|
||
successCount: 0,
|
||
isCompleted: false,
|
||
originalOrder: 1,
|
||
delayScore: 3,
|
||
// ... 其他 API 欄位
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 **開發工具配置**
|
||
|
||
### **TypeScript 配置**
|
||
```typescript
|
||
// 嚴格的類型檢查
|
||
interface 必須完整定義
|
||
Props 必須有明確類型
|
||
回調函數必須有返回值類型
|
||
狀態更新必須使用正確的類型
|
||
|
||
// 避免 any 類型
|
||
禁止: any, object, Function
|
||
建議: 具體的接口定義
|
||
```
|
||
|
||
### **ESLint 規則**
|
||
```typescript
|
||
// 代碼品質規則
|
||
'react-hooks/exhaustive-deps': 'error' // 確保 useEffect 依賴正確
|
||
'react/no-array-index-key': 'warn' // 避免使用 index 作為 key
|
||
'@typescript-eslint/no-unused-vars': 'error' // 禁止未使用變數
|
||
|
||
// 複雜度控制
|
||
'max-lines': ['error', 200] // 組件最多200行
|
||
'max-params': ['error', 5] // 函數最多5個參數
|
||
'complexity': ['error', 10] // 圈複雜度最多10
|
||
```
|
||
|
||
---
|
||
|
||
## 📱 **使用者體驗規格**
|
||
|
||
### **載入狀態處理**
|
||
```typescript
|
||
// 載入狀態
|
||
const [isLoading, setIsLoading] = useState(true)
|
||
|
||
// 載入動畫
|
||
const LoadingSpinner = () => (
|
||
<div className="flex items-center justify-center h-64">
|
||
<div className="animate-spin rounded-full h-12 w-12 border-b-2 border-blue-600" />
|
||
<span className="ml-3 text-gray-600">準備詞卡中...</span>
|
||
</div>
|
||
)
|
||
```
|
||
|
||
### **錯誤處理**
|
||
```typescript
|
||
// 錯誤狀態
|
||
const [error, setError] = useState<string | null>(null)
|
||
|
||
// 錯誤邊界
|
||
const ErrorBoundary = ({ error, onRetry }) => (
|
||
<div className="bg-red-50 border border-red-200 rounded-lg p-6">
|
||
<h3 className="text-lg font-semibold text-red-700 mb-2">發生錯誤</h3>
|
||
<p className="text-red-600 mb-4">{error}</p>
|
||
<button
|
||
onClick={onRetry}
|
||
className="bg-red-600 text-white px-4 py-2 rounded-lg hover:bg-red-700"
|
||
>
|
||
重新嘗試
|
||
</button>
|
||
</div>
|
||
)
|
||
```
|
||
|
||
### **無障礙設計**
|
||
```typescript
|
||
// 鍵盤操作支援
|
||
const handleKeyDown = (e: KeyboardEvent) => {
|
||
switch (e.key) {
|
||
case 'ArrowLeft': handleSkip(); break
|
||
case 'ArrowRight': handleAnswer(2); break // 一般
|
||
case 'ArrowUp': handleAnswer(3); break // 熟悉
|
||
case 'ArrowDown': handleAnswer(1); break // 模糊
|
||
case ' ': handleFlip(); break // 空格翻卡
|
||
}
|
||
}
|
||
|
||
// ARIA 標籤
|
||
<button
|
||
aria-label={`信心度選擇: ${label}`}
|
||
role="button"
|
||
tabIndex={0}
|
||
>
|
||
{label}
|
||
</button>
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 **開發檢查清單**
|
||
|
||
### **組件開發完成標準**
|
||
- [ ] TypeScript 無錯誤和警告
|
||
- [ ] 所有 props 都有預設值或必填檢查
|
||
- [ ] 使用 memo/useCallback 優化性能
|
||
- [ ] 響應式設計在手機和桌面都正常
|
||
- [ ] 無障礙功能完整 (鍵盤、ARIA)
|
||
- [ ] 錯誤狀態有適當處理
|
||
|
||
### **功能測試標準**
|
||
- [ ] 所有延遲計數測試通過
|
||
- [ ] 排序邏輯測試通過
|
||
- [ ] 信心度映射測試通過
|
||
- [ ] 完整流程集成測試通過
|
||
- [ ] 邊界條件測試通過
|
||
|
||
---
|
||
|
||
*前端規格維護: 開發團隊*
|
||
*更新觸發: 產品需求變更或技術實作調整*
|
||
*目標: 確保前端實作準確性和一致性* |