Document_Translator/PRD.md

# 產品需求文件 (PRD) - 文件翻譯 Web 系統

## 1. 產品概述

### 1.1 產品名稱
PANJIT Document Translator Web System

### 1.2 產品定位
企業級文件批量翻譯管理系統，提供 Web 化介面，支援多語言文件翻譯、使用者權限管理、任務排隊處理及成本追蹤功能。

### 1.3 目標使用者
- **主要使用者**: PANJIT 公司內部員工
- **管理員**: IT 部門管理人員 (ymirliu@panjit.com.tw)

### 1.4 核心價值
- 將現有桌面版翻譯工具轉換為 Web 服務
- 實現使用者工作隔離，每人只能查看自己的翻譯任務
- 自動化任務排隊與處理
- 完善的通知機制與成本管理

## 2. 功能需求

### 2.1 使用者認證與授權

#### 2.1.1 AD 帳號登入
- **需求描述**: 使用公司 AD (Active Directory) 帳號進行身份驗證
- **技術實現**: 使用 LDAP3 連接公司 AD 服務器
- **驗證流程**:
  1. 使用者輸入 AD 帳號與密碼
  2. 系統透過 LDAP 驗證身份
  3. 成功後建立 Session，記錄使用者資訊
  4. 失敗則顯示錯誤訊息

#### 2.1.2 權限管理
- **一般使用者**: 只能查看和管理自己的翻譯任務
- **管理員** (ymirliu@panjit.com.tw):
  - 查看所有使用者的任務
  - 查看系統使用統計
  - 查看 Dify API 成本報表
  - 管理系統設定

### 2.2 文件上傳與管理

#### 2.2.1 檔案上傳
- **支援格式**: .docx, .doc, .pptx, .xlsx, .xls, .pdf
- **檔案大小限制**: 單檔最大 25MB
- **上傳介面**: 
  - 拖放上傳
  - 點擊選擇檔案
  - 顯示上傳進度

#### 2.2.2 翻譯設定
- **來源語言**: 自動偵測或手動選擇
- **目標語言**: 
  - 支援多選 (如: English, Vietnamese, Traditional Chinese 等)
  - 記憶使用者偏好設定
- **翻譯格式**: 原文下接譯文（交錯排列）

### 2.3 任務排隊與處理

#### 2.3.1 排隊機制
- **排隊規則**: 
  - 按上傳時間順序 (FIFO)
  - 每個任務獲得唯一 UUID
  - 顯示當前排隊位置
- **處理方式**: 單檔依序處理，無並發

#### 2.3.2 任務狀態
- **PENDING**: 等待處理
- **PROCESSING**: 處理中
- **COMPLETED**: 完成
- **FAILED**: 失敗
- **RETRY**: 重試中

#### 2.3.3 錯誤處理與救援機制
- **重試策略**:
  - 最多重試 3 次
  - 重試間隔: 30秒、60秒、120秒
- **錯誤類型處理**:
  - 網路錯誤: 自動重試
  - API 配額超出: 暫停並通知管理員
  - 檔案損壞: 標記失敗並通知使用者
  - Dify 服務中斷: 等待並重試

### 2.4 翻譯處理

#### 2.4.1 翻譯引擎
- **API 服務**: Dify API (配置從 api.txt 讀取)
- **翻譯模式**: 句子級別翻譯並快取
- **快取機制**: 
  - 相同文本不重複翻譯
  - 使用 MySQL 儲存快取

#### 2.4.2 成本追蹤
- **自動記錄**: 從 Dify API response metadata 取得實際使用量
- **成本欄位**:
  - prompt_tokens: 使用的 token 數量
  - prompt_unit_price: 單價
  - prompt_price_unit: 價格單位
  - 總成本自動計算

### 2.5 通知系統

#### 2.5.1 郵件通知
- **SMTP 設定**: 
  - 伺服器: mail.panjit.com.tw
  - 埠號: 25
  - 無需認證
- **通知時機**:
  - 翻譯完成
  - 翻譯失敗
  - 重試超過次數
- **郵件內容**:
  - 檔案名稱
  - 翻譯狀態
  - 下載連結（完成時）
  - 錯誤訊息（失敗時）

### 2.6 檔案下載與清理

#### 2.6.1 檔案下載
- **驗證**: 確認使用者身份
- **格式**: 保持原檔案格式 (.docx, .pptx 等)
- **檔名**: {原檔名}_translated.{副檔名}

#### 2.6.2 自動清理
- **保留期限**: 7 天
- **清理規則**:
  - 每日凌晨執行清理任務
  - 刪除超過 7 天的原檔與譯文
  - 記錄清理日誌

### 2.7 管理功能

#### 2.7.1 統計報表
- **使用量統計**:
  - 每日/週/月 API 呼叫次數
  - 各使用者使用量排行
  - 文件類型分佈
- **成本分析**:
  - Dify API 實際成本（從 metadata 取得）
  - 按使用者的成本分配
  - 成本趨勢圖表

#### 2.7.2 系統監控
- **隊列狀態**: 當前排隊任務數量
- **處理狀態**: 正在處理的任務
- **錯誤監控**: 錯誤率統計
- **API 健康度**: Dify API 連線狀態

#### 2.7.3 管理操作
- **手動重試**: 重試失敗的任務
- **任務管理**: 查看所有任務詳情
- **日誌查看**: 系統操作日誌
- **報表匯出**: Excel 格式匯出

## 3. 非功能需求

