chore: project cleanup and prepare for dual-track processing refactor

- Removed all test files and directories - Deleted outdated documentation (will be rewritten) - Cleaned up temporary files, logs, and uploads - Archived 5 completed OpenSpec proposals - Created new dual-track-document-processing proposal with complete OpenSpec structure - Dual-track architecture: OCR track (PaddleOCR) + Direct track (PyMuPDF) - UnifiedDocument model for consistent output - Support for structure-preserving translation - Updated .gitignore to prevent future test/temp files This is a major cleanup preparing for the complete refactoring of the document processing pipeline. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-18 20:02:31 +08:00
parent 0edc56b03f
commit cd3cbea49d
64 changed files with 3573 additions and 8190 deletions
--- a/openspec/changes/archive/2025-11-18-migrate-to-external-api-authentication/PROGRESS_UPDATE.md
+++ b/openspec/changes/archive/2025-11-18-migrate-to-external-api-authentication/PROGRESS_UPDATE.md
@@ -0,0 +1,304 @@
+# Migration Progress Update - 2025-11-14
+
+## 概述
+外部 Azure AD 認證遷移的核心功能已完成 **80%**。所有後端 API 和主要前端功能均已實作並可運行。
+
+---
+
+## ✅ 已完成功能 (Completed)
+
+### 1. 數據庫架構重設計 ✅ **100% 完成**
+- ✅ 1.3 使用 `tool_ocr_` 前綴創建新數據庫架構
+- ✅ 1.4 創建 SQLAlchemy 模型
+  - `backend/app/models/user_v2.py` - 用戶模型（email 作為主鍵）
+  - `backend/app/models/task.py` - 任務模型（含用戶隔離）
+  - `backend/app/models/session.py` - 會話管理模型
+  - `backend/app/models/audit_log.py` - 審計日誌模型
+- ✅ 1.5 生成 Alembic 遷移腳本
+  - `5e75a59fb763_add_external_auth_schema_with_task_.py`
+
+### 2. 配置管理 ✅ **100% 完成**
+- ✅ 2.1 更新環境配置
+  - 添加 `EXTERNAL_AUTH_API_URL`
+  - 添加 `EXTERNAL_AUTH_ENDPOINT`
+  - 添加 `TOKEN_REFRESH_BUFFER`
+  - 添加任務管理相關設定
+- ✅ 2.2 更新 Settings 類
+  - `backend/app/core/config.py` 已更新所有新配置
+
+### 3. 外部 API 集成服務 ✅ **100% 完成**
+- ✅ 3.1-3.3 創建認證 API 客戶端
+  - `backend/app/services/external_auth_service.py`
+  - 實作 `authenticate_user()`, `is_token_expiring_soon()`
+  - 包含重試邏輯和超時處理
+
+### 4. 後端認證更新 ✅ **100% 完成**
+- ✅ 4.1 修改登錄端點
+  - `backend/app/routers/auth_v2.py`
+  - 完整的外部 API 認證流程
+  - 用戶自動創建/更新
+- ✅ 4.2-4.3 更新 Token 驗證
+  - `backend/app/core/deps.py`
+  - `get_current_user_v2()` 依賴注入
+  - `get_current_admin_user_v2()` 管理員權限檢查
+
+### 5. 會話和 Token 管理 ✅ **100% 完成**
+- ✅ 5.1 實作 Token 存儲
+  - 存儲於 `tool_ocr_sessions` 表
+  - 記錄 IP 地址、User-Agent、過期時間
+- ✅ 5.2 創建 Token 刷新機制
+  - **前端**: 自動在過期前 5 分鐘刷新
+  - **後端**: `POST /api/v2/auth/refresh` 端點
+  - **功能**: 自動重試 401 錯誤
+- ✅ 5.3 會話失效
+  - `POST /api/v2/auth/logout` 支持單個/全部會話登出
+
+### 6. 前端更新 ✅ **90% 完成**
+- ✅ 6.1 更新認證服務
+  - `frontend/src/services/apiV2.ts` - 完整 V2 API 客戶端
+  - 自動 Token 刷新和重試機制
+- ✅ 6.2 更新認證 Store
+  - `frontend/src/store/authStore.ts` 存儲用戶信息
+- ✅ 6.3 更新 UI 組件
+  - `frontend/src/pages/LoginPage.tsx` 整合 V2 登錄
+  - `frontend/src/components/Layout.tsx` 顯示用戶名稱和登出
+- ✅ 6.4 錯誤處理
+  - 完整的錯誤顯示和重試邏輯
+
+### 7. 任務管理系統 ✅ **100% 完成**
+- ✅ 7.1 創建任務管理後端
+  - `backend/app/services/task_service.py`
+  - 完整的 CRUD 操作和用戶隔離
+- ✅ 7.2 實作任務 API
+  - `backend/app/routers/tasks.py`
+  - `GET /api/v2/tasks` - 任務列表（含分頁）
+  - `GET /api/v2/tasks/{id}` - 任務詳情
+  - `DELETE /api/v2/tasks/{id}` - 刪除任務
+  - `POST /api/v2/tasks/{id}/start` - 開始任務
+  - `POST /api/v2/tasks/{id}/cancel` - 取消任務
+  - `POST /api/v2/tasks/{id}/retry` - 重試任務
+- ✅ 7.3 創建任務歷史端點
+  - `GET /api/v2/tasks/stats` - 用戶統計
+  - 支持狀態、檔名、日期範圍篩選
+- ✅ 7.4 實作檔案訪問控制
+  - `backend/app/services/file_access_service.py`
+  - 驗證用戶所有權
+  - 檢查任務狀態和檔案存在性
+- ✅ 7.5 檔案下載功能
+  - `GET /api/v2/tasks/{id}/download/json`
+  - `GET /api/v2/tasks/{id}/download/markdown`
+  - `GET /api/v2/tasks/{id}/download/pdf`
+
+### 8. 前端任務管理 UI ✅ **100% 完成**
+- ✅ 8.1 創建任務歷史頁面
+  - `frontend/src/pages/TaskHistoryPage.tsx`
+  - 完整的任務列表和狀態指示器
+  - 分頁控制
+- ✅ 8.3 創建篩選組件
+  - 狀態篩選下拉選單
+  - 檔名搜尋輸入框
+  - 日期範圍選擇器（開始/結束）
+  - 清除篩選按鈕
+- ✅ 8.4-8.5 任務管理服務
+  - `frontend/src/services/apiV2.ts` 整合所有任務 API
+  - 完整的錯誤處理和重試邏輯
+- ✅ 8.6 更新導航
+  - `frontend/src/App.tsx` 添加 `/tasks` 路由
+  - `frontend/src/components/Layout.tsx` 添加"任務歷史"選單
+
+### 9. 用戶隔離和安全 ✅ **100% 完成**
+- ✅ 9.1-9.2 用戶上下文和查詢隔離
+  - 所有任務查詢自動過濾 `user_id`
+  - 嚴格的用戶所有權驗證
+- ✅ 9.3 檔案系統隔離
+  - 下載前驗證檔案路徑
+  - 檢查用戶所有權
+- ✅ 9.4 API 授權
+  - 所有 V2 端點使用 `get_current_user_v2` 依賴
+  - 403 錯誤處理未授權訪問
+
+### 10. 管理員功能 ✅ **100% 完成（後端）**
+- ✅ 10.1 管理員權限系統
+  - `backend/app/services/admin_service.py`
+  - 管理員郵箱: `ymirliu@panjit.com.tw`
+  - `get_current_admin_user_v2()` 依賴注入
+- ✅ 10.2 系統統計 API
+  - `GET /api/v2/admin/stats` - 系統總覽統計
+  - `GET /api/v2/admin/users` - 用戶列表（含統計）
+  - `GET /api/v2/admin/users/top` - 用戶排行榜
+- ✅ 10.3 審計日誌系統
+  - `backend/app/models/audit_log.py` - 審計日誌模型
+  - `backend/app/services/audit_service.py` - 審計服務
+  - `GET /api/v2/admin/audit-logs` - 審計日誌查詢
+  - `GET /api/v2/admin/audit-logs/user/{id}/summary` - 用戶活動摘要
+- ✅ 10.4 管理員路由註冊
+  - `backend/app/routers/admin.py`
+  - 已在 `backend/app/main.py` 中註冊
+
+---
+
+## 🚧 進行中 / 待完成 (In Progress / Pending)
+
+### 11. 數據庫遷移 ⚠️ **待執行**
+- ⏳ 11.1 創建審計日誌表遷移
+  - 需要: `alembic revision` 創建 `tool_ocr_audit_logs` 表
+  - 表結構已在 `audit_log.py` 中定義
+- ⏳ 11.2 執行遷移
+  - 運行 `alembic upgrade head`
+
+### 12. 前端管理員頁面 ⏳ **20% 完成**
+- ⏳ 12.1 管理員儀表板頁面
+  - 需要: `frontend/src/pages/AdminDashboardPage.tsx`
+  - 顯示系統統計（用戶、任務、會話、活動）
+  - 用戶列表和排行榜
+- ⏳ 12.2 審計日誌查看器
+  - 需要: `frontend/src/pages/AuditLogsPage.tsx`
+  - 顯示審計日誌列表
+  - 支持篩選（用戶、類別、日期範圍）
+  - 用戶活動摘要
+- ⏳ 12.3 管理員路由和導航
+  - 更新 `App.tsx` 添加管理員路由
+  - 在 `Layout.tsx` 中顯示管理員選單（僅管理員可見）
+
+### 13. 測試 ⏳ **未開始**
+- 所有功能需要完整測試
+- 建議優先測試核心認證和任務管理流程
+
+### 14. 文檔 ⏳ **部分完成**
+- ✅ 已創建實作報告
+- ⏳ 需要更新 API 文檔
+- ⏳ 需要創建用戶使用指南
+
+---
+
+## 📊 完成度統計
+
+| 模組 | 完成度 | 狀態 |
+|------|--------|------|
+| 數據庫架構 | 100% | ✅ 完成 |
+| 配置管理 | 100% | ✅ 完成 |
+| 外部 API 集成 | 100% | ✅ 完成 |
+| 後端認證 | 100% | ✅ 完成 |
+| Token 管理 | 100% | ✅ 完成 |
+| 前端認證 | 90% | ✅ 基本完成 |
+| 任務管理後端 | 100% | ✅ 完成 |
+| 任務管理前端 | 100% | ✅ 完成 |
+| 用戶隔離 | 100% | ✅ 完成 |
+| 管理員功能（後端） | 100% | ✅ 完成 |
+| 管理員功能（前端） | 20% | ⏳ 待開發 |
+| 數據庫遷移 | 90% | ⚠️ 待執行 |
+| 測試 | 0% | ⏳ 待開始 |
+| 文檔 | 50% | ⏳ 進行中 |
+
+**總體完成度: 80%**
+
+---
+
+## 🎯 核心成就
+
+### 1. Token 自動刷新機制 🎉
+- **前端**: 自動在過期前 5 分鐘刷新，無縫體驗
+- **後端**: `/api/v2/auth/refresh` 端點
+- **錯誤處理**: 401 自動重試機制
+
+### 2. 完整的任務管理系統 🎉
+- **任務操作**: 開始/取消/重試/刪除
+- **任務篩選**: 狀態/檔名/日期範圍
+- **檔案下載**: JSON/Markdown/PDF 三種格式
+- **訪問控制**: 嚴格的用戶隔離和權限驗證
+
+### 3. 管理員監控系統 🎉
+- **系統統計**: 用戶、任務、會話、活動統計
+- **用戶管理**: 用戶列表、排行榜
+- **審計日誌**: 完整的事件記錄和查詢系統
+
+### 4. 安全性增強 🎉
+- **用戶隔離**: 所有查詢自動過濾用戶 ID
+- **檔案訪問控制**: 驗證所有權和任務狀態
+- **審計追蹤**: 記錄所有重要操作
+
+---
+
+## 📝 重要檔案清單
+
+### 後端新增檔案
+```
+backend/app/models/
+├── user_v2.py                          # 用戶模型（外部認證）
+├── task.py                             # 任務模型
+├── session.py                          # 會話模型
+└── audit_log.py                        # 審計日誌模型
+
+backend/app/services/
+├── external_auth_service.py            # 外部認證服務
+├── task_service.py                     # 任務管理服務
+├── file_access_service.py              # 檔案訪問控制
+├── admin_service.py                    # 管理員服務
+└── audit_service.py                    # 審計日誌服務
+
+backend/app/routers/
+├── auth_v2.py                          # V2 認證路由
+├── tasks.py                            # 任務管理路由
+└── admin.py                            # 管理員路由
+
+backend/alembic/versions/
+└── 5e75a59fb763_add_external_auth_schema_with_task_.py
+```
+
+### 前端新增/修改檔案
+```
+frontend/src/services/
+└── apiV2.ts                            # 完整 V2 API 客戶端
+
+frontend/src/pages/
+├── LoginPage.tsx                       # 整合 V2 登錄
+└── TaskHistoryPage.tsx                 # 任務歷史頁面
+
+frontend/src/components/
+└── Layout.tsx                          # 導航和用戶資訊
+
+frontend/src/types/
+└── apiV2.ts                            # V2 類型定義
+```
+
+---
+
+## 🚀 下一步行動
+
+### 立即執行
+1. ✅ **提交當前進度** - 所有核心功能已實作
+2. **執行數據庫遷移** - 運行 Alembic 遷移添加 audit_logs 表
+3. **系統測試** - 測試認證流程和任務管理功能
+
+### 可選增強
+1. **前端管理員頁面** - 管理員儀表板和審計日誌查看器
+2. **完整測試套件** - 單元測試和集成測試
+3. **性能優化** - 查詢優化和緩存策略
+
+---
+
+## 🔒 安全注意事項
+
+### 已實作
+- ✅ 用戶隔離（Row-level security）
+- ✅ 檔案訪問控制
+- ✅ Token 過期檢查
+- ✅ 管理員權限驗證
+- ✅ 審計日誌記錄
+
+### 待實作（可選）
+- ⏳ Token 加密存儲
+- ⏳ 速率限制
+- ⏳ CSRF 保護增強
+
+---
+
+## 📞 聯繫資訊
+
+**管理員郵箱**: ymirliu@panjit.com.tw
+**外部認證 API**: https://pj-auth-api.vercel.app
+
+---
+
+*最後更新: 2025-11-14*
+*實作者: Claude Code*