# Tool_OCR 前端代碼示例和最佳實踐

## 1. Tailwind CSS 樣式使用示例

### 佈局組件 (Layout.tsx 提取)
```typescript
// 導航欄樣式示例
<header className="border-b bg-card">
  <div className="container mx-auto px-4 py-4 flex items-center justify-between">
    <h1 className="text-2xl font-bold text-foreground">{t('app.title')}</h1>
    <button
      className="px-4 py-2 text-sm font-medium text-foreground hover:text-primary transition-colors"
    >
      {t('nav.logout')}
    </button>
  </div>
</header>

{/* 導航選項卡 */}
<nav className="border-b bg-card">
  <div className="container mx-auto px-4">
    <ul className="flex space-x-1">
      {navLinks.map((link) => (
        <NavLink
          to={link.to}
          className={({ isActive }) =>
            `block px-4 py-3 text-sm font-medium transition-colors ${
              isActive
                ? 'text-primary border-b-2 border-primary'
                : 'text-muted-foreground hover:text-foreground'
            }`
          }
        >
          {link.label}
        </NavLink>
      ))}
    </ul>
  </div>
</nav>
```

### 按鈕變體示例 (button.tsx)
```typescript
// 默認按鈕
<Button>Save Changes</Button>

// 危險操作
<Button variant="destructive">Delete</Button>

// 輪廓樣式
<Button variant="outline">Cancel</Button>

// 幽靈按鈕
<Button variant="ghost">Remove</Button>

// 鏈接樣式
<Button variant="link">Learn More</Button>

// 不同尺寸
<Button size="sm">Small</Button>
<Button size="lg">Large</Button>
<Button size="icon">+</Button>
```

### 響應式卡片示例 (UploadPage.tsx 提取)
```typescript
<div className="max-w-4xl mx-auto space-y-6">
  <Card>
    <CardHeader>
      <div className="flex items-center justify-between">
        <CardTitle className="text-lg">
          {t('upload.selectedFiles')} ({selectedFiles.length})
        </CardTitle>
        <Button variant="outline" size="sm" onClick={handleClearAll}>
          {t('upload.clearAll')}
        </Button>
      </div>
    </CardHeader>
    <CardContent>
      <div className="space-y-2">
        {selectedFiles.map((file, index) => (
          <div
            key={index}
            className="flex items-center justify-between p-3 bg-muted rounded-md"
          >
            <div className="flex-1 min-w-0">
              <p className="text-sm font-medium text-foreground truncate">
                {file.name}
              </p>
              <p className="text-xs text-muted-foreground">
                {formatFileSize(file.size)}
              </p>
            </div>
            <Button variant="ghost" size="sm" onClick={() => handleRemoveFile(index)}>
              {t('upload.removeFile')}
            </Button>
          </div>
        ))}
      </div>
    </CardContent>
  </Card>
</div>
```

### 文件上傳拖放區域 (FileUpload.tsx 提取)
```typescript
<Card
  {...getRootProps()}
  className={cn(
    'border-2 border-dashed transition-colors cursor-pointer hover:border-primary/50',
    {
      'border-primary bg-primary/5': isDragActive && !isDragReject,
      'border-destructive bg-destructive/5': isDragReject,
      'opacity-50 cursor-not-allowed': disabled,
    }
  )}
>
  <div className="p-12 text-center">
    <input {...getInputProps()} />
    
    <div className="mb-4">
      <svg className="mx-auto h-12 w-12 text-muted-foreground" />
    </div>

    <div className="space-y-2">
      {isDragActive ? (
        <p className="text-lg font-medium text-primary">
          {isDragReject ? t('upload.invalidFiles') : t('upload.dropFilesHere')}
        </p>
      ) : (
        <>
          <p className="text-lg font-medium text-foreground">
            {t('upload.dragAndDrop')}
          </p>
          <p className="text-sm text-muted-foreground">
            {t('upload.supportedFormats')}
          </p>
        </>
      )}
    </div>
  </div>
</Card>
```

---

## 2. React Query 使用示例

### 批次狀態查詢 (ResultsPage.tsx 提取)
```typescript
import { useQuery } from '@tanstack/react-query'

export default function ResultsPage() {
  const { batchId } = useUploadStore()
  const [selectedFileId, setSelectedFileId] = useState<number | null>(null)

  // 獲取批次狀態
  const { data: batchStatus, isLoading } = useQuery({
    queryKey: ['batchStatus', batchId],
    queryFn: () => apiClient.getBatchStatus(batchId!),
    enabled: !!batchId, // 只在有 batchId 時查詢
  })

  // 獲取 OCR 結果
  const { data: ocrResult, isLoading: isLoadingResult } = useQuery({
    queryKey: ['ocrResult', selectedFileId],
    queryFn: () => apiClient.getOCRResult(selectedFileId!.toString()),
    enabled: !!selectedFileId,
  })

  if (!batchId) {
    return <div>Please upload files first</div>
  }

  return (
    <div>
      {isLoading ? (
        <p>Loading batch status...</p>
      ) : (
        <ResultsTable data={batchStatus?.files} />
      )}
    </div>
  )
}
```