### 3.1 效能需求
- **檔案上傳**: 25MB 檔案應在 30 秒內完成上傳
- **API 回應**: 一般 API 請求應在 2 秒內回應
- **翻譯處理**: 依 Dify API 速度，通常每頁 10-30 秒

### 3.2 可用性需求
- **系統可用性**: 99% (排除計畫性維護)
- **錯誤恢復**: 系統異常後應能自動恢復
- **資料持久性**: 任務資料須持久化儲存

### 3.3 安全需求
- **身份驗證**: 必須透過 AD 驗證
- **工作隔離**: 使用者只能存取自己的檔案
- **傳輸安全**: 敏感資料需加密傳輸
- **檔案隔離**: 使用 UUID 建立獨立目錄

### 3.4 相容性需求
- **瀏覽器支援**: Chrome, Edge, Firefox 最新版本
- **作業系統**: Windows 環境優先
- **檔案格式**: 完整支援 Office 2016+ 格式

## 4. 技術規格

### 4.1 後端技術
- **框架**: Flask 3.0+
- **資料庫**: MySQL (使用現有環境)
- **任務隊列**: Celery + Redis
- **認證**: LDAP3
- **檔案處理**: python-docx, python-pptx, openpyxl, PyPDF2

### 4.2 前端技術
- **框架**: Vue 3 + Vite
- **UI 元件**: Element Plus
- **HTTP 客戶端**: Axios
- **路由**: Vue Router

### 4.3 資料庫設計
所有資料表使用 `dt_` 前綴：
- dt_users: 使用者資訊
- dt_translation_jobs: 翻譯任務
- dt_job_files: 檔案記錄
- dt_api_usage_stats: API 使用統計
- dt_system_logs: 系統日誌
- dt_translation_cache: 翻譯快取

### 4.4 API 設計
- **RESTful API**: 遵循 REST 原則
- **認證**: Session-based 或 JWT
- **回應格式**: JSON
- **錯誤處理**: 統一錯誤格式

## 5. 使用者介面

### 5.1 頁面結構
1. **登入頁**: AD 帳號登入表單
2. **首頁/上傳頁**: 檔案上傳與翻譯設定
3. **任務列表**: 個人任務狀態與管理
4. **歷史記錄**: 過去的翻譯記錄
5. **管理後台**: 統計報表（僅管理員）

### 5.2 互動設計
- **即時更新**: 任務狀態即時更新（WebSocket 或輪詢）
- **進度顯示**: 顯示處理進度百分比
- **錯誤提示**: 友善的錯誤訊息
- **操作確認**: 重要操作需二次確認

## 6. 測試需求

### 6.1 單元測試
- API 端點測試
- 服務層邏輯測試
- 工具函數測試

### 6.2 整合測試
- LDAP 認證流程
- 檔案上傳下載流程
- 翻譯任務完整流程
- 郵件通知流程

### 6.3 系統測試
- 壓力測試：多使用者同時上傳
- 錯誤恢復測試
- 自動清理測試

## 7. 部署需求

### 7.1 開發環境
- Python 3.8+
- Node.js 16+
- MySQL 5.7+
- Redis 6+

### 7.2 部署方式
- 開發階段：python app.py + npm run dev
- 生產環境：Gunicorn + Nginx

### 7.3 環境變數
從 .env 檔案讀取：
- 資料庫連線資訊
- LDAP 設定
- SMTP 設定
- API 金鑰（從 api.txt）

## 8. 專案時程

### 第一階段：基礎建設（第 1-2 週）
- 專案架構設計
- 資料庫建立
- 基礎 API 框架
- LDAP 認證實作

### 第二階段：核心功能（第 3-4 週）
- 檔案上傳功能
- 翻譯任務處理
- Celery 整合
- 錯誤處理機制

### 第三階段：前端開發（第 5-6 週）
- Vue.js 前端建立
- 使用者介面實作
- API 整合

### 第四階段：進階功能（第 7-8 週）
- 管理員功能
- 統計報表
- 自動清理機制
- 郵件通知

### 第五階段：測試與優化（第 9-10 週）
- 完整測試
- 效能優化
- 文件撰寫
- 部署準備

## 9. 風險評估

### 9.1 技術風險
- **Dify API 不穩定**: 實作完善的重試機制
- **大檔案處理**: 設定合理的檔案大小限制
- **LDAP 連線問題**: 實作連線池與重試

### 9.2 業務風險
- **成本超支**: 實時監控 API 使用量
- **資料外洩**: 嚴格的權限控制
- **系統當機**: 完善的錯誤恢復機制

## 10. 成功指標

### 10.1 功能指標
- 所有規劃功能 100% 實作
- 單元測試覆蓋率 > 80%
- 零重大安全漏洞

### 10.2 效能指標
- 系統可用性 > 99%
- API 回應時間 < 2 秒
- 翻譯成功率 > 95%

### 10.3 使用者指標
- 使用者滿意度 > 90%
- 平均每日活躍使用者 > 20
- 問題回報數 < 5 個/月

## 11. 相關文件

- 原始程式碼：document_translator_gui_with_backend.py
- API 配置：api.txt
- 參考專案：C:\Users\EGG\WORK\data\user_scrip\TOOL\TODOLIST

## 12. 修訂記錄

| 版本 | 日期 | 修改內容 | 作者 |
|------|------|---------|------|
| 1.0 | 2024-01-28 | 初始版本 | System |

---

**文件狀態**: 待審核
**下一步**: 提交給系統架構師進行技術設計文件(TDD)撰寫