Add PDF translation API, utilities, docs, and config

Introduces core backend and frontend infrastructure for a PDF translation interface. Adds API endpoints for translation, PDF testing, and AI provider testing; implements PDF text extraction, cost tracking, and pricing logic in the lib directory; adds reusable UI components; and provides comprehensive documentation (SDD, environment setup, Claude instructions). Updates Tailwind and global styles, and includes a sample test PDF and configuration files.
2025-10-15 23:34:44 +08:00
parent c899702d51
commit 39a4788cc4
21 changed files with 11041 additions and 251 deletions
--- a/SDD.md
+++ b/SDD.md
@@ -0,0 +1,569 @@
+# 軟體設計文件 (Software Design Document)
+
+## 1. 系統概述
+
+### 1.1 專案名稱
+PDF Translation Interface - PDF 翻譯介面系統
+
+### 1.2 專案目標
+提供一個基於網頁的 PDF 文件翻譯平台，讓使用者能夠上傳 PDF 文件並將其內容翻譯成多種語言。
+
+### 1.3 系統範圍
+- PDF 文件上傳功能（拖拽上傳支援）
+- 多層文字擷取處理（pdf-parse → pdf2json 備援）
+- OCR 光學字元識別（支援掃描型 PDF）
+- AI 驅動的多語言翻譯（DeepSeek + OpenAI 備援）
+- 翻譯後 PDF 檔案生成與下載（智慧中文字元處理）
+- 翻譯文字檔案下載功能
+- 語音播放功能（多語音選擇、速度控制）
+- Token 使用量與費用追蹤系統
+- 文清楓風格響應式網頁介面（RWD）
+
+## 2. 系統架構
+
+### 2.1 技術堆疊
+
+#### 前端技術
+- **框架**: Next.js 15.2.4 (App Router)
+- **UI 庫**: React 19.0.0
+- **程式語言**: TypeScript 5
+- **樣式系統**: Tailwind CSS v4.1.9
+- **元件庫**: shadcn/ui + Radix UI
+- **圖標**: Lucide React
+- **語音合成**: Web Speech API (SpeechSynthesis)
+- **設計風格**: 文清楓自然風格（琥珀-綠-青漸變）
+- **響應式設計**: 完整 RWD 支援（手機/平板/桌面）
+
+#### 後端技術
+- **執行環境**: Node.js
+- **API 框架**: Next.js API Routes
+- **PDF 處理**: pdf-parse (主要) → pdf2json (備援) → pdfjs-dist (進階)
+- **OCR 引擎**: Tesseract.js (多語言支援)
+- **PDF 生成**: PDFKit + fontkit (Unicode 字體支援)
+- **AI 整合**: Vercel AI SDK
+- **AI 模型**: 
+  - DeepSeek Chat (預設)
+  - OpenAI GPT-4o-mini (備選)
+- **費用追蹤**: 本地儲存式 Token 計算與費用統計
+- **中文處理**: WinAnsi 編碼處理與智慧後備機制
+
+#### 部署與基礎設施
+- **部署平台**: Vercel
+- **版本控制**: Git
+- **套件管理**: npm/pnpm
+
+### 2.2 系統架構圖
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   使用者瀏覽器                        │
+│  ┌────────────────────────────────────────────┐    │
+│  │         React 前端應用程式                    │    │
+│  │  ├─ PDF 上傳元件                            │    │
+│  │  ├─ 語言選擇器                              │    │
+│  │  └─ 翻譯結果顯示                            │    │
+│  └────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────┘
+                           │
+                           │ HTTPS
+                           ▼
+┌─────────────────────────────────────────────────────┐
+│                 Next.js 伺服器                       │
+│  ┌────────────────────────────────────────────┐    │
+│  │         API 路由 (/api/translate)           │    │
+│  │  ├─ PDF 接收與驗證                          │    │
+│  │  ├─ 文字擷取處理                            │    │
+│  │  └─ AI 翻譯服務呼叫                        │    │
+│  └────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────┘
+                           │
+                           │ API
+                           ▼
+┌─────────────────────────────────────────────────────┐
+│         AI 翻譯服務 (DeepSeek / OpenAI)              │
+└─────────────────────────────────────────────────────┘
+                           ▲
+                           │
+┌─────────────────────────────────────────────────────┐
+│              OCR 服務 (Tesseract.js)                 │
+└─────────────────────────────────────────────────────┘
+```
+
+## 3. 元件設計
+
+### 3.1 前端元件結構
+
+```
+/components
+├── /ui                          # 基礎 UI 元件
+│   ├── button.tsx              # 按鈕元件
+│   ├── card.tsx                # 卡片容器
+│   ├── select.tsx              # 下拉選單
+│   ├── textarea.tsx            # 文字輸入區
+│   └── alert-dialog.tsx        # 警告對話框
+│
+├── pdf-translator.tsx          # 主要應用程式元件
+└── theme-provider.tsx          # 主題管理元件
+```
+
+### 3.2 主要元件功能
+
+#### PDFTranslator 元件
+**責任**：協調整個翻譯工作流程
+- 檔案上傳處理
+- 語言選擇管理
+- API 呼叫協調
+- 結果顯示與下載
+
+**狀態管理**：
+```typescript
+- file: File | null              // 上傳的 PDF 檔案
+- sourceLanguage: string          // 來源語言
+- targetLanguage: string          // 目標語言
+- isTranslating: boolean          // 翻譯進行狀態
+- translatedText: string          // 翻譯結果
+- translatedPDFBase64: string     // 翻譯後的 PDF Base64
+- isDragging: boolean             // 拖拽狀態
+- generatePDF: boolean            // 是否生成 PDF
+- tokenUsage: any                 // Token 使用量統計
+- cost: any                       // 單次翻譯費用
+- model: any                      // 使用的 AI 模型資訊
+- costSummary: CostSummary        // 累積費用統計
+
+// 語音播放相關狀態
+- isPlaying: boolean              // 語音播放狀態
+- isPaused: boolean               // 語音暫停狀態
+- speechSupported: boolean        // 瀏覽器語音支援
+- selectedVoice: string           // 選擇的語音
+- availableVoices: SpeechSynthesisVoice[] // 可用語音列表
+- speechRate: number              // 播放速度
+- speechVolume: number            // 播放音量
+```
+
+### 3.3 API 設計
+
+#### POST /api/translate
+**請求格式**：
+```typescript
+{
+  file: File,                    // PDF 檔案
+  sourceLanguage: string,         // 來源語言代碼
+  targetLanguage: string          // 目標語言代碼
+}
+```
+
+**回應格式**：
+```typescript
+{
+  translatedText: string,         // 翻譯後的文字
+  pdfBase64?: string,            // 翻譯後的 PDF (Base64)
+  tokenUsage?: {
+    prompt: number,              // 輸入 Token 數
+    completion: number,          // 輸出 Token 數
+    total: number,              // 總 Token 數
+    formattedCounts: {
+      prompt: string,
+      completion: string,
+      total: string
+    }
+  },
+  cost?: {
+    inputCost: number,           // 輸入費用
+    outputCost: number,          // 輸出費用
+    totalCost: number,           // 總費用
+    formattedCost: string,       // 格式化費用顯示
+    currency: string             // 貨幣單位
+  },
+  model?: {
+    name: string,               // 模型名稱
+    provider: string,           // 提供者
+    displayName: string         // 顯示名稱
+  },
+  costSession?: CostSession      // 費用追蹤會話
+}
+```
+
+**錯誤處理**：
+- 400: 無效的請求參數
+- 413: 檔案太大
+- 500: 內部伺服器錯誤
+
+## 4. 資料流程
+
+### 4.1 翻譯流程
+
+```
+1. 使用者上傳 PDF
+   └─> 檔案驗證 (類型、大小)
+   
+2. 選擇來源與目標語言
+   └─> 表單驗證
+   
+3. 提交翻譯請求
+   └─> FormData 封裝
+   └─> POST /api/translate
+   
+4. 後端處理
+   └─> 接收檔案
+   └─> 多層文字擷取策略
+       ├─> 主要: 使用 pdf-parse 擷取文字
+       ├─> 備援: pdf2json 解析（處理特殊編碼）
+       └─> 最終: pdfjs-dist 進階處理
+   └─> 文字預處理與分段
+   └─> 呼叫 AI 翻譯 API (DeepSeek/OpenAI)
+   └─> Token 使用量計算與費用追蹤
+   └─> 整合翻譯結果
+   
+5. 生成輸出檔案
+   └─> 智慧 PDF 生成（處理中文字元編碼）
+   └─> WinAnsi 編碼限制處理
+   └─> 中文字元後備描述系統
+   └─> Unicode 字體支援
+   
+6. 顯示結果
+   └─> 更新 UI（文清楓風格）
+   └─> Token 使用量與費用顯示
+   └─> 累積費用統計更新
+   └─> 語音播放功能啟用
+   └─> 提供下載選項
+       ├─> 下載翻譯後 PDF
+       └─> 下載純文字檔案
+   └─> 語音播放控制
+       ├─> 播放/暫停/停止
+       ├─> 語音選擇
+       └─> 速度調整
+```
+
+### 4.2 PDF 處理流程
+
+#### 4.2.1 文字型 PDF 處理（多層備援）
+```
+輸入: PDF 檔案
+  │
+  ├─> 第一層: pdf-parse 解析
+  │   ├─> 成功: 擷取文字內容
+  │   └─> 失敗: 進入第二層
+  │
+  ├─> 第二層: pdf2json 解析
+  │   ├─> 成功: 解碼 URI 編碼文字
+  │   └─> 失敗: 進入第三層
+  │
+  ├─> 第三層: pdfjs-dist 解析
+  │   ├─> 成功: 進階文字擷取
+  │   └─> 失敗: 回報錯誤
+  │
+  ├─> 文字長度與品質檢查
+  ├─> 保留段落結構
+  └─> 傳送至翻譯 API
+```
+
+#### 4.2.2 掃描型 PDF 處理 (OCR)
+```
+輸入: 掃描的 PDF 檔案
+  │
+  ├─> 將 PDF 轉換為圖片
+  ├─> 每頁進行 OCR 識別
+  │   ├─> 語言偵測
+  │   ├─> 文字區域識別
+  │   └─> 文字擷取
+  ├─> 合併所有頁面文字
+  ├─> 文字校正與優化
+  └─> 傳送至翻譯 API
+```
+
+### 4.3 翻譯後 PDF 生成流程（智慧中文處理）
+```
+翻譯完成的文字
+  │
+  ├─> 中文字元檢測
+  ├─> 智慧 PDF 生成策略
+  │   ├─> 中文內容: 使用後備描述系統
+  │   │   ├─> WinAnsi 編碼限制處理
+  │   │   ├─> 生成內容描述
+  │   │   └─> 添加重要提示
+  │   └─> 非中文: 標準 PDF 生成
+  │
+  ├─> 使用 PDFKit + fontkit
+  │   ├─> Unicode 字體支援
+  │   ├─> 標準字體後備
+  │   └─> 錯誤處理機制
+  │
+  ├─> 頁面佈局與格式
+  │   ├─> 標題與語言資訊
+  │   ├─> 重要提示區域
+  │   └─> 內容區域分頁
+  │
+  └─> Base64 編碼輸出
+```
+
+## 5. 介面設計
+
+### 5.1 使用者介面流程
+
+```
+┌────────────────┐     ┌────────────────┐     ┌────────────────┐
+│   檔案上傳      │ --> │   語言選擇      │ --> │   開始翻譯      │
+└────────────────┘     └────────────────┘     └────────────────┘
+                                                      │
+                                                      ▼
+┌────────────────┐     ┌────────────────┐     ┌────────────────┐
+│   下載結果      │ <-- │   顯示翻譯      │ <-- │   處理中...     │
+└────────────────┘     └────────────────┘     └────────────────┘
+```
+
+### 5.2 響應式設計（文清楓風格）
+- **桌面版** (xl:grid-cols-2)：雙欄佈局 (上傳區 | 結果區)
+  - 寬敞間距 (p-8, gap-8)
+  - 完整文字與圖標顯示
+  - 琥珀-綠-青漸變背景
+  
+- **平板版** (lg)：單欄佈局，適中間距
+  - 中等間距 (p-6, gap-6)
+  - 保持主要功能文字
+  - 優化觸控目標大小
+  
+- **手機版** (sm)：縱向堆疊，緊湊佈局
+  - 緊湊間距 (p-4, gap-4)
+  - 圖標化界面 (隱藏部分文字)
+  - 按鈕與控制項優化
+  - 垂直排列下載按鈕
+  
+### 5.3 文清楓設計特色
+- **自然色彩**: 琥珀(amber) → 綠(green) → 青(teal)漸變
+- **裝飾元素**: 半透明背景圓圈、表情符號點綴
+- **卡片設計**: 毛玻璃效果 (backdrop-blur-sm)
+- **漸變邊框**: 各功能區域協調色彩變化
+
+## 6. 安全性考量
+
+### 6.1 輸入驗證
+- 檔案類型限制 (僅 PDF)
+- 檔案大小限制
+- 語言代碼驗證
+- XSS 防護
+
+### 6.2 API 安全
+- API 金鑰環境變數管理
+- Rate limiting (建議實作)
+- CORS 配置
+- HTTPS 加密傳輸
+
+### 6.3 隱私保護
+- 不儲存使用者檔案
+- 不記錄翻譯內容
+- 僅記錄匿名使用統計
+
+## 7. 核心功能實作細節
+
+### 7.1 PDF 文字擷取實作
+```javascript
+// 使用 pdf-parse 套件
+import pdf from 'pdf-parse'
+
+async function extractTextFromPDF(buffer: Buffer) {
+  const data = await pdf(buffer)
+  return {
+    text: data.text,
+    numPages: data.numpages,
+    info: data.info
+  }
+}
+```
+
+### 7.2 OCR 文字識別實作
+```javascript
+// 使用 Tesseract.js
+import Tesseract from 'tesseract.js'
+
+async function performOCR(imageBuffer: Buffer, language: string) {
+  const result = await Tesseract.recognize(
+    imageBuffer,
+    language,
+    {
+      logger: m => console.log(m)
+    }
+  )
+  return result.data.text
+}
+```
+
+### 7.3 翻譯後 PDF 生成實作
+```javascript
+// 使用 PDFKit
+import PDFDocument from 'pdfkit'
+
+function generateTranslatedPDF(translatedText: string, metadata: any) {
+  const doc = new PDFDocument()
+  
+  // 設定字體支援多語言
+  doc.font('fonts/NotoSansCJK.ttf')
+  
+  // 加入翻譯文字
+  doc.text(translatedText, {
+    align: 'left',
+    lineGap: 5
+  })
+  
+  return doc
+}
+```
+
+## 8. 效能優化
+
+### 8.1 前端優化
+- 元件懶加載
+- 圖片優化
+- CSS 最小化
+- Tree shaking
+- 大檔案分片上傳
+
+### 8.2 後端優化
+- API 回應快取
+- 串流處理大檔案
+- 非同步處理
+- 批次處理多頁 PDF
+- OCR 結果快取
+
+## 9. 支援的語言
+
+系統支援以下 16 種語言的雙向翻譯：
+
+1. 自動偵測 (auto) - 僅限來源語言
+2. 繁體中文 (zh-TW) 🎤
+3. 簡體中文 (zh-CN) 🎤
+4. 英語 (en) 🎤
+5. 日語 (ja) 🎤
+6. 韓語 (ko) 🎤
+7. 西班牙語 (es) 🎤
+8. 法語 (fr) 🎤
+9. 德語 (de) 🎤
+10. 義大利語 (it) 🎤
+11. 葡萄牙語 (pt) 🎤
+12. 俄語 (ru) 🎤
+13. 阿拉伯語 (ar) 🎤
+14. 印地語 (hi) 🎤
+15. 泰語 (th) 🎤
+16. 越南語 (vi) 🎤
+
+🎤 = 支援語音播放功能（根據瀏覽器可用語音）
+
+### 9.1 語音播放支援
+- **Web Speech API**: 瀏覽器原生語音合成
+- **多語音選擇**: 根據目標語言自動篩選
+- **語音控制**: 播放、暫停、停止、速度調整
+- **語音品質**: 依瀏覽器與系統語音包而定
+
+## 10. 部署架構
+
+### 10.1 Vercel 部署配置
+```javascript
+{
+  buildCommand: "npm run build",
+  outputDirectory: ".next",
+  installCommand: "npm install",
+  framework: "nextjs"
+}
+```
+
+### 10.2 環境變數
+```
+# AI 服務提供者選擇
+AI_PROVIDER=deepseek  # 或 openai
+
+# DeepSeek 配置
+DEEPSEEK_API_KEY=sk-xxxxxxxxxxxx
+DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
+DEEPSEEK_MODEL=deepseek-chat
+
+# OpenAI 配置（備選）
+OPENAI_API_KEY=sk-xxxxxxxxxxxx
+OPENAI_MODEL=gpt-4o-mini
+
+# 應用程式設定
+NODE_ENV=production
+MAX_FILE_SIZE=10485760  # 10MB
+
+# 費用追蹤設定
+ENABLE_COST_TRACKING=true
+DEFAULT_CURRENCY=USD
+
+# PDF 處理設定
+PDF_PROCESSING_TIMEOUT=30000  # 30秒
+OCR_LANGUAGE_DEFAULT=chi_tra+eng
+```
+
+## 11. 未來擴展計畫
+
+### 11.1 功能增強
+- [ ] 批次檔案處理
+- [ ] 保留 PDF 格式輸出
+- [ ] 翻譯歷史記錄
+- [ ] 使用者帳號系統
+- [ ] 自訂詞彙表
+
+### 11.2 技術改進
+- [✓] 實作多層 PDF 解析（pdf-parse → pdf2json → pdfjs-dist）
+- [✓] 整合 OCR 功能（使用 Tesseract.js）
+- [✓] 智慧 PDF 生成（PDFKit + 中文字元處理）
+- [✓] 整合多個 AI 模型（DeepSeek + OpenAI）
+- [✓] Token 使用量與費用追蹤系統
+- [✓] 語音播放功能（多語音、速度控制）
+- [✓] 文清楓風格響應式設計
+- [✓] 拖拽上傳功能
+- [✓] 累積費用統計與重置
+- [ ] 添加進度條顯示
+- [ ] 實作檔案分塊處理
+- [ ] 添加翻譯品質評分
+- [ ] 添加更多 OCR 語言支援
+
+### 11.3 效能優化
+- [ ] 實作 Redis 快取
+- [ ] CDN 整合
+- [ ] 工作佇列系統
+- [ ] 資料庫整合
+
+## 12. 測試策略
+
+### 12.1 單元測試
+- 元件渲染測試
+- 函數邏輯測試
+- API 端點測試
+- PDF 處理測試
+  - 文字型 PDF 擷取
+  - OCR 識別測試
+  - PDF 生成測試
+
+### 12.2 整合測試
+- 檔案上傳流程
+- 翻譯流程測試
+- 錯誤處理測試
+
+### 12.3 端對端測試
+- 完整使用者流程
+- 跨瀏覽器測試
+- 響應式設計測試
+
+## 13. 維護與監控
+
+### 13.1 日誌記錄
+- 錯誤日誌
+- 效能指標
+- 使用統計
+
+### 13.2 監控指標
+- API 回應時間
+- 翻譯成功率
+- 系統可用性
+- 使用者活躍度
+
+## 14. 文件與支援
+
+### 14.1 開發文件
+- API 文件
+- 元件文件
+- 部署指南
+
+### 14.2 使用者文件
+- 使用教學
+- 常見問題
+- 疑難排解指南