OCR/FRONTEND_API.md

# Tool_OCR Frontend API Documentation

> **Version**: 0.1.0
> **Last Updated**: 2025-01-13
> **Purpose**: Complete documentation of frontend architecture, component structure, API integration, and dependencies

---

## Table of Contents

1. [Project Overview](#project-overview)
2. [Technology Stack](#technology-stack)
3. [Component Architecture](#component-architecture)
4. [Page → API Dependency Matrix](#page--api-dependency-matrix)
5. [Component Tree Structure](#component-tree-structure)
6. [State Management Strategy](#state-management-strategy)
7. [Route Configuration](#route-configuration)
8. [API Integration Patterns](#api-integration-patterns)
9. [UI/UX Design System](#uiux-design-system)
10. [Error Handling Patterns](#error-handling-patterns)
11. [Deployment Configuration](#deployment-configuration)

---

## Project Overview

Tool_OCR 前端是一個基於 React 18 + Vite 的現代化 OCR 文件處理系統,提供企業級的使用者介面和體驗。

### Key Features

- **批次檔案上傳**: 支援拖放上傳,多檔案批次處理
- **即時進度追蹤**: 使用輪詢機制顯示 OCR 處理進度
- **結果預覽**: Markdown 和 JSON 雙格式預覽
- **靈活匯出**: 支援 TXT、JSON、Excel、Markdown、PDF、ZIP 多種格式
- **規則管理**: 可自訂匯出規則和 CSS 模板
- **響應式設計**: 適配桌面和平板裝置

---

## Technology Stack

### Core Dependencies

```json
{
  "@tanstack/react-query": "^5.90.7",    // Server state management
  "react": "^19.2.0",                     // UI framework
  "react-dom": "^19.2.0",
  "react-router-dom": "^7.9.5",           // Routing
  "vite": "^7.2.2",                       // Build tool
  "typescript": "~5.9.3"                  // Type safety
}
```

### UI & Styling

```json
{
  "tailwindcss": "^4.1.17",               // CSS framework
  "class-variance-authority": "^0.7.0",   // Component variants
  "clsx": "^2.1.1",                       // Class name utility
  "tailwind-merge": "^3.4.0",             // Tailwind class merge
  "lucide-react": "^0.553.0"              // Icon library
}
```

### State & Data

```json
{
  "zustand": "^5.0.8",                    // Client state
  "axios": "^1.13.2",                     // HTTP client
  "react-dropzone": "^14.3.8",            // File upload
  "react-markdown": "^9.0.1"              // Markdown rendering
}
```

### Internationalization

```json
{
  "i18next": "^25.6.2",
  "react-i18next": "^16.3.0"
}
```

---

## Component Architecture

### Atomic Design Structure

```
frontend/src/
├── components/
│   ├── ui/                 # Atomic components (shadcn/ui)
│   │   ├── button.tsx
│   │   ├── card.tsx
│   │   ├── input.tsx
│   │   ├── label.tsx
│   │   ├── select.tsx
│   │   ├── badge.tsx
│   │   ├── progress.tsx
│   │   ├── alert.tsx
│   │   ├── dialog.tsx
│   │   ├── tabs.tsx
│   │   ├── table.tsx
│   │   └── toast.tsx
│   ├── FileUpload.tsx      # Drag-and-drop upload component
│   ├── ResultsTable.tsx    # OCR results display table
│   ├── MarkdownPreview.tsx # Markdown content renderer
│   └── Layout.tsx          # Main app layout with sidebar
├── pages/
│   ├── LoginPage.tsx       # Authentication
│   ├── UploadPage.tsx      # File upload and selection
│   ├── ProcessingPage.tsx  # OCR processing status
│   ├── ResultsPage.tsx     # Results viewing and preview
│   ├── ExportPage.tsx      # Export configuration and download
│   └── SettingsPage.tsx    # User settings and rules management
├── store/
│   ├── authStore.ts        # Authentication state (Zustand)
│   └── uploadStore.ts      # Upload batch state (Zustand)
├── services/
│   └── api.ts              # API client (Axios)
├── types/
│   └── api.ts              # TypeScript type definitions
├── lib/
│   └── utils.ts            # Utility functions
├── i18n/
│   └── index.ts            # i18n configuration
└── styles/
    └── index.css           # Global styles and CSS variables
```

---

## Page → API Dependency Matrix

| Page/Component | API Endpoints Used | HTTP Method | Purpose | Polling |
|----------------|-------------------|-------------|---------|---------|
| **LoginPage** | `/api/v1/auth/login` | POST | User authentication | No |
| **UploadPage** | `/api/v1/upload` | POST | Upload files for OCR | No |
| **ProcessingPage** | `/api/v1/ocr/process` | POST | Start OCR processing | No |
| | `/api/v1/batch/{batch_id}/status` | GET | Poll batch status | Yes (2s) |
| **ResultsPage** | `/api/v1/batch/{batch_id}/status` | GET | Load completed files | No |
| | `/api/v1/ocr/result/{file_id}` | GET | Get OCR result details | No |
| | `/api/v1/export/pdf/{file_id}` | GET | Download PDF export | No |
| **ExportPage** | `/api/v1/export` | POST | Export batch results | No |
| | `/api/v1/export/rules` | GET | List export rules | No |
| | `/api/v1/export/rules` | POST | Create new rule | No |
| | `/api/v1/export/rules/{rule_id}` | PUT | Update existing rule | No |
| | `/api/v1/export/rules/{rule_id}` | DELETE | Delete rule | No |
| | `/api/v1/export/css-templates` | GET | List CSS templates | No |
| **SettingsPage** | `/api/v1/export/rules` | GET | Manage export rules | No |

---

## Component Tree Structure

```
App
├── Router (React Router)
│   ├── PublicRoute
│   │   └── LoginPage
│   │       ├── Form (username + password)
│   │       ├── Button (submit)
│   │       └── Alert (error display)
│   └── ProtectedRoute (requires authentication)
│       └── Layout
│           ├── Sidebar
│           │   ├── Logo
│           │   ├── Navigation Links
│           │   │   ├── UploadPage link
│           │   │   ├── ProcessingPage link
│           │   │   ├── ResultsPage link
│           │   │   ├── ExportPage link
│           │   │   └── SettingsPage link
│           │   └── User Section + Logout
│           ├── TopBar
│           │   ├── SearchInput
│           │   └── NotificationBell
│           └── MainContent (Outlet)
│               ├── UploadPage
│               │   ├── FileUpload (react-dropzone)
│               │   ├── FileList (selected files)
│               │   └── UploadButton
│               ├── ProcessingPage
│               │   ├── ProgressBar
│               │   ├── StatsCards (completed/processing/failed)
│               │   ├── FileStatusList
│               │   └── ActionButtons
│               ├── ResultsPage
│               │   ├── FileList (left sidebar)
│               │   │   ├── SearchInput
│               │   │   └── FileItems
│               │   └── PreviewPanel (right)
│               │       ├── StatsCards
│               │       ├── Tabs (Markdown/JSON)
│               │       ├── MarkdownPreview
│               │       └── JSONViewer
│               ├── ExportPage
│               │   ├── FormatSelector
│               │   ├── RuleSelector
│               │   ├── CSSTemplateSelector
│               │   ├── OptionsForm
│               │   └── ExportButton
│               └── SettingsPage
│                   ├── UserInfo
│                   ├── ExportRulesManager
│                   │   ├── RuleList
│                   │   ├── CreateRuleDialog
│                   │   ├── EditRuleDialog
│                   │   └── DeleteConfirmDialog
│                   └── SystemSettings
```

---

## State Management Strategy

### Client State (Zustand)

**authStore.ts** - Authentication State
```typescript
interface AuthState {
  user: User | null
  isAuthenticated: boolean
  setUser: (user: User | null) => void
  logout: () => void
}
```

**uploadStore.ts** - Upload Batch State
```typescript
interface UploadState {
  batchId: number | null
  files: FileInfo[]
  uploadProgress: number
  setBatchId: (id: number) => void
  setFiles: (files: FileInfo[]) => void
  setUploadProgress: (progress: number) => void
  reset: () => void
}
```

### Server State (React Query)

- **Caching**: Automatic caching with stale-while-revalidate strategy
- **Polling**: Automatic refetch for batch status every 2 seconds during processing
- **Error Handling**: Built-in error retry and error state management
- **Optimistic Updates**: For export rules CRUD operations

### Query Keys

```typescript
// Batch status polling
['batchStatus', batchId]

// OCR result for specific file
['ocrResult', fileId]

// Export rules list
['exportRules']

// CSS templates list
['cssTemplates']
```

---

## Route Configuration

| Route | Component | Access Level | Description | Protected |
|-------|-----------|--------------|-------------|-----------|
| `/login` | LoginPage | Public | User authentication | No |
| `/` | Layout (redirect to /upload) | Private | Main layout wrapper | Yes |
| `/upload` | UploadPage | Private | File upload interface | Yes |
| `/processing` | ProcessingPage | Private | OCR processing status | Yes |
| `/results` | ResultsPage | Private | View OCR results | Yes |
| `/export` | ExportPage | Private | Export configuration | Yes |
| `/settings` | SettingsPage | Private | User settings | Yes |

### Protected Route Implementation

```typescript
function ProtectedRoute({ children }: { children: React.ReactNode }) {
  const isAuthenticated = useAuthStore((state) => state.isAuthenticated)

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

  return <>{children}</>
}
```

---

## API Integration Patterns

### API Client Configuration

**Base URL**: `http://localhost:12010/api/v1`

**Request Interceptor**: Adds JWT token to Authorization header

```typescript
this.client.interceptors.request.use((config) => {
  if (this.token) {
    config.headers.Authorization = `Bearer ${this.token}`
  }
  return config
})
```

**Response Interceptor**: Handles 401 errors and redirects to login

```typescript
this.client.interceptors.response.use(
  (response) => response,
  (error: AxiosError<ApiError>) => {
    if (error.response?.status === 401) {
      this.clearToken()
      window.location.href = '/login'
    }
    return Promise.reject(error)
  }
)
```

### Authentication Flow

```typescript
// 1. Login
const response = await apiClient.login({ username, password })
// Response: { access_token, token_type, expires_in }

// 2. Store token
localStorage.setItem('auth_token', response.access_token)

// 3. Set user in store
setUser({ id: 1, username })

// 4. Navigate to /upload
navigate('/upload')
```

### File Upload Flow

```typescript
// 1. Prepare FormData
const formData = new FormData()
files.forEach((file) => formData.append('files', file))

// 2. Upload files
const response = await apiClient.uploadFiles(files)
// Response: { batch_id, files: FileInfo[] }

// 3. Store batch info
setBatchId(response.batch_id)
setFiles(response.files)

// 4. Navigate to /processing
navigate('/processing')
```

### OCR Processing Flow

```typescript
// 1. Start OCR processing
await apiClient.processOCR({ batch_id, lang: 'ch', detect_layout: true })
// Response: { message, batch_id, total_files, status }

// 2. Poll batch status every 2 seconds
const { data: batchStatus } = useQuery({
  queryKey: ['batchStatus', batchId],
  queryFn: () => apiClient.getBatchStatus(batchId),
  refetchInterval: (query) => {
    const status = query.state.data?.batch.status
    if (status === 'completed' || status === 'failed') return false
    return 2000 // Poll every 2 seconds
  },
})

// 3. Auto-redirect when completed
useEffect(() => {
  if (batchStatus?.batch.status === 'completed') {
    navigate('/results')
  }
}, [batchStatus?.batch.status])
```

### Results Viewing Flow

```typescript
// 1. Load batch status
const { data: batchStatus } = useQuery({
  queryKey: ['batchStatus', batchId],
  queryFn: () => apiClient.getBatchStatus(batchId),
})

// 2. Select a file
setSelectedFileId(fileId)

// 3. Load OCR result for selected file
const { data: ocrResult } = useQuery({
  queryKey: ['ocrResult', selectedFileId],
  queryFn: () => apiClient.getOCRResult(selectedFileId),
  enabled: !!selectedFileId,
})

// 4. Display in Markdown or JSON format
<Tabs>
  <TabsContent value="markdown">
    <ReactMarkdown>{ocrResult.markdown_content}</ReactMarkdown>
  </TabsContent>
  <TabsContent value="json">
    <pre>{JSON.stringify(ocrResult.json_data, null, 2)}</pre>
  </TabsContent>
</Tabs>
```

### Export Flow

```typescript
// 1. Select export format and options
const exportData = {
  batch_id: batchId,
  format: 'pdf',
  rule_id: selectedRuleId,
  css_template: 'academic',
  options: { include_metadata: true }
}

// 2. Request export
const blob = await apiClient.exportResults(exportData)

// 3. Trigger download
downloadBlob(blob, `ocr-results-${batchId}.pdf`)
```

---

## UI/UX Design System

### Color Palette (CSS Variables)

```css
/* Primary - Professional Blue */
--primary: 217 91% 60%;           /* #3b82f6 */
--primary-foreground: 0 0% 100%;

/* Secondary - Gray-Blue */
--secondary: 220 15% 95%;
--secondary-foreground: 220 15% 25%;

/* Accent - Vibrant Teal */
--accent: 173 80% 50%;
--accent-foreground: 0 0% 100%;

/* Success */
--success: 142 72% 45%;           /* #16a34a */
--success-foreground: 0 0% 100%;

/* Destructive */
--destructive: 0 85% 60%;         /* #ef4444 */
--destructive-foreground: 0 0% 100%;

/* Warning */
--warning: 38 92% 50%;
--warning-foreground: 0 0% 100%;

/* Background */
--background: 220 15% 97%;        /* #fafafa */
--card: 0 0% 100%;                /* #ffffff */
--sidebar: 220 25% 12%;           /* Dark blue-gray */

/* Borders */
--border: 220 13% 88%;
--radius: 0.5rem;
```

### Typography

- **Font Family**: System font stack (native)
- **Page Title**: 1.875rem (30px), font-weight: 700
- **Section Title**: 1.125rem (18px), font-weight: 600
- **Body Text**: 0.875rem (14px), font-weight: 400
- **Small Text**: 0.75rem (12px)

### Spacing Scale

```css
--spacing-xs: 0.25rem;   /* 4px */
--spacing-sm: 0.5rem;    /* 8px */
--spacing-md: 1rem;      /* 16px */
--spacing-lg: 1.5rem;    /* 24px */
--spacing-xl: 2rem;      /* 32px */
```

### Component Variants

**Button Variants**:
- `default`: Primary blue background
- `outline`: Border only
- `secondary`: Muted background
- `destructive`: Red for delete actions
- `ghost`: No background, hover effect

**Alert Variants**:
- `default`: Neutral gray
- `info`: Blue
- `success`: Green
- `warning`: Yellow
- `destructive`: Red

**Badge Variants**:
- `default`: Gray
- `success`: Green
- `warning`: Yellow
- `destructive`: Red
- `secondary`: Muted

### Responsive Breakpoints

```typescript
// Tailwind breakpoints
sm: '640px',    // Mobile landscape
md: '768px',    // Tablet
lg: '1024px',   // Desktop (primary support)
xl: '1280px',   // Large desktop
2xl: '1536px'   // Extra large
```

**Primary Support**: Desktop (>= 1024px)
**Secondary Support**: Tablet (768px - 1023px)
**Optional**: Mobile (< 768px)

---

## Error Handling Patterns

### Global Error Boundary

```typescript
class ErrorBoundary extends Component<Props, State> {
  static getDerivedStateFromError(error: Error): State {
    return { hasError: true, error }
  }

  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
    console.error('Uncaught error:', error, errorInfo)
  }

  render() {
    if (this.state.hasError) {
      return <ErrorFallbackUI error={this.state.error} />
    }
    return this.props.children
  }
}
```

### API Error Handling

```typescript
try {
  await apiClient.uploadFiles(files)
} catch (err: any) {
  const errorDetail = err.response?.data?.detail

  toast({
    title: t('upload.uploadError'),
    description: Array.isArray(errorDetail)
      ? errorDetail.map(e => e.msg || e.message).join(', ')
      : errorDetail || t('errors.networkError'),
    variant: 'destructive',
  })
}
```

### Form Validation

```typescript
// Client-side validation
if (selectedFiles.length === 0) {
  toast({
    title: t('errors.validationError'),
    description: '請選擇至少一個檔案',
    variant: 'destructive',
  })
  return
}

// Backend validation errors
if (err.response?.status === 422) {
  const errors = err.response.data.detail
  // Display validation errors to user
}
```

### Loading States

```typescript
// Query loading state
const { data, isLoading, error } = useQuery({
  queryKey: ['batchStatus', batchId],
  queryFn: () => apiClient.getBatchStatus(batchId),
})

if (isLoading) return <LoadingSpinner />
if (error) return <ErrorAlert error={error} />
if (!data) return <EmptyState />

// Mutation loading state
const mutation = useMutation({
  mutationFn: apiClient.uploadFiles,
  onSuccess: () => { /* success */ },
  onError: () => { /* error */ },
})

<Button disabled={mutation.isPending}>
  {mutation.isPending ? <Loader2 className="animate-spin" /> : '上傳'}
</Button>
```

---

## Deployment Configuration

### Environment Variables

```bash
# .env.production
VITE_API_BASE_URL=http://localhost:12010
VITE_APP_NAME=Tool_OCR
VITE_APP_VERSION=0.1.0
```

### Build Configuration

**vite.config.ts**:
```typescript
export default defineConfig({
  plugins: [react()],
  server: {
    port: 12011,
    proxy: {
      '/api': {
        target: 'http://localhost:12010',
        changeOrigin: true,
      },
    },
  },
  build: {
    outDir: 'dist',
    sourcemap: false,
    rollupOptions: {
      output: {
        manualChunks: {
          vendor: ['react', 'react-dom', 'react-router-dom'],
          ui: ['@tanstack/react-query', 'zustand', 'lucide-react'],
        },
      },
    },
  },
})
```

### Build Commands

```bash
# Development
npm run dev

# Production build
npm run build

# Preview production build
npm run preview
```

### Nginx Configuration

```nginx
server {
    listen 80;
    server_name tool-ocr.example.com;
    root /path/to/Tool_OCR/frontend/dist;

    # Frontend static files
    location / {
        try_files $uri $uri/ /index.html;
    }

    # API reverse proxy
    location /api {
        proxy_pass http://127.0.0.1:12010;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    # Static assets caching
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}
```

---

## Performance Optimization

### Code Splitting

- **Vendor Bundle**: React, React Router, React Query (separate chunk)
- **UI Bundle**: Zustand, Lucide React, UI components
- **Route-based Splitting**: Lazy load pages with `React.lazy()`

### Caching Strategy

- **React Query Cache**: 5 minutes stale time for most queries
- **Polling Interval**: 2 seconds during OCR processing
- **Infinite Cache**: Export rules (rarely change)

### Asset Optimization

- **Images**: Convert to WebP format, use appropriate sizes
- **Fonts**: System font stack (no custom fonts)
- **Icons**: Lucide React (tree-shakeable)

---

## Testing Strategy

### Component Testing (Planned)

```typescript
// Example: UploadPage.test.tsx
import { render, screen, fireEvent } from '@testing-library/react'
import { UploadPage } from '@/pages/UploadPage'

describe('UploadPage', () => {
  it('should display file upload area', () => {
    render(<UploadPage />)
    expect(screen.getByText(/拖放檔案/i)).toBeInTheDocument()
  })

  it('should allow file selection', async () => {
    render(<UploadPage />)
    const file = new File(['content'], 'test.pdf', { type: 'application/pdf' })
    // Test file upload
  })
})
```

### API Integration Testing

- **Mock API Responses**: Use MSW (Mock Service Worker)
- **Error Scenarios**: Test 401, 404, 500 responses
- **Loading States**: Test skeleton/spinner display

---

## Accessibility Standards

### WCAG 2.1 AA Compliance

- **Keyboard Navigation**: All interactive elements accessible via keyboard
- **Focus Indicators**: Visible focus states on all inputs and buttons
- **ARIA Labels**: Proper labels for screen readers
- **Color Contrast**: Minimum 4.5:1 ratio for text
- **Alt Text**: All images have descriptive alt attributes

### Semantic HTML

```typescript
// Use semantic elements
<nav>      // Navigation
<main>     // Main content
<aside>    // Sidebar
<article>  // Independent content
<section>  // Grouped content
```

---

## Browser Compatibility

### Minimum Supported Versions

- **Chrome**: 90+
- **Firefox**: 88+
- **Edge**: 90+
- **Safari**: 14+

### Polyfills Required

- None (modern build target: ES2020)

---

## Development Workflow

### Local Development

```bash
# 1. Install dependencies
npm install

# 2. Start dev server
npm run dev
# Frontend: http://localhost:12011
# API Proxy: http://localhost:12011/api -> http://localhost:12010/api

# 3. Build for production
npm run build

# 4. Preview production build
npm run preview
```

### Code Style

- **Formatter**: Prettier (automatic on save)
- **Linter**: ESLint
- **Type Checking**: TypeScript strict mode

---

## Known Issues & Limitations

### Current Limitations

1. **No Real-time WebSocket**: Uses HTTP polling for progress updates
2. **No Offline Support**: Requires active internet connection
3. **No Mobile Optimization**: Primarily designed for desktop/tablet
4. **Translation Feature Stub**: Planned for Phase 5
5. **File Size Limit**: Frontend validates 50MB per file, backend may differ

### Future Improvements

- [ ] Implement WebSocket for real-time updates
- [ ] Add dark mode toggle
- [ ] Mobile responsive design
- [ ] Implement translation feature
- [ ] Add E2E tests with Playwright
- [ ] PWA support for offline capability

---

## Maintenance & Updates

### Update Checklist

When updating API contracts:
1. Update TypeScript types in `@/types/api.ts`
2. Update API client methods in `@/services/api.ts`
3. Update this documentation (FRONTEND_API.md)
4. Update corresponding page components
5. Test integration thoroughly

### Dependency Updates

```bash
# Check for updates
npm outdated

# Update dependencies
npm update

# Update to latest (breaking changes possible)
npm install <package>@latest
```

---

## Contact & Support

**Frontend Developer**: Claude Code
**Documentation Version**: 0.1.0
**Last Updated**: 2025-01-13

For API questions, refer to:
- `API_REFERENCE.md` - Complete API documentation
- `backend_api.md` - Backend implementation details
- FastAPI Swagger UI: `http://localhost:12010/docs`

---

**End of Documentation**