egg/PROJECT-CONTORL
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
69b81d92413aef03a401e0c5a0ed3cd63c797380
PROJECT-CONTORL/openspec/specs/document-management/spec.md
beabigegg 9b220523ff feat: complete issue fixes and implement remaining features 
## Critical Issues (CRIT-001~003) - All Fixed
- JWT secret key validation with pydantic field_validator
- Login audit logging for success/failure attempts
- Frontend API path prefix removal

## High Priority Issues (HIGH-001~008) - All Fixed
- Project soft delete using is_active flag
- Redis session token bytes handling
- Rate limiting with slowapi (5 req/min for login)
- Attachment API permission checks
- Kanban view with drag-and-drop
- Workload heatmap UI (WorkloadPage, WorkloadHeatmap)
- TaskDetailModal integrating Comments/Attachments
- UserSelect component for task assignment

## Medium Priority Issues (MED-001~012) - All Fixed
- MED-001~005: DB commits, N+1 queries, datetime, error format, blocker flag
- MED-006: Project health dashboard (HealthService, ProjectHealthPage)
- MED-007: Capacity update API (PUT /api/users/{id}/capacity)
- MED-008: Schedule triggers (cron parsing, deadline reminders)
- MED-009: Watermark feature (image/PDF watermarking)
- MED-010~012: useEffect deps, DOM operations, PDF export

## New Files
- backend/app/api/health/ - Project health API
- backend/app/services/health_service.py
- backend/app/services/trigger_scheduler.py
- backend/app/services/watermark_service.py
- backend/app/core/rate_limiter.py
- frontend/src/pages/ProjectHealthPage.tsx
- frontend/src/components/ProjectHealthCard.tsx
- frontend/src/components/KanbanBoard.tsx
- frontend/src/components/WorkloadHeatmap.tsx

## Tests
- 113 new tests passing (health: 32, users: 14, triggers: 35, watermark: 32)

## OpenSpec Archives
- add-project-health-dashboard
- add-capacity-update-api
- add-schedule-triggers
- add-watermark-feature
- add-rate-limiting
- enhance-frontend-ux
- add-resource-management-ui

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-04 21:49:52 +08:00

5.7 KiB
Raw Blame History

Document Management

Purpose

文件管理系統，提供檔案附件、版本控制、加密存儲與浮水印功能。

Requirements

Requirement: File Attachments

系統 SHALL 支援任務層級的檔案附件，儲存於地端 NAS。

Scenario: 上傳附件

  • GIVEN 使用者擁有任務的編輯權限
  • WHEN 使用者上傳檔案至任務
  • THEN 系統將檔案儲存至 NAS
  • AND 建立附件記錄關聯至該任務

Scenario: 下載附件

  • GIVEN 使用者擁有任務的存取權限
  • WHEN 使用者下載附件
  • THEN 系統驗證權限後提供檔案下載
  • AND 記錄下載操作日誌

Scenario: 刪除附件

  • GIVEN 使用者擁有任務的編輯權限
  • WHEN 使用者刪除附件
  • THEN 系統標記附件為已刪除（軟刪除）
  • AND 保留檔案供稽核追溯

Requirement: Version Control

系統 SHALL 支援檔案版本控制，追蹤所有版本變更。

Scenario: 上傳新版本

  • GIVEN 任務已有同名附件
  • WHEN 使用者上傳同名檔案
  • THEN 系統建立新版本而非覆蓋
  • AND 版本號自動遞增

Scenario: 查看版本歷史

  • GIVEN 附件有多個版本
  • WHEN 使用者查看版本歷史
  • THEN 顯示所有版本清單
  • AND 包含上傳者、上傳時間、檔案大小

Scenario: 回復舊版本

  • GIVEN 使用者需要使用舊版本
  • WHEN 使用者選擇回復特定版本
  • THEN 系統將該版本設為當前版本
  • AND 記錄回復操作

Requirement: File Encryption

系統 SHALL 對半導體敏感圖檔進行 AES-256 加密存儲。

Scenario: 加密存儲

  • GIVEN 專案設定為機密等級
  • WHEN 使用者上傳檔案
  • THEN 系統使用 AES-256 加密後存儲
  • AND 加密金鑰安全管理

Scenario: 解密讀取

  • GIVEN 使用者請求下載加密檔案
  • WHEN 系統驗證權限通過
  • THEN 系統解密檔案後提供下載
  • AND 解密過程透明，使用者無感

