OCR/FRONTEND_QUICK_REFERENCE.md

Tool_OCR 前端快速參考指南

文件位置速查表

主要文件位置

/Users/egg/Projects/Tool_OCR/frontend/
├── src/
│   ├── App.tsx                    # 路由定義
│   ├── main.tsx                   # 應用入口
│   ├── index.css                  # 全局樣式
│   ├── components/
│   │   ├── ui/                    # UI 組件庫
│   │   ├── Layout.tsx             # 主佈局
│   │   ├── FileUpload.tsx         # 文件上傳
│   │   └── ...
│   ├── pages/                     # 頁面
│   ├── store/                     # 狀態管理
│   ├── services/api.ts            # API 客戶端
│   ├── types/api.ts               # 類型定義
│   ├── i18n/                      # 國際化
│   └── lib/utils.ts               # 工具函數
├── vite.config.ts                 # Vite 配置
├── tailwind.config.js             # Tailwind 配置
├── tsconfig.json                  # TypeScript 配置
└── package.json                   # 依賴管理

---

技術棧速查

功能	技術	版本
UI 框架	React	19.2.0
語言	TypeScript	5.9.3
構建	Vite	7.2.2
樣式	Tailwind CSS	4.1.17
狀態管理	Zustand	5.0.8
數據獲取	React Query	5.90.7
路由	React Router	7.9.5
國際化	i18next	25.6.2
HTTP	Axios	1.13.2
檔案上傳	react-dropzone	14.3.8

---

常用命令

# 開發
cd frontend
npm run dev                        # 啟動開發服務器 (localhost:12011)
npm run lint                       # 代碼檢查
npm run build                      # 生產構建

# 類型檢查
npx tsc --noEmit                  # 檢查 TypeScript 錯誤

# 格式化
npm install -D prettier            # (如果需要)
npx prettier --write src/          # 格式化代碼

---

路由結構

/login                    → LoginPage (公開)
/upload                   → UploadPage (受保護)
/processing               → ProcessingPage (受保護)
/results                  → ResultsPage (受保護)
/export                   → ExportPage (受保護)
/settings                 → SettingsPage (受保護)

添加新路由

// 在 App.tsx 中
<Route path="new-page" element={<NewPage />} />

// 在導航中
{ to: '/new-page', label: t('nav.newPage') }

---

常用代碼片段

使用 i18n 翻譯

const { t } = useTranslation()
<h1>{t('key.path')}</h1>

使用 Zustand 狀態

const { batchId, setBatchId } = useUploadStore()
const { user, logout } = useAuthStore()

調用 API

const data = await apiClient.uploadFiles(files)
const status = await apiClient.getBatchStatus(batchId)

React Query 查詢

const { data, isLoading } = useQuery({
  queryKey: ['key', id],
  queryFn: () => apiClient.getData(id),
})

Tailwind 樣式

className="flex items-center justify-between p-4 bg-card rounded-lg"
className={cn('base', { 'conditional': isActive })}

提示通知

const { toast } = useToast()
toast({
  title: 'Success',
  description: 'Action completed',
  variant: 'success',
})

---

調試技巧

查看存儲在 localStorage 的狀態

// 在瀏覽器控制台
console.log(JSON.parse(localStorage.getItem('auth-storage')))
console.log(JSON.parse(localStorage.getItem('tool-ocr-upload-store')))

查看 React Query 緩存

// 在瀏覽器控制台安裝 React Query DevTools
// npm install @tanstack/react-query-devtools

TypeScript 錯誤

# 運行編譯器檢查類型
npx tsc --noEmit

---

環境變數配置

開發環境 (.env)

VITE_API_BASE_URL=http://localhost:12010

使用環境變數

const baseURL = import.meta.env.VITE_API_BASE_URL

---

常見問題

Q: 如何添加新的頁面？

A:

1. 在 /src/pages 創建 NewPage.tsx
2. 在 App.tsx 添加路由
3. 在 Layout.tsx 導航中添加鏈接

Q: 如何修改主題顏色？

A:

1. 編輯 src/index.css 中的 CSS 變數
2. 或編輯 tailwind.config.js

Q: 如何添加新的翻譯？

