# Proposal: add-resource-workload

## Summary

實作資源管理系統的核心功能：負載熱圖與容量追蹤。讓主管能夠視覺化了解團隊成員的工作負載狀況，並進行資源分配決策。

## Motivation

根據 `project.md` 的核心目標：
- 提供**即時資源負載與專案進度分析**
- 讓 Unit Managers 獲得**團隊工作負載可見度、資源分配熱圖**
- 減輕工程師的**時間回報負擔**

目前系統已完成 `user-auth` 和 `task-management`，具備：
- 使用者資料與容量（capacity）欄位
- 任務的時間估算（original_estimate）與實際耗時（time_spent）
- 任務指派（assignee_id）與截止日期（due_date）

基於現有基礎，可以開始計算並展示資源負載資訊。

## Scope

### In Scope (Phase 1 - 核心負載功能)

1. **Workload Heatmap API**
   - 計算每位成員的週負載百分比
   - 依負載狀態分類（綠色/黃色/紅色）
   - 支援時間範圍查詢

2. **User Capacity Management**
   - 更新使用者容量設定 API
   - 容量歷史記錄（未來週數的容量調整，如請假）

3. **Workload Snapshot Storage**
   - 建立 `pjctrl_workload_snapshots` 表
   - 定期快照或即時計算策略

4. **Team Workload Overview API**
   - 部門級別的負載總覽
   - 支援按專案或部門篩選

### Out of Scope (Future Phases)

- Multi-Project Health Dashboard（需要更多專案進度數據）
- 資源分配不均的自動建議
- 資源分配 AI 預測
- WebSocket 即時更新

## Affected Specs

- `resource-management` - 實作以下需求：
  - Workload Heatmap（部分）
  - Capacity Planning（部分）
  - Team Workload Distribution（部分）

## Dependencies

- `user-auth` - 使用者認證與權限
- `task-management` - 任務與時間估算數據來源

## Risks

| Risk | Impact | Mitigation |
|------|--------|------------|
| 負載計算效能 | 大量任務時計算緩慢 | 使用 Redis 快取計算結果 |
| 任務時間數據不完整 | 無 original_estimate 的任務無法計算 | 提供預設值或排除計算 |
| 週邊界定義不一致 | 不同使用者對「週」的理解不同 | 統一使用 ISO 週（週一至週日）|

## Success Criteria

- [ ] 主管可查看團隊成員的週負載熱圖
- [ ] 負載百分比正確反映任務分配時數 vs 容量
- [ ] 支援按部門篩選負載視圖
- [ ] API 回應時間 < 500ms（快取命中時 < 100ms）