aken1023
39a4788cc4
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.
569 lines
17 KiB
Markdown
569 lines
17 KiB
Markdown
# 軟體設計文件 (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 使用者文件
|
||
- 使用教學
|
||
- 常見問題
|
||
- 疑難排解指南 |