egg/Document_Translator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
82aaa315bbdb0f0dbdb2b7849205253b5d1d03d6
Document_Translator/PRD.md
beabigegg a60d965317 1st_fix_login_issue
2025-09-02 10:31:35 +08:00

8.7 KiB
Raw Blame History

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

1. 產品概述

1.1 產品名稱

PANJIT Document Translator Web System

1.2 產品定位

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

1.3 目標使用者

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)撰寫