LinkDesk/openspec/changes/my-task-page-project-tasks/design.md

Context

此變更旨在為 VFX 專案管理系統新增一個「我的任務」(My Tasks) 頁面，讓用戶能夠在一個統一的視圖中查看所有專案中分配給自己的任務。目前用戶需要逐一進入每個專案才能看到被分配的任務，這對於同時管理多個專案的 Director、Coordinator 等角色而言效率較低。

現有系統已經具備：

• 完善的任務管理系統（Task entity with assignments）
• 專案內的任務頁面（使用 DataTable 元件）
• 基於角色的存取控制 (RBAC)
• JWT 認證機制

Goals / Non-Goals

Goals:

• 建立一個統一的「我的任務」頁面，展示所有分配給當前用戶的任務
• 重用現有的專案任務頁面 layout 與 DataTable 元件，確保 UI 一致性
• 支援按專案、狀態等條件篩選任務
• 支援任務排序功能
• 提供從任務列表直接導航到任務詳細頁面的功能

Non-Goals:

• 不會修改現有專案內的任務頁面行為
• 不會新增任務管理功能（如建立、編輯、刪除任務）- 這些應在專案上下文完成
• 不會提供跨專案的任務批量操作

Decisions

1. API 設計：獨立端點 vs 擴展現有端點

Decision: 建立獨立的 /api/tasks/my-tasks 端點

Rationale:

• 獨立端點可讓權限過濾更清晰（僅顯示用戶有權限存取的專案任務）
• 回應格式可針對 My Tasks 視圖優化（如包含專案資訊）
• 未來擴展（如分頁、進階篩選）更彈性

Alternative considered: 擴展現有的 /api/projects/{id}/tasks 端點

• 這個方法需要傳遞多個專案 ID，不適合跨專案查詢場景

2. 前端架構：新建元件 vs 重用現有元件

Decision: 重用現有的 ProjectTaskPage layout 與 DataTable 元件

Rationale:

• 確保 UI/UX 一致性，用戶在專案內和 My Tasks 頁面有相同體驗
• 減少開發時間和維護成本
• DataTable 元件已經支援排序、篩選、分頁等功能

Alternative considered: 建立全新的 MyTasksPage 元件

• 需要重複實作相同功能，增加維護負擔

3. 權限模型：僅顯示有權限的任務

Decision: API 僅返回用戶有存取權限的專案任務

Rationale:

• 符合最小權限原則
• 避免資安風險（用戶不應看到無權限專案的任務）
• 與現有 RBAC 系統整合

4. 資料庫查詢策略

Decision: 單一查詢取得所有任務（而非多次查詢）

Rationale:

• 減少網路往返次數
• 雖然查詢較複雜，但可通過 SQLAlchemy 優化
• 考量未來加入分頁以處理大量任務

Risks:

• [Risk] 大型系統中任務數量可能很大 → Mitigation: 實作分頁機制
• [Risk] 跨專案查詢效能 → Mitigation: 確保 task.assignee_id 和 task.project_id 有適當索引

Migration Plan

此變更為純新增功能，不需要資料遷移。部署步驟：

1. 後端部署：

   • 部署新 API 端點 /api/tasks/my-tasks
   • 確認任務查詢效能（如需要則新增資料庫索引）

2. 前端部署：

   • 新增 My Tasks 頁面路由
   • 確保導航選單有 My Tasks 入口

3. 驗證：

   • 測試不同角色用戶的 My Tasks 顯示正確性
   • 驗證篩選、排序功能正常運作
   • 確認權限控制正確（無權限專案的任務不顯示）

Open Questions

• Q1: My Tasks 頁面是否需要顯示任務的詳細進度（如 shot/asset 進度）？

  • 目前建議: 暫不包含，保持與專案任務頁面一致

• Q2: 是否需要支援「我的最愛」或「追蹤中」的任務功能？

  • 目前建議: 留待未來擴展

• Q3: 如何處理任務數量眾多的效能問題？

  • 建議: 採用分頁（預設 50 筆），並在未來根據需求考慮虛擬滾動