# Tool_OCR Frontend

> 現代化的 OCR 文件處理系統前端介面
>
> 基於 React 18 + Vite + TypeScript + Tailwind CSS + shadcn/ui

---

## 目錄

- [快速開始](#快速開始)
- [功能特性](#功能特性)
- [技術棧](#技術棧)
- [專案結構](#專案結構)
- [開發指南](#開發指南)
- [部署說明](#部署說明)

---

## 快速開始

### 前置需求

- Node.js >= 18.0.0
- npm >= 9.0.0
- 後端 API 服務運行在 `http://localhost:12010`

### 安裝依賴

```bash
cd frontend
npm install
```

### 啟動開發伺服器

```bash
npm run dev
```

瀏覽器開啟: `http://localhost:12011`

### 建置生產版本

```bash
npm run build
```

建置輸出目錄: `dist/`

---

## 功能特性

### 1. 使用者認證
- JWT Token 認證
- 自動登出處理
- 受保護路由

### 2. 批次檔案上傳
- **拖放上傳介面** (react-dropzone)
- **支援格式**: PNG, JPG, JPEG, PDF, DOC, DOCX, PPT, PPTX
- **批次限制**: 單檔 50MB, 每批次最多 100 檔
- **即時預覽**: 檔案清單、大小、狀態

### 3. OCR 處理追蹤
- **即時進度顯示** (2 秒輪詢)
- **統計儀表板**: 已完成/處理中/失敗數量
- **檔案級別狀態**: 處理狀態、時間、錯誤訊息
- **自動跳轉**: 處理完成後自動進入結果頁面

### 4. 結果預覽
- **雙欄佈局**: 檔案清單 + 內容預覽
- **多格式預覽**: Markdown 渲染 / JSON 資料
- **統計資訊**: OCR 信心度、處理時間、文字區塊數

### 5. 靈活匯出
- **匯出格式**: TXT, JSON, Excel, Markdown, PDF, ZIP
- **自訂規則**: 建立、編輯、刪除匯出規則
- **CSS 模板**: 選擇 PDF 樣式 (default, academic, business)

### 6. 設定管理
- 使用者資訊顯示
- 匯出規則 CRUD 操作
- 系統設定

---

## 技術棧

### 核心框架
- **React 18.2** - 使用者介面框架
- **TypeScript 5.9** - 型別安全
- **Vite 7.2** - 快速建置工具

### 狀態管理
- **React Query (TanStack Query)** - 伺服器狀態管理
- **Zustand** - 客戶端狀態管理

### UI 組件庫
- **Tailwind CSS 4.1** - CSS 框架
- **shadcn/ui** - React 組件庫
- **Lucide React** - 圖示庫

### 路由與 HTTP
- **React Router 7.9** - 客戶端路由
- **Axios** - HTTP 請求

### 其他
- **react-dropzone** - 拖放上傳
- **react-markdown** - Markdown 渲染
- **i18next** - 國際化

---

## 專案結構

```
frontend/
├── src/
│   ├── components/
│   │   ├── ui/                # shadcn/ui 組件
│   │   ├── FileUpload.tsx
│   │   ├── ResultsTable.tsx
│   │   ├── MarkdownPreview.tsx
│   │   └── Layout.tsx
│   ├── pages/
│   │   ├── LoginPage.tsx
│   │   ├── UploadPage.tsx
│   │   ├── ProcessingPage.tsx
│   │   ├── ResultsPage.tsx
│   │   ├── ExportPage.tsx
│   │   └── SettingsPage.tsx
│   ├── store/
│   │   ├── authStore.ts
│   │   └── uploadStore.ts
│   ├── services/
│   │   └── api.ts
│   ├── types/
│   │   └── api.ts
│   ├── lib/
│   │   └── utils.ts
│   ├── i18n/
│   ├── styles/
│   ├── App.tsx
│   └── main.tsx
├── package.json
├── vite.config.ts
├── tailwind.config.js
└── tsconfig.json
```

---

## 開發指南

### 安裝新依賴

```bash
# 安裝 class-variance-authority (如果尚未安裝)
npm install class-variance-authority

# 安裝 react-markdown (如果尚未安裝)
npm install react-markdown
```

### 新增 shadcn/ui 組件

所有 shadcn/ui 組件已在 `src/components/ui/` 目錄中,包括:
- Button, Card, Input, Label, Select
- Alert, Dialog, Tabs, Badge
- Progress, Toast, Table

### 整合新 API

1. 在 `src/types/api.ts` 定義型別
2. 在 `src/services/api.ts` 新增方法
3. 在頁面組件使用 React Query

---

## 部署說明

### 環境變數

建立 `.env.production`:

```bash
VITE_API_BASE_URL=http://your-api-server.com:12010
VITE_APP_NAME=Tool_OCR
```

### 建置

```bash
npm run build
```

### 部署到 Nginx

```nginx
server {
    listen 80;
    server_name tool-ocr.example.com;
    root /var/www/tool-ocr;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api {
        proxy_pass http://127.0.0.1:12010;
        proxy_set_header Host $host;
    }
}
```

---

## 參考文件

- [FRONTEND_API.md](../FRONTEND_API.md) - 完整前端 API 文件
- [API_REFERENCE.md](../API_REFERENCE.md) - 後端 API 參考

---

**版本**: 0.1.0 | **最後更新**: 2025-01-13