Files

beabigegg 61fe01cb6b feat: implement workload heatmap module

- Backend (FastAPI):
  - Workload heatmap API with load level calculation
  - User workload detail endpoint with task breakdown
  - Redis caching for workload calculations (1hr TTL)
  - Department isolation and access control
  - WorkloadSnapshot model for historical data
  - Alembic migration for workload_snapshots table

- API Endpoints:
  - GET /api/workload/heatmap - Team workload overview
  - GET /api/workload/user/{id} - User workload detail
  - GET /api/workload/me - Current user workload

- Load Levels:
  - normal: <80%, warning: 80-99%, overloaded: >=100%

- Tests:
  - 26 unit/API tests
  - 15 E2E automated tests
  - 77 total tests passing

- OpenSpec:
  - add-resource-workload change archived
  - resource-management spec updated

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2025-12-29 01:13:21 +08:00

4.6 KiB

Raw Blame History

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

Requirement: Multi-Project Health Dashboard

系統 SHALL 提供多專案健康看板，讓主管一覽所有專案狀態。

Scenario: 專案健康總覽

GIVEN 主管負責多個專案
WHEN 主管開啟健康看板
THEN 顯示所有專案的進度、風險指標、延遲任務數
AND 可依風險程度排序

Scenario: 專案延遲警示

GIVEN 專案有任務超過截止日期
WHEN 主管查看健康看板
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

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，每小時更新或任務變更時即時更新

4.6 KiB Raw Blame History Unescape Escape