fix: resolve 7 frontend-backend API inconsistencies and add comprehensive documentation
- 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 <noreply@anthropic.com>
This commit is contained in:
beabigegg
184
FRONTEND_QUICK_START.md
Normal file
184
FRONTEND_QUICK_START.md
Normal file
@@ -0,0 +1,184 @@
|
||||
# Frontend 快速啟動指南
|
||||
|
||||
> 5 分鐘完成前端環境設置和測試
|
||||
|
||||
---
|
||||
|
||||
## 步驟 1: 安裝依賴 (2 分鐘)
|
||||
|
||||
```bash
|
||||
cd d:\WORK\user_scrip\TOOL\Tool_OCR\frontend
|
||||
npm install
|
||||
```
|
||||
|
||||
**如果出現缺少套件警告,請手動安裝**:
|
||||
|
||||
```bash
|
||||
npm install class-variance-authority react-markdown
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 步驟 2: 啟動開發伺服器 (1 分鐘)
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
**成功訊息**:
|
||||
```
|
||||
VITE v7.2.2 ready in XXX ms
|
||||
|
||||
➜ Local: http://localhost:12011/
|
||||
➜ Network: use --host to expose
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 步驟 3: 開啟瀏覽器測試 (2 分鐘)
|
||||
|
||||
### 1. 打開瀏覽器
|
||||
|
||||
訪問: **http://localhost:12011**
|
||||
|
||||
### 2. 測試登入頁面
|
||||
|
||||
- **預期畫面**: 美觀的雙欄登入介面
|
||||
- 左側: 品牌展示 + 特色介紹
|
||||
- 右側: 登入表單
|
||||
|
||||
![登入頁面預期效果]
|
||||
- 藍色漸層背景
|
||||
- 3 個特色亮點卡片
|
||||
- 統計數據 (99% / 10+ / 1M+)
|
||||
- 專業的輸入框和按鈕
|
||||
|
||||
### 3. 測試上傳頁面 (需先登入)
|
||||
|
||||
**測試帳號** (請確認後端 API 已啟動):
|
||||
- 使用後端設定的測試帳號登入
|
||||
|
||||
**預期功能**:
|
||||
- 拖放區域顯示正常
|
||||
- 可以拖放檔案
|
||||
- 檔案清單顯示
|
||||
- 上傳按鈕可點擊
|
||||
|
||||
### 4. 測試處理頁面
|
||||
|
||||
**預期功能**:
|
||||
- 進度條動畫
|
||||
- 統計卡片 (已完成/處理中/失敗/總計)
|
||||
- 檔案狀態清單
|
||||
- 自動更新進度 (每 2 秒)
|
||||
|
||||
### 5. 測試結果頁面
|
||||
|
||||
**預期功能**:
|
||||
- 左側檔案清單
|
||||
- 右側預覽面板
|
||||
- Markdown / JSON 切換
|
||||
- 統計資訊卡片
|
||||
|
||||
---
|
||||
|
||||
## 常見問題排除
|
||||
|
||||
### Q1: npm install 失敗
|
||||
|
||||
**解決方案**:
|
||||
```bash
|
||||
# 清除快取
|
||||
npm cache clean --force
|
||||
|
||||
# 刪除 node_modules 和 package-lock.json
|
||||
rm -rf node_modules package-lock.json
|
||||
|
||||
# 重新安裝
|
||||
npm install
|
||||
```
|
||||
|
||||
### Q2: Vite 啟動失敗
|
||||
|
||||
**檢查事項**:
|
||||
- Node.js 版本 >= 18.0.0
|
||||
```bash
|
||||
node -v
|
||||
```
|
||||
- 端口 12011 是否被佔用
|
||||
```bash
|
||||
netstat -ano | findstr 12011
|
||||
```
|
||||
|
||||
### Q3: 頁面顯示空白
|
||||
|
||||
**檢查事項**:
|
||||
1. 瀏覽器控制台是否有錯誤訊息 (F12)
|
||||
2. 後端 API 是否已啟動 (http://localhost:12010)
|
||||
3. 網路請求是否正常 (Network 標籤)
|
||||
|
||||
### Q4: 登入失敗
|
||||
|
||||
**確認事項**:
|
||||
- 後端 API 服務已啟動
|
||||
- 測試帳號正確
|
||||
- 網路請求到達後端 (檢查 Network)
|
||||
|
||||
---
|
||||
|
||||
## 後續步驟
|
||||
|
||||
### 開發模式
|
||||
|
||||
```bash
|
||||
# 前端開發 (自動熱更新)
|
||||
npm run dev
|
||||
|
||||
# 程式碼檢查
|
||||
npm run lint
|
||||
|
||||
# TypeScript 型別檢查
|
||||
npm run build
|
||||
```
|
||||
|
||||
### 生產建置
|
||||
|
||||
```bash
|
||||
# 建置
|
||||
npm run build
|
||||
|
||||
# 預覽建置結果
|
||||
npm run preview
|
||||
```
|
||||
|
||||
### 查看文件
|
||||
|
||||
1. **FRONTEND_API.md** - 完整前端架構和 API 整合文件
|
||||
2. **FRONTEND_UPGRADE_SUMMARY.md** - 升級完成報告
|
||||
3. **frontend/README.md** - 使用手冊
|
||||
|
||||
---
|
||||
|
||||
## 測試清單
|
||||
|
||||
完成以下測試確認功能正常:
|
||||
|
||||
- [ ] 前端開發伺服器啟動成功
|
||||
- [ ] 登入頁面顯示正常
|
||||
- [ ] 可以輸入使用者名稱和密碼
|
||||
- [ ] 所有頁面路由正常 (upload, processing, results, export, settings)
|
||||
- [ ] UI 組件樣式正確 (按鈕、卡片、輸入框等)
|
||||
- [ ] 響應式佈局正常 (調整瀏覽器視窗大小)
|
||||
|
||||
---
|
||||
|
||||
## 需要幫助?
|
||||
|
||||
參考以下文件:
|
||||
- **技術問題**: 查看 `FRONTEND_API.md` 的 "Troubleshooting" 章節
|
||||
- **API 整合**: 查看 `FRONTEND_API.md` 的 "API Integration Patterns"
|
||||
- **部署問題**: 查看 `frontend/README.md` 的 "部署說明"
|
||||
|
||||
---
|
||||
|
||||
**預祝使用順利!**
|
||||
Reference in New Issue
Block a user