1st_fix_login_issue

2025-09-02 10:31:35 +08:00
commit a60d965317
103 changed files with 12402 additions and 0 deletions
--- a/PRD.md
+++ b/PRD.md
@@ -0,0 +1,337 @@
+# 產品需求文件 (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)撰寫