From 9cf36d8e21957ca3db628f5b9c98a6b94891555d Mon Sep 17 00:00:00 2001 From: beabigegg Date: Thu, 13 Nov 2025 08:54:37 +0800 Subject: [PATCH] fix: resolve 7 frontend-backend API inconsistencies and add comprehensive documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fixed LoginResponse: added expires_in field - Renamed format to file_format across FileInfo interface - Updated ProcessRequest: replaced confidence_threshold with detect_layout - Modified ProcessResponse: added message and total_files, removed task_id - Removed non-existent getTaskStatus API call - Fixed getOCRResult parameter from taskId to fileId - Commented out translation config APIs pending backend implementation Documentation: - Added API_REFERENCE.md: Complete API endpoint inventory - Added API_FIX_SUMMARY.md: Detailed before/after comparison of all fixes - Added FRONTEND_API.md: Frontend integration documentation - Added FRONTEND_QUICK_START.md: Quick start guide - Added FRONTEND_UPGRADE_SUMMARY.md: Upgrade summary 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- API_FIX_SUMMARY.md | 368 +++++++++++++++ API_REFERENCE.md | 743 +++++++++++++++++++++++++++++ FRONTEND_API.md | 893 +++++++++++++++++++++++++++++++++++ FRONTEND_QUICK_START.md | 184 ++++++++ FRONTEND_UPGRADE_SUMMARY.md | 650 +++++++++++++++++++++++++ frontend/src/services/api.ts | 50 +- frontend/src/types/api.ts | 11 +- 7 files changed, 2865 insertions(+), 34 deletions(-) create mode 100644 API_FIX_SUMMARY.md create mode 100644 API_REFERENCE.md create mode 100644 FRONTEND_API.md create mode 100644 FRONTEND_QUICK_START.md create mode 100644 FRONTEND_UPGRADE_SUMMARY.md diff --git a/API_FIX_SUMMARY.md b/API_FIX_SUMMARY.md new file mode 100644 index 0000000..2fd561f --- /dev/null +++ b/API_FIX_SUMMARY.md @@ -0,0 +1,368 @@ +# API 前後端不一致問題修正總結 + +## 修正日期 +2025-01-13 + +## 修正概覽 + +本次修正針對前後端 API 整合的 6 個主要問題進行了全面修復，確保前後端資料結構完全一致。 + +--- + +## 已修正的問題 + +### ✅ 問題 1: 登入回應結構不一致 + +**修正內容**: +- 在前端 `LoginResponse` 型別新增 `expires_in` 欄位 + +**修改檔案**: +- [frontend/src/types/api.ts:12-16](frontend/src/types/api.ts#L12-L16) + +**變更**: +```typescript +// 修正前 +export interface LoginResponse { + access_token: string + token_type: string +} + +// 修正後 +export interface LoginResponse { + access_token: string + token_type: string + expires_in: number // Token expiration time in seconds +} +``` + +**影響**: +- ✅ 前端現在可以接收 Token 過期時間 +- ✅ 可實作 Token 自動續期功能 +- ✅ 可提前提醒使用者 Token 即將過期 + +--- + +### ✅ 問題 2: OCR 任務狀態 API 不存在 + +**修正內容**: +- 移除前端的 `getTaskStatus()` 方法 +- 統一使用 `getBatchStatus()` 進行批次狀態追蹤 +- 從 import 中移除 `TaskStatus` 型別 + +**修改檔案**: +- [frontend/src/services/api.ts:3-18](frontend/src/services/api.ts#L3-L18) - 移除 TaskStatus import +- [frontend/src/services/api.ts:153-160](frontend/src/services/api.ts#L153-L160) - 移除 getTaskStatus 方法 + +**變更**: +```typescript +// 修正前 +import type { + // ... 其他型別 + TaskStatus, + // ... +} + +async getTaskStatus(taskId: string): Promise { + const response = await this.client.get(`/ocr/status/${taskId}`) + return response.data +} + +// 修正後 +// TaskStatus 已從 import 移除 +// getTaskStatus 方法已刪除 +// 統一使用 getBatchStatus() 追蹤狀態 +``` + +**影響**: +- ✅ 避免呼叫不存在的 API 端點 (404 錯誤) +- ✅ 統一使用批次狀態管理 +- ✅ 簡化狀態追蹤邏輯 + +--- + +### ✅ 問題 3: OCR 處理請求/回應模型不符 + +**修正內容**: +- 修改 `ProcessRequest` 型別，改用 `detect_layout` 取代 `confidence_threshold` +- 修改 `ProcessResponse` 型別，新增 `message` 和 `total_files` 欄位，移除 `task_id` + +**修改檔案**: +- [frontend/src/types/api.ts:37-50](frontend/src/types/api.ts#L37-L50) + +**變更**: +```typescript +// 修正前 +export interface ProcessRequest { + batch_id: number + lang?: string + confidence_threshold?: number // ❌ 後端不支援此欄位 +} + +export interface ProcessResponse { + task_id: string // ❌ 後端不回傳此欄位 + batch_id: number + status: string +} + +// 修正後 +export interface ProcessRequest { + batch_id: number + lang?: string + detect_layout?: boolean // ✅ 與後端一致 +} + +export interface ProcessResponse { + message: string // ✅ 新增 + batch_id: number + total_files: number // ✅ 新增 + status: string + // task_id 已移除 +} +``` + +**影響**: +- ✅ 前端可正確傳遞版面偵測參數給後端 +- ✅ 前端可接收處理訊息和檔案總數 +- ✅ 避免型別檢查錯誤 +- ✅ 避免驗證失敗 + +--- + +### ✅ 問題 4: 上傳檔案欄位命名不一致 + +**修正內容**: +- 將 `FileInfo.format` 改名為 `FileInfo.file_format` + +**修改檔案**: +- [frontend/src/types/api.ts:28-35](frontend/src/types/api.ts#L28-L35) + +**變更**: +```typescript +// 修正前 +export interface FileInfo { + id: number + filename: string + file_size: number + format: string // ❌ 與後端欄位名稱不同 + status: 'pending' | 'processing' | 'completed' | 'failed' +} + +// 修正後 +export interface FileInfo { + id: number + filename: string + file_size: number + file_format: string // ✅ 與後端一致 + status: 'pending' | 'processing' | 'completed' | 'failed' +} +``` + +**影響**: +- ✅ 前端可直接使用後端回傳的 `file_format` 欄位 +- ✅ 無需額外的欄位映射或轉換 +- ✅ UI 可正確顯示檔案格式 + +--- + +### ✅ 問題 5: CSS 模板清單缺少 filename + +**修正內容**: +- 移除 `CSSTemplate.filename` 欄位定義 +- 改用 `name` 作為模板識別碼 + +**修改檔案**: +- [frontend/src/types/api.ts:135-139](frontend/src/types/api.ts#L135-L139) + +**變更**: +```typescript +// 修正前 +export interface CSSTemplate { + name: string + description: string + filename: string // ❌ 後端實際不回傳此欄位 +} + +// 修正後 +export interface CSSTemplate { + name: string + description: string + // filename 已移除，使用 name 作為識別碼 +} +``` + +**影響**: +- ✅ 避免 `filename` 為 undefined 的問題 +- ✅ 使用 `name` 作為 `