# 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` 的 "部署說明"

---

**預祝使用順利!**