Scenario: 加密金鑰輪換

  • GIVEN 安全政策要求金鑰輪換
  • WHEN 管理員執行金鑰輪換
  • THEN 系統使用新金鑰重新加密所有檔案
  • AND 舊金鑰安全銷毀

Requirement: Dynamic Watermarking

系統 SHALL 在下載時自動為檔案加上使用者浮水印。

Scenario: 圖片浮水印

  • GIVEN 使用者下載圖片類型附件 (PNG, JPG, JPEG)
  • WHEN 系統處理下載請求
  • THEN 自動加上包含使用者姓名、工號、下載時間的浮水印
  • AND 浮水印位置不影響主要內容

Scenario: PDF 浮水印

  • GIVEN 使用者下載 PDF 類型附件
  • WHEN 系統處理下載請求
  • THEN 每頁加上浮水印
  • AND 浮水印透明度適中

Scenario: 浮水印內容

  • GIVEN 需要加上浮水印
  • WHEN 系統生成浮水印
  • THEN 浮水印包含：
    • 使用者姓名
    • 使用者工號
    • 下載日期時間
    • 機密等級標示（如適用）

Scenario: 不支援的檔案類型

  • GIVEN 使用者下載非圖片/PDF 類型附件
  • WHEN 系統處理下載請求
  • THEN 直接提供原始檔案下載
  • AND 不嘗試加上浮水印

Scenario: 浮水印服務異常處理

  • GIVEN 浮水印生成過程發生錯誤
  • WHEN 系統無法完成浮水印處理
  • THEN 記錄錯誤日誌
  • AND 提供原始檔案下載（降級處理）

Requirement: Audit Trail

系統 SHALL 記錄所有文件操作供稽核追溯。

Scenario: 操作日誌記錄

  • GIVEN 使用者對附件執行任何操作
  • WHEN 操作完成
  • THEN 系統記錄操作類型、操作者、時間、IP 位址
  • AND 日誌不可竄改

Scenario: 稽核查詢

  • GIVEN 稽核人員需要查詢文件操作歷史
  • WHEN 稽核人員執行查詢
  • THEN 顯示完整操作歷史
  • AND 支援依時間、操作者、檔案篩選

Data Model

pjctrl_attachments
├── id: UUID (PK)
├── task_id: UUID (FK -> tasks)
├── filename: VARCHAR(500)
├── original_filename: VARCHAR(500)
├── file_path: VARCHAR(1000) (NAS path)
├── file_size: BIGINT
├── mime_type: VARCHAR(100)
├── version: INT DEFAULT 1
├── is_encrypted: BOOLEAN DEFAULT false
├── encryption_key_id: UUID (FK -> encryption_keys)
├── checksum: VARCHAR(64) (SHA-256)
├── uploaded_by: UUID (FK -> users)
├── is_deleted: BOOLEAN DEFAULT false
├── created_at: TIMESTAMP
└── updated_at: TIMESTAMP

pjctrl_attachment_versions
├── id: UUID (PK)
├── attachment_id: UUID (FK -> attachments)
├── version: INT
├── file_path: VARCHAR(1000)
├── file_size: BIGINT
├── checksum: VARCHAR(64)
├── uploaded_by: UUID (FK -> users)
├── is_current: BOOLEAN DEFAULT false
└── created_at: TIMESTAMP

pjctrl_encryption_keys
├── id: UUID (PK)
├── key_hash: VARCHAR(64) (for verification)
├── algorithm: VARCHAR(20) DEFAULT 'AES-256'
├── is_active: BOOLEAN DEFAULT true
├── created_at: TIMESTAMP
└── rotated_at: TIMESTAMP

pjctrl_document_audit_logs
├── id: UUID (PK)
├── attachment_id: UUID (FK -> attachments)
├── user_id: UUID (FK -> users)
├── action: ENUM('upload', 'download', 'delete', 'restore', 'version_create', 'version_restore')
├── ip_address: VARCHAR(45)
├── user_agent: VARCHAR(500)
├── details: JSON
└── created_at: TIMESTAMP

Technical Notes

  • 加密金鑰存儲於獨立的 Key Management Service (KMS)
  • 浮水印使用 Pillow (圖片) 和 PyPDF2 (PDF) 處理
  • 大檔案使用串流處理避免記憶體溢出
  • NAS 存儲路徑結構：/{project_id}/{task_id}/{attachment_id}/{version}/