OCR/frontend

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

安裝依賴

cd frontend
npm install

啟動開發伺服器

npm run dev

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

建置生產版本

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

---

開發指南

安裝新依賴

# 安裝 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:

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

建置

npm run build

部署到 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 - 完整前端 API 文件
• API_REFERENCE.md - 後端 API 參考

---

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