# Proposal: Add Gantt View

**Change ID:** `add-gantt-view`
**Issue Reference:** `FEAT-003` (issues.md)
**Status:** Draft
**Author:** Claude
**Date:** 2026-01-05

## Summary

實作甘特圖視角，以時間軸方式呈現專案任務，顯示任務期間、依賴關係和里程碑。

## Motivation

甘特圖是專案管理的核心視覺化工具，可幫助團隊：
- 了解任務時程與排程
- 識別關鍵路徑
- 發現資源衝突和瓶頸
- 追蹤進度與延遲

目前系統僅有看板和列表視角，缺少時間軸視圖，無法直觀地規劃和追蹤專案進度。

## Scope

### In Scope
- Backend: Task model 新增 start_date 欄位
- Backend: TaskDependency model（前置任務關係）
- Backend: 依賴關係 CRUD API
- Frontend: Gantt chart 元件（使用第三方函式庫）
- Frontend: 任務時程編輯（拖拉調整日期）
- Frontend: 依賴關係視覺化（箭頭連線）

### Out of Scope
- 關鍵路徑計算
- 資源分配視圖
- 基線對比功能
- 匯出為圖片/PDF

## Design Decisions

### 任務依賴類型
| Type | 說明 | 範例 |
|------|------|------|
| finish_to_start (FS) | 前置任務完成後才能開始 | 設計完成 → 開發開始 |
| start_to_start (SS) | 前置任務開始後才能開始 | 設計開始 → 文件開始 |
| finish_to_finish (FF) | 前置任務完成後才能完成 | 開發完成 → 測試完成 |
| start_to_finish (SF) | 前置任務開始後才能完成 | 較少使用 |

**預設**: finish_to_start (FS) 為最常見類型

### Data Model 變更
```sql
-- Task 新增欄位
ALTER TABLE pjctrl_tasks ADD COLUMN start_date DATETIME;

-- 新增依賴關係表
CREATE TABLE pjctrl_task_dependencies (
  id UUID PRIMARY KEY,
  predecessor_id UUID REFERENCES pjctrl_tasks(id),
  successor_id UUID REFERENCES pjctrl_tasks(id),
  dependency_type ENUM('FS', 'SS', 'FF', 'SF') DEFAULT 'FS',
  lag_days INT DEFAULT 0,
  created_at TIMESTAMP
);
```

### 前端函式庫選擇
建議使用 **DHTMLX Gantt** 或 **Frappe Gantt**：

| 函式庫 | 優點 | 缺點 |
|--------|------|------|
| DHTMLX Gantt | 功能完整、效能好 | 商業授權 |
| Frappe Gantt | 開源、輕量 | 功能較少 |
| React-Gantt-Chart | React 原生 | 社群較小 |

**建議**: 使用 Frappe Gantt（MIT 授權），足夠基本需求

### API 設計
```
# 依賴關係 API
POST   /api/tasks/{task_id}/dependencies         # 新增依賴
GET    /api/tasks/{task_id}/dependencies         # 取得依賴
DELETE /api/task-dependencies/{dependency_id}   # 刪除依賴

# 任務日期更新（使用現有 API）
PUT    /api/tasks/{task_id}                      # body 包含 start_date, due_date
```

### 日期驗證規則
- start_date 不可晚於 due_date
- 有依賴關係時，根據 dependency_type 驗證日期合理性
- 循環依賴檢測

## Affected Specs

| Spec | Change Type |
|------|-------------|
| task-management | MODIFIED (Multiple Views requirement 甘特圖細節) |

## Risks & Mitigations

| Risk | Mitigation |
|------|------------|
| 複雜依賴關係影響效能 | 限制單任務最多 10 個直接依賴 |
| 循環依賴 | 新增/修改依賴時進行循環檢測 |
| 大型專案載入慢 | 分頁載入或虛擬滾動 |

## Dependencies

- Frappe Gantt（或其他甘特圖函式庫）
- 需要 Task model 已有 due_date 欄位（✓ 已存在）