---

## 3. Zustand 狀態管理示例

### 認證存儲 (authStore.ts)
```typescript
import { create } from 'zustand'
import { persist } from 'zustand/middleware'
import type { User } from '@/types/api'

interface AuthState {
  user: User | null
  isAuthenticated: boolean
  setUser: (user: User | null) => void
  logout: () => void
}

export const useAuthStore = create<AuthState>()(
  persist(
    (set) => ({
      user: null,
      isAuthenticated: false,
      setUser: (user) =>
        set({
          user,
          isAuthenticated: user !== null,
        }),
      logout: () =>
        set({
          user: null,
          isAuthenticated: false,
        }),
    }),
    {
      name: 'auth-storage', // localStorage 鍵名
    }
  )
)

// 使用示例
function LoginPage() {
  const setUser = useAuthStore((state) => state.setUser)
  
  const handleLogin = async (username: string, password: string) => {
    const response = await apiClient.login({ username, password })
    setUser({ id: 1, username })
  }
}
```

### 上傳狀態存儲 (uploadStore.ts)
```typescript
export const useUploadStore = create<UploadState>()(
  persist(
    (set) => ({
      batchId: null,
      files: [],
      uploadProgress: 0,
      
      setBatchId: (id) => {
        set({ batchId: id })
      },
      
      setFiles: (files) => set({ files }),
      
      setUploadProgress: (progress) => set({ uploadProgress: progress }),
      
      updateFileStatus: (fileId, status) =>
        set((state) => ({
          files: state.files.map((file) =>
            file.id === fileId ? { ...file, status } : file
          ),
        })),
      
      clearUpload: () =>
        set({
          batchId: null,
          files: [],
          uploadProgress: 0,
        }),
    }),
    {
      name: 'tool-ocr-upload-store',
      // 只持久化 batchId 和 files，不持久化進度
      partialize: (state) => ({
        batchId: state.batchId,
        files: state.files,
      }),
    }
  )
)

// 使用示例
function UploadPage() {
  const { setBatchId, setFiles } = useUploadStore()
  
  const handleUploadSuccess = (data: UploadResponse) => {
    setBatchId(data.batch_id)
    setFiles(data.files)
  }
}
```

---

## 4. API 客戶端使用示例

### API 認證流程 (api.ts)
```typescript
// 登錄
const response = await apiClient.login({
  username: 'admin',
  password: 'password'
})
// Token 自動保存到 localStorage

// 後續請求自動附帶 token
const status = await apiClient.getBatchStatus(123)
// 請求頭自動包含: Authorization: Bearer <token>

// 登出
apiClient.logout()
// Token 自動從 localStorage 清除
```

### 文件上傳示例
```typescript
const handleUpload = async (files: File[]) => {
  try {
    const response = await apiClient.uploadFiles(files)
    // response: { batch_id: 1, files: [...] }
    setBatchId(response.batch_id)
    setFiles(response.files)
  } catch (error) {
    // 自動處理 401 錯誤並重定向到登錄頁
    showError(error.response?.data?.detail)
  }
}
```

### 導出功能示例
```typescript
// 導出 PDF
const handleDownloadPDF = async (fileId: number) => {
  const blob = await apiClient.exportPDF(fileId)
  const url = window.URL.createObjectURL(blob)
  const a = document.createElement('a')
  a.href = url
  a.download = `ocr-result-${fileId}.pdf`
  a.click()
  window.URL.revokeObjectURL(url)
}

// 導出規則管理
const rules = await apiClient.getExportRules()
const newRule = await apiClient.createExportRule({
  rule_name: 'My Rule',
  config_json: { /* ... */ }
})
await apiClient.updateExportRule(rule.id, { rule_name: 'Updated' })
await apiClient.deleteExportRule(rule.id)
```

---

## 5. 國際化使用示例

### 在組件中使用翻譯
```typescript
import { useTranslation } from 'react-i18next'

export default function UploadPage() {
  const { t } = useTranslation()

  return (
    <div>
      <h1>{t('upload.title')}</h1>
      <p>{t('upload.dragAndDrop')}</p>
      
      {/* 帶插值的翻譯 */}
      <p>{t('upload.fileCount', { count: 5 })}</p>
      {/* 會渲染: "已選擇 5 個檔案" */}
      
      <button>{t('upload.uploadButton')}</button>
    </div>
  )
}
```

### i18n 初始化 (i18n/index.ts)
```typescript
import i18n from 'i18next'
import { initReactI18next } from 'react-i18next'
import zhTW from './locales/zh-TW.json'

i18n.use(initReactI18next).init({
  resources: {
    'zh-TW': {
      translation: zhTW,
    },
  },
  lng: 'zh-TW',
  fallbackLng: 'zh-TW',
  interpolation: {
    escapeValue: false,
  },
})

export default i18n
```

---

## 6. 路由和保護示例

