df50d5e7f8
Archived proposals:
- add-trigger-conditions-weekly-subscription: Trigger conditions and weekly subscription
- update-api-consistency: WebSocket auth, optimistic locking, workload defaults
All implementations were already complete in previous commits (f5f870d).
Updated tasks.md with implementation summary.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
240 lines
9.3 KiB
Markdown
240 lines
9.3 KiB
Markdown
# Resource Management
|
||
|
||
## Purpose
|
||
|
||
資源管理系統，提供負載熱圖與人員容量追蹤，協助主管進行資源分配決策。讓主管能即時掌握團隊成員的工作負載狀況，及早發現超載或閒置問題，優化資源分配。
|
||
## Requirements
|
||
### Requirement: Workload Heatmap
|
||
|
||
系統 SHALL 提供負載熱圖 API，自動統計每人每週分配的任務總時數，並以顏色等級表示負載狀態。
|
||
|
||
#### Scenario: 負載正常顯示
|
||
- **GIVEN** 某人員本週被指派的任務總時數低於其容量的 80%
|
||
- **WHEN** 主管查詢負載熱圖 API
|
||
- **THEN** 該人員的 `load_level` 為 `normal`
|
||
- **AND** 回傳包含 `load_percentage`、`allocated_hours`、`capacity_hours`
|
||
|
||
#### Scenario: 負載警告顯示
|
||
- **GIVEN** 某人員本週被指派的任務總時數達到其容量的 80%-99%
|
||
- **WHEN** 主管查詢負載熱圖 API
|
||
- **THEN** 該人員的 `load_level` 為 `warning`
|
||
|
||
#### Scenario: 負載超載顯示
|
||
- **GIVEN** 某人員本週被指派的任務總時數達到或超過其容量的 100%
|
||
- **WHEN** 主管查詢負載熱圖 API
|
||
- **THEN** 該人員的 `load_level` 為 `overloaded`
|
||
|
||
#### Scenario: 查詢特定週的負載
|
||
- **GIVEN** 主管需要查看非當週的負載
|
||
- **WHEN** 主管以 `week_start` 參數查詢負載熱圖 API
|
||
- **THEN** 系統回傳該週的負載資料
|
||
|
||
#### Scenario: 快取機制
|
||
- **GIVEN** 負載資料已被計算並快取
|
||
- **WHEN** 相同查詢在 1 小時內再次發生
|
||
- **THEN** 系統從 Redis 快取回傳結果
|
||
|
||
### Requirement: Capacity Planning
|
||
|
||
系統 SHALL 支援人員容量規劃，包含預設容量與臨時調整。
|
||
|
||
#### Scenario: 設定人員預設容量
|
||
- **GIVEN** 管理者需要設定人員的週工時上限
|
||
- **WHEN** 管理者更新使用者的 `capacity` 值
|
||
- **THEN** 系統儲存新的容量設定
|
||
- **AND** 後續負載計算使用新容量值
|
||
|
||
#### Scenario: 容量為零處理
|
||
- **GIVEN** 使用者的容量設為 0
|
||
- **WHEN** 系統計算該使用者的負載
|
||
- **THEN** `load_percentage` 顯示為 `null`
|
||
- **AND** `load_level` 顯示為 `unavailable`
|
||
|
||
#### Scenario: 容量更新 API
|
||
- **GIVEN** 管理者需要更新團隊成員的容量
|
||
- **WHEN** 管理者呼叫 `PUT /api/users/{user_id}/capacity` 並提供新容量值
|
||
- **THEN** 系統驗證容量值在有效範圍內 (0-168 小時)
|
||
- **AND** 更新使用者的 capacity 欄位
|
||
- **AND** 記錄變更至稽核日誌
|
||
|
||
#### Scenario: 容量更新權限控制
|
||
- **GIVEN** 一般使用者嘗試更新他人容量
|
||
- **WHEN** 使用者呼叫 `PUT /api/users/{other_id}/capacity`
|
||
- **THEN** 系統拒絕請求並回傳 403 Forbidden
|
||
|
||
### Requirement: Multi-Project Health Dashboard
|
||
系統 SHALL 提供多專案健康看板，讓主管一覽所有專案狀態。
|
||
|
||
#### Scenario: 專案健康總覽
|
||
- **GIVEN** 主管負責多個專案
|
||
- **WHEN** 主管開啟健康看板
|
||
- **THEN** 顯示所有專案的進度、風險指標、延遲任務數
|
||
- **AND** 可依風險程度排序
|
||
|
||
#### Scenario: 專案延遲警示
|
||
- **GIVEN** 專案有任務超過截止日期
|
||
- **WHEN** 主管查看健康看板
|
||
- **THEN** 該專案標示為延遲狀態
|
||
- **AND** 顯示延遲任務數量與影響
|
||
|
||
#### Scenario: 專案健康 API
|
||
- **GIVEN** 後端系統運行中
|
||
- **WHEN** 客戶端請求 `GET /api/projects/health`
|
||
- **THEN** 系統回傳所有可存取專案的健康數據
|
||
- **AND** 包含 `total_tasks`, `completed_tasks`, `overdue_tasks`, `blocked_tasks`, `risk_score`
|
||
|
||
#### Scenario: 單一專案健康詳情
|
||
- **GIVEN** 主管需要查看特定專案詳情
|
||
- **WHEN** 客戶端請求 `GET /api/projects/{id}/health`
|
||
- **THEN** 系統回傳該專案的詳細健康數據
|
||
- **AND** 包含任務分類統計與風險評估
|
||
|
||
### Requirement: Team Workload Distribution
|
||
|
||
系統 SHALL 提供團隊工作分配查詢功能。
|
||
|
||
#### Scenario: 部門負載總覽
|
||
- **GIVEN** 主管需要了解部門整體負載
|
||
- **WHEN** 主管以 `department_id` 參數查詢負載熱圖 API
|
||
- **THEN** 僅顯示該部門成員的負載狀況
|
||
|
||
#### Scenario: 使用者負載詳情
|
||
- **GIVEN** 主管需要了解某人的詳細任務分配
|
||
- **WHEN** 主管查詢使用者負載詳情 API
|
||
- **THEN** 回傳該週指派給該使用者的所有任務
|
||
- **AND** 包含每個任務的 `original_estimate` 與 `due_date`
|
||
|
||
### Requirement: Workload Data Access Control
|
||
|
||
系統 SHALL 限制負載資料的存取權限。
|
||
|
||
#### Scenario: 系統管理員查看所有人
|
||
- **GIVEN** 登入者為 `super_admin`
|
||
- **WHEN** 查詢負載熱圖 API
|
||
- **THEN** 可查看所有使用者的負載資料
|
||
|
||
#### Scenario: 一般使用者查看自己
|
||
- **GIVEN** 登入者為一般使用者
|
||
- **WHEN** 查詢負載熱圖 API 未指定 `user_ids`
|
||
- **THEN** 僅回傳自己的負載資料
|
||
|
||
#### Scenario: 跨部門存取拒絕
|
||
- **GIVEN** 登入者非系統管理員
|
||
- **WHEN** 查詢其他部門使用者的負載
|
||
- **THEN** 系統拒絕存取並回傳 403 Forbidden
|
||
|
||
### Requirement: Workload Heatmap UI
|
||
The system SHALL provide a visual workload heatmap interface for managers.
|
||
|
||
#### Scenario: View workload heatmap
|
||
- **GIVEN** user is logged in as manager or admin
|
||
- **WHEN** user navigates to /workload page without filters
|
||
- **THEN** system displays a heatmap showing all accessible users' workload
|
||
- **AND** users with zero workload are included by default
|
||
- **AND** each user cell is color-coded by load level (green/yellow/red)
|
||
|
||
#### Scenario: Hide empty workloads
|
||
- **GIVEN** user is viewing the workload page
|
||
- **WHEN** user enables the hide_empty filter
|
||
- **THEN** the heatmap excludes users with zero workload
|
||
|
||
#### Scenario: Navigate between weeks
|
||
- **GIVEN** user is viewing the workload page
|
||
- **WHEN** user clicks previous/next week buttons
|
||
- **THEN** the heatmap updates to show that week's workload data
|
||
|
||
#### Scenario: Default week window on Sunday
|
||
- **GIVEN** today is Sunday and user opens workload page without selecting week_start
|
||
- **THEN** the default heatmap window includes tasks due in the upcoming week
|
||
|
||
#### Scenario: View user workload details
|
||
- **GIVEN** user is viewing the workload heatmap
|
||
- **WHEN** user clicks on a specific user's cell
|
||
- **THEN** a modal/drawer opens showing that user's task breakdown
|
||
- **AND** tasks show title, project, time estimate, and due date
|
||
|
||
#### Scenario: Filter by department
|
||
- **GIVEN** user is a system admin
|
||
- **WHEN** user selects a department from the filter
|
||
- **THEN** the heatmap shows only users from that department
|
||
|
||
### Requirement: Manager Workload Visibility
|
||
The system SHALL allow department managers to view workload data for all members within their department.
|
||
|
||
#### Scenario: Manager views department member workload
|
||
- **WHEN** a department manager requests workload data for a user in their department
|
||
- **THEN** system returns the workload data for that user
|
||
|
||
#### Scenario: Manager denied access to other department workload
|
||
- **WHEN** a department manager requests workload data for a user in a different department
|
||
- **THEN** system returns 403 Forbidden error
|
||
|
||
#### Scenario: Regular user cannot view others' workload
|
||
- **WHEN** a non-manager user requests workload data for another user
|
||
- **THEN** system returns 403 Forbidden error
|
||
|
||
### Requirement: Cross-Department Project Membership
|
||
The system SHALL support explicit project membership to enable cross-department collaboration.
|
||
|
||
#### Scenario: Add cross-department member to project
|
||
- **WHEN** project owner adds a user from another department as project member
|
||
- **THEN** user gains access to the project regardless of department
|
||
|
||
#### Scenario: Project member accesses cross-department project
|
||
- **WHEN** a project member from another department accesses project resources
|
||
- **THEN** system grants access based on project membership
|
||
|
||
#### Scenario: Non-member denied access despite same department
|
||
- **WHEN** a user not in project membership list attempts to access confidential project
|
||
- **THEN** system denies access unless user is in the project's department
|
||
|
||
### Requirement: Optimized Relationship Loading
|
||
The system SHALL use efficient query patterns to avoid N+1 query problems when loading related entities.
|
||
|
||
#### Scenario: Project member list loading
|
||
- **WHEN** loading a project with its members
|
||
- **THEN** the system SHALL load all members in at most 2 database queries
|
||
- **AND** NOT one query per member
|
||
|
||
#### Scenario: Task assignee loading
|
||
- **WHEN** loading a list of tasks with their assignees
|
||
- **THEN** the system SHALL batch load assignee details
|
||
- **AND** NOT query each assignee individually
|
||
|
||
#### Scenario: Query count monitoring
|
||
- **WHEN** running in development mode
|
||
- **THEN** the system SHALL log query counts per request
|
||
- **AND** warn when query count exceeds threshold (e.g., 10 queries)
|
||
|
||
## Data Model
|
||
|
||
```
|
||
pjctrl_workload_snapshots
|
||
├── id: UUID (PK)
|
||
├── user_id: UUID (FK -> users)
|
||
├── week_start: DATE
|
||
├── allocated_hours: DECIMAL
|
||
├── capacity_hours: DECIMAL
|
||
├── load_percentage: DECIMAL
|
||
├── created_at: TIMESTAMP
|
||
└── updated_at: TIMESTAMP
|
||
|
||
pjctrl_project_health
|
||
├── id: UUID (PK)
|
||
├── project_id: UUID (FK -> projects)
|
||
├── snapshot_date: DATE
|
||
├── total_tasks: INT
|
||
├── completed_tasks: INT
|
||
├── overdue_tasks: INT
|
||
├── blocked_tasks: INT
|
||
├── risk_score: DECIMAL
|
||
├── created_at: TIMESTAMP
|
||
└── updated_at: TIMESTAMP
|
||
```
|
||
|
||
## Calculation Rules
|
||
|
||
- **負載百分比** = (allocated_hours / capacity_hours) × 100
|
||
- **風險評分** = f(overdue_tasks, blocked_tasks, timeline_remaining)
|
||
- 快取計算結果於 Redis，每小時更新或任務變更時即時更新
|