533 lines
14 KiB
Markdown
533 lines
14 KiB
Markdown
# 前端詞卡管理資料流程圖
|
||
|
||
## 📋 **文檔概覽**
|
||
|
||
本文檔詳細說明前端詞卡管理功能如何取得詞卡及其例句圖片，並顯示在用戶介面上的完整資料流程。
|
||
|
||
---
|
||
|
||
## 🏗️ **整體架構圖**
|
||
|
||
```mermaid
|
||
graph TB
|
||
A[用戶訪問 /flashcards] --> B[FlashcardsContent 組件初始化]
|
||
B --> C[useEffect 觸發資料載入]
|
||
C --> D[flashcardsService.getFlashcards()]
|
||
D --> E[HTTP GET /api/flashcards]
|
||
E --> F[FlashcardsController.GetFlashcards()]
|
||
F --> G[EF Core 查詢 + Include 圖片關聯]
|
||
G --> H[資料庫查詢 flashcards + example_images]
|
||
H --> I[IImageStorageService.GetImageUrlAsync()]
|
||
I --> J[組裝回應資料]
|
||
J --> K[前端接收 flashcards 陣列]
|
||
K --> L[狀態更新 setFlashcards()]
|
||
L --> M[UI 重新渲染]
|
||
M --> N[FlashcardItem 組件渲染]
|
||
N --> O[圖片顯示邏輯判斷]
|
||
O --> P{有例句圖片?}
|
||
P -->|Yes| Q[顯示圖片 <img>]
|
||
P -->|No| R[顯示新增按鈕]
|
||
Q --> S[響應式圖片縮放]
|
||
R --> T[點擊觸發 handleGenerateExampleImage]
|
||
```
|
||
|
||
---
|
||
|
||
## 🔄 **詳細資料流程**
|
||
|
||
### **第1階段：頁面初始化**
|
||
|
||
#### **1.1 組件載入**
|
||
```typescript
|
||
// /frontend/app/flashcards/page.tsx
|
||
export default function FlashcardsPage() {
|
||
return (
|
||
<ProtectedRoute>
|
||
<FlashcardsContent />
|
||
</ProtectedRoute>
|
||
)
|
||
}
|
||
|
||
function FlashcardsContent() {
|
||
const [searchState, searchActions] = useFlashcardSearch(activeTab)
|
||
|
||
useEffect(() => {
|
||
loadTotalCounts() // 初始化資料載入
|
||
}, [])
|
||
}
|
||
```
|
||
|
||
#### **1.2 資料載入觸發**
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant UC as 用戶
|
||
participant FC as FlashcardsContent
|
||
participant FS as flashcardsService
|
||
participant API as Backend API
|
||
|
||
UC->>FC: 訪問 /flashcards
|
||
FC->>FC: useEffect 觸發
|
||
FC->>FS: searchActions.refresh()
|
||
FS->>API: GET /api/flashcards
|
||
```
|
||
|
||
---
|
||
|
||
### **第2階段：後端資料處理**
|
||
|
||
#### **2.1 API 端點處理**
|
||
```csharp
|
||
// FlashcardsController.GetFlashcards()
|
||
var query = _context.Flashcards
|
||
.Include(f => f.FlashcardExampleImages) // 載入圖片關聯
|
||
.ThenInclude(fei => fei.ExampleImage) // 載入圖片詳情
|
||
.Where(f => f.UserId == userId && !f.IsArchived)
|
||
.AsQueryable();
|
||
```
|
||
|
||
#### **2.2 資料庫查詢流程**
|
||
```mermaid
|
||
graph LR
|
||
A[Flashcards Table] --> B[FlashcardExampleImages Table]
|
||
B --> C[ExampleImages Table]
|
||
A --> D[User Filter]
|
||
A --> E[Search Filter]
|
||
A --> F[CEFR Filter]
|
||
C --> G[Image URL Generation]
|
||
G --> H[完整 JSON 回應]
|
||
```
|
||
|
||
#### **2.3 圖片資料組裝**
|
||
```csharp
|
||
// 每個 flashcard 處理圖片關聯
|
||
foreach (var flashcardImage in flashcard.FlashcardExampleImages)
|
||
{
|
||
var imageUrl = await _imageStorageService.GetImageUrlAsync(
|
||
flashcardImage.ExampleImage.RelativePath
|
||
);
|
||
|
||
exampleImages.Add(new ExampleImageDto
|
||
{
|
||
Id = flashcardImage.ExampleImage.Id.ToString(),
|
||
ImageUrl = imageUrl, // 完整的 HTTP URL
|
||
IsPrimary = flashcardImage.IsPrimary,
|
||
QualityScore = flashcardImage.ExampleImage.QualityScore
|
||
});
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### **第3階段：前端資料接收與處理**
|
||
|
||
#### **3.1 API 回應結構**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"flashcards": [
|
||
{
|
||
"id": "94c32b17-53a7-4de5-9bfc-f6d4f2dc1368",
|
||
"word": "up",
|
||
"translation": "出",
|
||
"example": "He brought the issue up in the meeting.",
|
||
|
||
// 新增的圖片相關欄位
|
||
"exampleImages": [
|
||
{
|
||
"id": "d96d3330-7814-45e1-9ac6-801c8ca32ee7",
|
||
"imageUrl": "https://localhost:5008/images/examples/xxx.png",
|
||
"isPrimary": true,
|
||
"qualityScore": 0.95,
|
||
"fileSize": 190000
|
||
}
|
||
],
|
||
"hasExampleImage": true,
|
||
"primaryImageUrl": "https://localhost:5008/images/examples/xxx.png"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### **3.2 前端狀態更新流程**
|
||
```mermaid
|
||
graph TD
|
||
A[API 回應接收] --> B[解構 flashcards 陣列]
|
||
B --> C[更新 React 狀態]
|
||
C --> D[觸發組件重新渲染]
|
||
D --> E[FlashcardItem 組件 map 渲染]
|
||
E --> F[個別詞卡資料傳入]
|
||
F --> G[圖片顯示邏輯判斷]
|
||
```
|
||
|
||
---
|
||
|
||
### **第4階段：UI 渲染與圖片顯示**
|
||
|
||
#### **4.1 詞卡項目渲染**
|
||
```typescript
|
||
// FlashcardItem 組件
|
||
function FlashcardItem({ card, ... }) {
|
||
return (
|
||
<div className="bg-white border rounded-lg">
|
||
{/* 圖片區域 - 響應式設計 */}
|
||
<div className="w-32 h-20 sm:w-40 sm:h-24 md:w-48 md:h-32">
|
||
{hasExampleImage(card) ? (
|
||
// 顯示圖片
|
||
<img
|
||
src={getExampleImage(card)}
|
||
alt={`${card.word} example`}
|
||
className="w-full h-full object-cover"
|
||
/>
|
||
) : (
|
||
// 顯示新增按鈕
|
||
<div onClick={() => onGenerateExampleImage(card)}>
|
||
<span>新增例句圖</span>
|
||
</div>
|
||
)}
|
||
</div>
|
||
|
||
{/* 詞卡資訊 */}
|
||
<div className="flex-1">
|
||
<h3>{card.word}</h3>
|
||
<span>{card.translation}</span>
|
||
</div>
|
||
</div>
|
||
)
|
||
}
|
||
```
|
||
|
||
#### **4.2 圖片顯示判斷邏輯**
|
||
```mermaid
|
||
flowchart TD
|
||
A[FlashcardItem 渲染] --> B{檢查 card.hasExampleImage}
|
||
B -->|true| C[取得 card.primaryImageUrl]
|
||
B -->|false| D[顯示新增例句圖按鈕]
|
||
C --> E[設定 img src 屬性]
|
||
E --> F[瀏覽器載入圖片]
|
||
F --> G{圖片載入成功?}
|
||
G -->|成功| H[顯示 512x512 圖片]
|
||
G -->|失敗| I[顯示錯誤提示]
|
||
D --> J[用戶點擊生成按鈕]
|
||
J --> K[觸發 handleGenerateExampleImage]
|
||
H --> L[CSS 響應式縮放顯示]
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 **技術實現細節**
|
||
|
||
### **前端服務層**
|
||
```typescript
|
||
// /frontend/lib/services/flashcards.ts
|
||
export const flashcardsService = {
|
||
async getFlashcards(): Promise<FlashcardsResponse> {
|
||
const response = await fetch(`${API_URL}/api/flashcards`, {
|
||
headers: {
|
||
'Authorization': `Bearer ${getToken()}`,
|
||
'Content-Type': 'application/json'
|
||
}
|
||
})
|
||
|
||
return response.json()
|
||
}
|
||
}
|
||
|
||
// 回應介面定義
|
||
interface Flashcard {
|
||
id: string
|
||
word: string
|
||
translation: string
|
||
example: string
|
||
|
||
// 圖片相關欄位
|
||
exampleImages: ExampleImage[]
|
||
hasExampleImage: boolean
|
||
primaryImageUrl?: string
|
||
}
|
||
|
||
interface ExampleImage {
|
||
id: string
|
||
imageUrl: string
|
||
isPrimary: boolean
|
||
qualityScore?: number
|
||
fileSize?: number
|
||
}
|
||
```
|
||
|
||
### **圖片顯示邏輯**
|
||
```typescript
|
||
// 當前實現 (將被取代)
|
||
const getExampleImage = (card: Flashcard): string | null => {
|
||
// 硬編碼映射 (舊方式)
|
||
const imageMap: {[key: string]: string} = {
|
||
'evidence': '/images/examples/bring_up.png',
|
||
}
|
||
return imageMap[card.word?.toLowerCase()] || null
|
||
}
|
||
|
||
// 新實現 (基於 API 資料)
|
||
const getExampleImage = (card: Flashcard): string | null => {
|
||
return card.primaryImageUrl || null
|
||
}
|
||
|
||
const hasExampleImage = (card: Flashcard): boolean => {
|
||
return card.hasExampleImage
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🖼️ **圖片載入和顯示流程**
|
||
|
||
### **圖片 URL 生成過程**
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant FE as 前端
|
||
participant BE as 後端 API
|
||
participant DB as 資料庫
|
||
participant FS as 檔案系統
|
||
|
||
FE->>BE: GET /api/flashcards
|
||
BE->>DB: 查詢 flashcards + images
|
||
DB-->>BE: 返回關聯資料
|
||
BE->>FS: 檢查圖片檔案存在
|
||
FS-->>BE: 確認檔案路徑
|
||
BE->>BE: 生成完整 HTTP URL
|
||
BE-->>FE: 回應包含 imageUrl
|
||
FE->>FS: 瀏覽器請求圖片
|
||
FS-->>FE: 返回 512x512 PNG 圖片
|
||
```
|
||
|
||
### **響應式圖片顯示**
|
||
```css
|
||
/* 圖片容器響應式尺寸 */
|
||
.example-image-container {
|
||
/* 手機 */
|
||
width: 128px; /* w-32 */
|
||
height: 80px; /* h-20 */
|
||
}
|
||
|
||
@media (min-width: 640px) {
|
||
.example-image-container {
|
||
/* 平板 */
|
||
width: 160px; /* sm:w-40 */
|
||
height: 96px; /* sm:h-24 */
|
||
}
|
||
}
|
||
|
||
@media (min-width: 768px) {
|
||
.example-image-container {
|
||
/* 桌面 */
|
||
width: 192px; /* md:w-48 */
|
||
height: 128px; /* md:h-32 */
|
||
}
|
||
}
|
||
|
||
/* 圖片本身處理 */
|
||
.example-image {
|
||
width: 100%;
|
||
height: 100%;
|
||
object-fit: cover; /* 保持比例，裁切適應容器 */
|
||
border-radius: 8px;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## ⚡ **效能優化策略**
|
||
|
||
### **前端優化**
|
||
```typescript
|
||
// 圖片懶載入
|
||
<img
|
||
src={card.primaryImageUrl}
|
||
loading="lazy" // 瀏覽器原生懶載入
|
||
alt={`${card.word} example`}
|
||
/>
|
||
|
||
// 錯誤處理
|
||
<img
|
||
src={card.primaryImageUrl}
|
||
onError={(e) => {
|
||
e.target.style.display = 'none'
|
||
// 顯示備用內容
|
||
}}
|
||
/>
|
||
```
|
||
|
||
### **後端優化**
|
||
```csharp
|
||
// 查詢優化
|
||
var flashcards = await query
|
||
.AsNoTracking() // 只讀查詢優化
|
||
.OrderByDescending(f => f.CreatedAt)
|
||
.ToListAsync();
|
||
|
||
// 圖片 URL 快取 (未來實現)
|
||
private readonly IMemoryCache _urlCache;
|
||
```
|
||
|
||
---
|
||
|
||
## 🎮 **用戶互動流程**
|
||
|
||
### **圖片生成流程**
|
||
```mermaid
|
||
flowchart TD
|
||
A[用戶看到詞卡] --> B{是否有圖片?}
|
||
B -->|有| C[顯示 512x512 圖片]
|
||
B -->|無| D[顯示新增例句圖按鈕]
|
||
D --> E[用戶點擊按鈕]
|
||
E --> F[觸發 handleGenerateExampleImage]
|
||
F --> G[調用圖片生成 API]
|
||
G --> H[顯示生成進度]
|
||
H --> I[等待 2-3 分鐘]
|
||
I --> J[生成完成]
|
||
J --> K[自動刷新詞卡列表]
|
||
K --> L[新圖片顯示在詞卡中]
|
||
```
|
||
|
||
### **生成進度顯示**
|
||
```typescript
|
||
// 生成狀態管理
|
||
const [generatingCards, setGeneratingCards] = useState<Set<string>>(new Set())
|
||
|
||
const handleGenerateExampleImage = async (card: Flashcard) => {
|
||
// 1. 標記為生成中
|
||
setGeneratingCards(prev => new Set([...prev, card.id]))
|
||
|
||
try {
|
||
// 2. 調用生成 API
|
||
const result = await imageGenerationService.generateImage(card.id)
|
||
|
||
// 3. 輪詢進度
|
||
await imageGenerationService.pollUntilComplete(result.requestId)
|
||
|
||
// 4. 刷新資料
|
||
await searchActions.refresh()
|
||
|
||
// 5. 顯示成功訊息
|
||
toast.success(`「${card.word}」的例句圖片生成完成！`)
|
||
} catch (error) {
|
||
toast.error(`圖片生成失敗: ${error.message}`)
|
||
} finally {
|
||
// 6. 移除生成中狀態
|
||
setGeneratingCards(prev => {
|
||
const newSet = new Set(prev)
|
||
newSet.delete(card.id)
|
||
return newSet
|
||
})
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 **資料流轉換表**
|
||
|
||
| 階段 | 資料格式 | 位置 | 範例 |
|
||
|------|----------|------|------|
|
||
| **資料庫** | 關聯表格 | `flashcard_example_images` | `{flashcard_id, example_image_id, is_primary}` |
|
||
| **EF Core** | 實體物件 | `Flashcard.FlashcardExampleImages` | `List<FlashcardExampleImage>` |
|
||
| **後端 API** | JSON 回應 | HTTP Response | `{hasExampleImage: true, primaryImageUrl: "https://..."}` |
|
||
| **前端狀態** | TypeScript 物件 | React State | `flashcards: Flashcard[]` |
|
||
| **UI 組件** | JSX 元素 | React Component | `<img src={card.primaryImageUrl} />` |
|
||
| **瀏覽器** | 實際圖片 | DOM | `512x512 PNG 圖片顯示` |
|
||
|
||
---
|
||
|
||
## 🔍 **錯誤處理流程**
|
||
|
||
### **API 層級錯誤**
|
||
```mermaid
|
||
graph TD
|
||
A[API 調用] --> B{網路狀態}
|
||
B -->|成功| C[解析 JSON]
|
||
B -->|失敗| D[顯示網路錯誤]
|
||
C --> E{success: true?}
|
||
E -->|Yes| F[正常資料流程]
|
||
E -->|No| G[顯示 API 錯誤訊息]
|
||
D --> H[重試機制]
|
||
G --> H
|
||
H --> I[用戶手動重新整理]
|
||
```
|
||
|
||
### **圖片載入錯誤**
|
||
```typescript
|
||
// 圖片載入失敗處理
|
||
const handleImageError = (e: React.SyntheticEvent<HTMLImageElement>) => {
|
||
const target = e.target as HTMLImageElement
|
||
target.style.display = 'none'
|
||
|
||
// 顯示備用內容
|
||
target.parentElement!.innerHTML = `
|
||
<div class="text-gray-400 text-xs text-center">
|
||
<svg class="w-6 h-6 mx-auto mb-1">
|
||
<!-- 錯誤圖示 -->
|
||
</svg>
|
||
圖片載入失敗
|
||
</div>
|
||
`
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 **實際運作範例**
|
||
|
||
### **情境1：有圖片的詞卡 (deal)**
|
||
```
|
||
1. 用戶訪問詞卡頁面
|
||
2. API 返回: hasExampleImage: true, primaryImageUrl: "https://localhost:5008/..."
|
||
3. React 渲染: <img src="https://localhost:5008/..." />
|
||
4. 瀏覽器載入: 512x512 PNG 圖片 (約190KB)
|
||
5. CSS 處理: 響應式縮放顯示在詞卡中
|
||
```
|
||
|
||
### **情境2：無圖片的詞卡 (up)**
|
||
```
|
||
1. 用戶訪問詞卡頁面
|
||
2. API 返回: hasExampleImage: false, primaryImageUrl: null
|
||
3. React 渲染: 新增例句圖按鈕
|
||
4. 用戶點擊: 觸發圖片生成流程
|
||
5. 生成完成: 自動刷新並顯示新圖片
|
||
```
|
||
|
||
---
|
||
|
||
## 🔮 **未來擴展規劃**
|
||
|
||
### **前端增強功能**
|
||
- **圖片預覽**: 點擊圖片查看大圖
|
||
- **多圖片支援**: 輪播顯示多張例句圖
|
||
- **圖片編輯**: 刪除、重新生成功能
|
||
- **批量生成**: 一次為多個詞卡生成圖片
|
||
|
||
### **效能優化**
|
||
- **圖片 CDN**: 雲端加速分發
|
||
- **WebP 格式**: 更小的檔案大小
|
||
- **預載入**: 預先載入即將顯示的圖片
|
||
- **虛擬化**: 大量詞卡的效能優化
|
||
|
||
---
|
||
|
||
## 📈 **監控指標**
|
||
|
||
### **前端效能**
|
||
- 頁面載入時間: 目標 < 2 秒
|
||
- 圖片載入時間: 目標 < 1 秒
|
||
- API 回應時間: 目標 < 500ms
|
||
|
||
### **用戶體驗**
|
||
- 圖片顯示成功率: 目標 > 95%
|
||
- 生成成功率: 目標 > 90%
|
||
- 用戶滿意度: 目標 > 4.5/5
|
||
|
||
---
|
||
|
||
**文檔版本**: v1.0
|
||
**建立日期**: 2025-09-24
|
||
**最後更新**: 2025-09-24
|
||
**相關文檔**: [前後端整合計劃](./EXAMPLE_IMAGE_FRONTEND_BACKEND_INTEGRATION_PLAN.md) |