### 受保護的路由 (App.tsx)
```typescript
function ProtectedRoute({ children }: { children: React.ReactNode }) {
  const isAuthenticated = useAuthStore((state) => state.isAuthenticated)

  if (!isAuthenticated) {
    return <Navigate to="/login" replace />
  }

  return <>{children}</>
}

function App() {
  return (
    <Routes>
      {/* 公開路由 */}
      <Route path="/login" element={<LoginPage />} />

      {/* 受保護的路由 */}
      <Route
        path="/"
        element={
          <ProtectedRoute>
            <Layout />
          </ProtectedRoute>
        }
      >
        <Route index element={<Navigate to="/upload" replace />} />
        <Route path="upload" element={<UploadPage />} />
        <Route path="processing" element={<ProcessingPage />} />
        <Route path="results" element={<ResultsPage />} />
        <Route path="export" element={<ExportPage />} />
        <Route path="settings" element={<SettingsPage />} />
      </Route>

      {/* 全部匹配 */}
      <Route path="*" element={<Navigate to="/" replace />} />
    </Routes>
  )
}
```

---

## 7. 類型定義示例

### API 類型 (types/api.ts)
```typescript
// 認證
export interface LoginRequest {
  username: string
  password: string
}

export interface LoginResponse {
  access_token: string
  token_type: string
}

// 文件上傳
export interface UploadResponse {
  batch_id: number
  files: FileInfo[]
}

export interface FileInfo {
  id: number
  filename: string
  file_size: number
  format: string
  status: 'pending' | 'processing' | 'completed' | 'failed'
}

// OCR 結果
export interface OCRResult {
  file_id: number
  filename: string
  status: string
  markdown_content: string
  json_data: OCRJsonData
  confidence: number
  processing_time: number
}

export interface TextBlock {
  text: string
  confidence: number
  bbox: [number, number, number, number]
  position: number
}

// 導出規則
export interface ExportRule {
  id: number
  rule_name: string
  config_json: Record<string, any>
  css_template?: string
  created_at: string
}
```

---

## 8. 最佳實踐

### 1. 組件結構
```typescript
// 導入順序
import { useState } from 'react'
import { useNavigate } from 'react-router-dom'
import { useTranslation } from 'react-i18next'
import { useQuery } from '@tanstack/react-query'

// 內部導入
import { Button } from '@/components/ui/button'
import { Card } from '@/components/ui/card'
import { useAuthStore } from '@/store/authStore'
import { apiClient } from '@/services/api'

// 組件定義
export default function MyPage() {
  // Hooks
  const { t } = useTranslation()
  const navigate = useNavigate()
  const [state, setState] = useState(null)
  
  // 查詢
  const { data, isLoading } = useQuery({
    queryKey: ['key'],
    queryFn: () => apiClient.getData(),
  })

  // 狀態更新
  const handleClick = () => {
    // ...
  }

  // 渲染
  return (
    <div className="space-y-4">
      {/* JSX */}
    </div>
  )
}
```

### 2. 錯誤處理
```typescript
const { toast } = useToast()

const handleAction = async () => {
  try {
    const result = await apiClient.doSomething()
    toast({
      title: t('success.title'),
      description: t('success.message'),
      variant: 'success',
    })
  } catch (error: any) {
    const errorMessage = error.response?.data?.detail || t('errors.generic')
    toast({
      title: t('error.title'),
      description: errorMessage,
      variant: 'destructive',
    })
  }
}
```

### 3. 類名合併
```typescript
import { cn } from '@/lib/utils'

// 條件類名
const buttonClass = cn(
  'base-classes',
  {
    'conditional-classes': isActive,
    'other-classes': isDisabled,
  },
  customClassName
)

// 動態樣式
const cardClass = cn(
  'p-4 rounded-lg',
  variant === 'outlined' && 'border border-input',
  variant === 'elevated' && 'shadow-lg'
)
```

### 4. React Query 配置
```typescript
// 主入口 (main.tsx)
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      retry: 1,
      refetchOnWindowFocus: false,
      staleTime: 1000 * 60 * 5, // 5 分鐘
    },
  },
})

// 使用示例
const { data, isLoading, error } = useQuery({
  queryKey: ['items', id],
  queryFn: () => apiClient.getItem(id),
  enabled: !!id, // 條件查詢
  staleTime: 1000 * 60 * 10, // 10 分鐘不新鮮
})
```

---

## 9. 環境變數

### .env 文件
```env
VITE_API_BASE_URL=http://localhost:12010
```

### 使用環境變數
```typescript
const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || 'http://localhost:12010'
```

---

## 10. 常見開發流程

### 創建新頁面
1. 在 `/src/pages` 創建 `NewPage.tsx`
2. 在 `App.tsx` 添加路由
3. 使用 Zustand 管理狀態
4. 使用 React Query 獲取數據
5. 使用 Tailwind CSS 樣式
6. 使用 i18next 添加文字

### 添加新 API 接口
1. 在 `types/api.ts` 定義類型
2. 在 `services/api.ts` 添加方法
3. 在需要的地方使用 `apiClient.method()`
4. 使用 React Query 或直接調用

### 修改樣式
1. 優先使用 Tailwind CSS 工具類
2. 使用 cn() 合併類名
3. 修改 `tailwind.config.js` 自定義主題
4. 在 `index.css` 添加全局樣式