# 軟體設計文件 (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 使用者文件
- 使用教學
- 常見問題
- 疑難排解指南