A:

1. 編輯 src/i18n/locales/zh-TW.json
2. 在組件中使用 t('key.path')

Q: 如何調試 API 請求？

A:

1. 打開瀏覽器開發者工具 (Network 標籤)
2. 檢查 /api/v1/ 的請求

Q: 上傳文件怎樣無法工作？

A:

1. 檢查後端是否在運行 (localhost:12010)
2. 檢查文件格式是否被支持
3. 檢查文件大小是否超過 50MB

Q: 認證登錄失敗？

A:

1. 檢查用戶名和密碼
2. 檢查後端認證端點 /api/v1/auth/login
3. 檢查 localStorage 中的 token

---

依賴更新

# 檢查過期依賴
npm outdated

# 更新依賴
npm update

# 更新到最新版本
npm install --save-latest package-name

# 清除 node_modules 並重新安裝
rm -rf node_modules package-lock.json
npm install

---

性能優化

代碼分割

import { lazy, Suspense } from 'react'

const NewPage = lazy(() => import('./pages/NewPage'))

// 在 Routes 中
<Suspense fallback={<div>Loading...</div>}>
  <NewPage />
</Suspense>

優化 React Query

const { data } = useQuery({
  queryKey: ['items'],
  queryFn: () => apiClient.getItems(),
  staleTime: 1000 * 60 * 5,        // 5 分鐘內不重新獲取
  gcTime: 1000 * 60 * 10,          // 10 分鐘後從緩存中移除
})

優化組件

// 使用 React.memo 避免不必要的重新渲染
export default React.memo(function MyComponent(props) {
  return <div>{props.data}</div>
})

---

測試 (可選)

# 安裝測試工具
npm install -D vitest @testing-library/react

# 運行測試
npm test

# 生成覆蓋率報告
npm test -- --coverage

---

構建和部署

# 生產構建
npm run build

# 預覽構建
npm run preview

# 構建後的文件位置
# dist/

# 部署
# 將 dist/ 目錄上傳到服務器
# 配置 Web 服務器支持 SPA (所有路由都指向 index.html)

---

貢獻指南

代碼風格

• 使用 TypeScript 進行類型安全
• 遵循現有的命名約定
• 優先使用 Tailwind CSS
• 添加必要的類型定義

提交代碼

# 檢查代碼
npm run lint

# 提交
git add .
git commit -m "description of changes"
git push

---

有用的資源

文檔

• React 文檔
• Tailwind CSS
• React Router
• Zustand
• React Query
• i18next

工具

• Vite 文檔
• TypeScript 文檔
• ESLint 文檔

IDE 擴展 (VS Code)

• Tailwind CSS IntelliSense
• Thunder Client (API 測試)
• React Developer Tools
• Redux DevTools (狀態檢查)

---

快速開始

# 1. 進入前端目錄
cd /Users/egg/Projects/Tool_OCR/frontend

# 2. 安裝依賴
npm install

# 3. 啟動開發服務器
npm run dev

# 4. 打開瀏覽器
# 訪問 http://localhost:12011

# 5. 登錄
# 使用後端提供的帳號密碼

# 6. 開始使用
# 上傳檔案 → 處理 → 查看結果 → 匯出

---

常用快捷鍵

VS Code

• Ctrl+Shift+F (或 Cmd+Shift+F 在 Mac) - 全文搜索
• Ctrl+K Ctrl+X - 刪除行
• Alt+Up/Down - 移動行
• Ctrl+/ - 註解行

瀏覽器開發者工具

• F12 或 Ctrl+Shift+I - 打開開發者工具
• Ctrl+Shift+C - 元素檢查器
• Ctrl+Shift+M - 響應式設計模式

---

總結速記

架構：React 19 + TypeScript + Vite 樣式：Tailwind CSS 4 狀態：Zustand (輕量) + React Query (數據) 路由：React Router v7 API：Axios 單例客戶端 國際化：i18next (繁體中文) 開發端口：12011 後端 API：localhost:12010

核心文件：

• App.tsx (路由)
• main.tsx (入口)
• services/api.ts (API)
• store/*.ts (狀態)
• pages/ (頁面)
• components/ (組件)