feat: add admin dashboard, audit logs, token expiry check and test suite

Frontend Features:
- Add ProtectedRoute component with token expiry validation
- Create AdminDashboardPage with system statistics and user management
- Create AuditLogsPage with filtering and pagination
- Add admin-only navigation (Shield icon) for ymirliu@panjit.com.tw
- Add admin API methods to apiV2 service
- Add admin type definitions (SystemStats, AuditLog, etc.)

Token Management:
- Auto-redirect to login on token expiry
- Check authentication on route change
- Show loading state during auth check
- Admin privilege verification

Backend Testing:
- Add pytest configuration (pytest.ini)
- Create test fixtures (conftest.py)
- Add unit tests for auth, tasks, and admin endpoints
- Add integration tests for complete workflows
- Test user isolation and admin access control

Documentation:
- Add TESTING.md with comprehensive testing guide
- Include test running instructions
- Document fixtures and best practices

Routes:
- /admin - Admin dashboard (admin only)
- /admin/audit-logs - Audit logs viewer (admin only)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
egg
2025-11-16 18:01:50 +08:00
parent fd98018ddd
commit 8f94191914
13 changed files with 1554 additions and 45 deletions

258
TESTING.md Normal file
View File

@@ -0,0 +1,258 @@
# Tool_OCR Testing Guide
## 測試架構
本專案包含完整的測試套件,包括單元測試和集成測試。
---
## 後端測試
### 安裝測試依賴
```bash
cd backend
pip install pytest pytest-cov httpx
```
### 運行所有測試
```bash
# 運行所有測試
pytest
# 運行並顯示詳細輸出
pytest -v
# 運行並生成覆蓋率報告
pytest --cov=app --cov-report=html
```
### 運行特定測試
```bash
# 僅運行單元測試
pytest tests/test_auth.py
pytest tests/test_tasks.py
pytest tests/test_admin.py
# 僅運行集成測試
pytest tests/test_integration.py
# 運行特定測試類
pytest tests/test_tasks.py::TestTasks
# 運行特定測試方法
pytest tests/test_tasks.py::TestTasks::test_create_task
```
### 測試覆蓋
**單元測試** (`tests/test_*.py`):
- `test_auth.py` - 認證端點測試
- 登入成功/失敗
- Token 驗證
- 登出功能
- `test_tasks.py` - 任務管理測試
- 任務 CRUD 操作
- 用戶隔離驗證
- 統計數據
- `test_admin.py` - 管理員功能測試
- 系統統計
- 用戶列表
- 審計日誌
**集成測試** (`tests/test_integration.py`):
- 完整認證和任務流程
- 管理員工作流程
- 任務生命週期
---
## 測試資料庫
測試使用 SQLite 記憶體資料庫,每次測試後自動清理:
- 不影響開發或生產資料庫
- 快速執行
- 完全隔離
---
## Fixtures (測試夾具)
`conftest.py` 中定義:
- `db` - 測試資料庫 session
- `client` - FastAPI 測試客戶端
- `test_user` - 一般測試用戶
- `admin_user` - 管理員測試用戶
- `auth_token` - 測試用戶的認證 token
- `admin_token` - 管理員的認證 token
- `test_task` - 測試任務
---
## 測試範例
### 編寫新的單元測試
```python
# tests/test_my_feature.py
import pytest
class TestMyFeature:
"""Test my new feature"""
def test_feature_works(self, client, auth_token):
"""Test that feature works correctly"""
response = client.get(
'/api/v2/my-endpoint',
headers={'Authorization': f'Bearer {auth_token}'}
)
assert response.status_code == 200
data = response.json()
assert 'expected_field' in data
```
### 編寫新的集成測試
```python
# tests/test_integration.py
class TestIntegration:
def test_complete_workflow(self, client, db):
"""Test complete user workflow"""
# Step 1: Login
# Step 2: Perform actions
# Step 3: Verify results
pass
```
---
## CI/CD 整合
### GitHub Actions 範例
```yaml
name: Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Set up Python
uses: actions/setup-python@v2
with:
python-version: 3.11
- name: Install dependencies
run: |
cd backend
pip install -r requirements.txt
pip install pytest pytest-cov
- name: Run tests
run: |
cd backend
pytest --cov=app --cov-report=xml
- name: Upload coverage
uses: codecov/codecov-action@v2
```
---
## 前端測試 (未來計劃)
### 建議測試框架
- **單元測試**: Vitest
- **元件測試**: React Testing Library
- **E2E 測試**: Playwright
### 範例配置
```bash
# 安裝測試依賴
npm install --save-dev vitest @testing-library/react @testing-library/jest-dom
# 運行測試
npm test
# 運行 E2E 測試
npm run test:e2e
```
---
## 測試最佳實踐
### 1. 測試命名規範
- 使用描述性名稱: `test_user_can_create_task`
- 遵循 AAA 模式: Arrange, Act, Assert
### 2. 測試隔離
- 每個測試獨立執行
- 使用 fixtures 提供測試數據
- 不依賴其他測試的狀態
### 3. Mock 外部服務
- Mock 外部 API 呼叫
- Mock 檔案系統操作
- Mock 第三方服務
### 4. 測試覆蓋率目標
- 核心業務邏輯: >90%
- API 端點: >80%
- 工具函數: >70%
---
## 故障排除
### 常見問題
**問題**: `ImportError: cannot import name 'XXX'`
**解決**: 確保 PYTHONPATH 正確設定
```bash
export PYTHONPATH=$PYTHONPATH:$(pwd)
```
**問題**: 資料庫連接錯誤
**解決**: 測試使用記憶體資料庫,不需要實際資料庫連接
**問題**: Token 驗證失敗
**解決**: 檢查 JWT secret 設定,使用測試用 fixtures
---
## 測試報告
執行測試後生成的報告:
1. **終端輸出**: 測試結果概覽
2. **HTML 報告**: `htmlcov/index.html` (需要 --cov-report=html)
3. **覆蓋率報告**: 顯示未測試的代碼行
---
## 持續改進
- 定期運行測試套件
- 新功能必須包含測試
- 維護測試覆蓋率在 80% 以上
- Bug 修復時添加回歸測試
---
**最後更新**: 2025-11-16
**維護者**: Development Team