PROJECT-CONTORL/openspec/specs/task-management/spec.md

# Task Management

## Purpose

任務管理核心系統，支援多層級架構、自定義欄位與多維視角。
## Requirements
### Requirement: Hierarchical Task Structure
系統 SHALL 支援多層級任務架構：空間 (Space) > 專案 (Project) > 任務 (Task) > 子任務 (Sub-task)。

#### Scenario: 建立空間
- **GIVEN** 使用者擁有建立空間的權限
- **WHEN** 使用者建立新空間
- **THEN** 系統建立空間並設定擁有者
- **AND** 空間可包含多個專案

#### Scenario: 建立專案
- **GIVEN** 使用者在某空間內擁有建立專案的權限
- **WHEN** 使用者建立新專案
- **THEN** 系統建立專案並關聯至該空間
- **AND** 設定專案的 Owner、Budget、Timeline、Security_Level

#### Scenario: 建立任務與子任務
- **GIVEN** 使用者在專案內擁有建立任務的權限
- **WHEN** 使用者建立任務或子任務
- **THEN** 系統建立任務並維護父子關係
- **AND** 子任務繼承父任務的部分屬性

### Requirement: Custom Fields
系統 SHALL 支援自定義欄位，包含下拉選單、公式、人員標籤等類型。

#### Scenario: 新增自定義欄位
- **GIVEN** 專案管理者需要追蹤特定資料（如：封裝類型、機台編號、預計良率）
- **WHEN** 管理者在專案中新增自定義欄位
- **THEN** 系統建立欄位定義並套用至該專案所有任務

#### Scenario: 編輯自定義欄位
- **GIVEN** 專案已有自定義欄位
- **WHEN** 管理者修改欄位名稱或選項
- **THEN** 系統更新欄位定義
- **AND** 現有任務的欄位值保持不變

#### Scenario: 刪除自定義欄位
- **GIVEN** 專案已有自定義欄位且有任務包含該欄位的值
- **WHEN** 管理者刪除該欄位
- **THEN** 系統顯示確認對話框說明將刪除所有相關值
- **AND** 確認後刪除欄位定義及所有任務的該欄位值

#### Scenario: 公式欄位計算
- **GIVEN** 任務包含公式類型的自定義欄位
- **WHEN** 相依欄位的值發生變更
- **THEN** 系統自動重新計算公式欄位的值

#### Scenario: 公式欄位循環引用檢查
- **GIVEN** 管理者建立公式欄位
- **WHEN** 公式引用自己或形成循環引用
- **THEN** 系統拒絕建立並顯示錯誤訊息

#### Scenario: 人員標籤欄位
- **GIVEN** 任務包含人員標籤類型的自定義欄位
- **WHEN** 使用者選擇人員
- **THEN** 系統驗證人員存在並建立關聯
- **AND** 被標籤的人員可收到相關通知

#### Scenario: 下拉選單欄位
- **GIVEN** 任務包含下拉選單類型的自定義欄位
- **WHEN** 使用者選擇選項
- **THEN** 系統儲存選擇的值
- **AND** 選項列表由欄位定義提供

#### Scenario: 自定義欄位值顯示
- **GIVEN** 任務有自定義欄位值
- **WHEN** 使用者在列表或看板視角查看任務
- **THEN** 自定義欄位值顯示在任務資訊中
- **AND** 公式欄位顯示計算結果（唯讀）

#### Scenario: 欄位數量限制
- **GIVEN** 專案已有 20 個自定義欄位
- **WHEN** 管理者嘗試新增第 21 個欄位
- **THEN** 系統拒絕新增並顯示數量已達上限的訊息

### Requirement: Input Length Validation
All text input fields SHALL have maximum length constraints to prevent abuse and database issues.

#### Scenario: Task title exceeds limit
- **WHEN** user creates a task with title exceeding 500 characters
- **THEN** request is rejected with 422 Validation Error
- **AND** error indicates field length exceeded

#### Scenario: Description within limit
- **WHEN** user creates a task with description 10000 characters or less
- **THEN** task is created successfully

#### Scenario: Description exceeds limit
- **WHEN** user creates a task with description exceeding 10000 characters
- **THEN** request is rejected with 422 Validation Error

#### Scenario: Comment content limit
- **WHEN** user submits a comment exceeding 5000 characters
- **THEN** request is rejected with 422 Validation Error

### Requirement: Multiple Views
系統 SHALL 支援多維視角：看板 (Kanban)、甘特圖 (Gantt)、列表 (List)、行事曆 (Calendar)。

#### Scenario: 甘特圖視角
- **GIVEN** 使用者選擇甘特圖視角
- **WHEN** 系統載入專案任務
- **THEN** 任務依時間軸顯示為水平條狀
- **AND** 顯示任務相依關係與里程碑

#### Scenario: 甘特圖時間軸縮放
- **GIVEN** 使用者正在查看甘特圖
- **WHEN** 使用者切換縮放層級（日、週、月）
- **THEN** 時間軸相應調整顯示密度
- **AND** 任務條保持正確的相對位置

#### Scenario: 拖拉調整任務日期
- **GIVEN** 使用者正在查看甘特圖
- **WHEN** 使用者拖拉任務條改變位置或長度
- **THEN** 系統更新任務的 start_date 和 due_date
- **AND** 驗證日期合理性（start_date <= due_date）

#### Scenario: 顯示任務依賴關係
- **GIVEN** 任務之間存在依賴關係
- **WHEN** 使用者查看甘特圖
- **THEN** 系統顯示連接任務的箭頭
- **AND** 箭頭方向表示依賴方向（前置任務 → 後續任務）

#### Scenario: 新增任務依賴
- **GIVEN** 使用者在甘特圖上選擇兩個任務
- **WHEN** 使用者建立依賴關係
- **THEN** 系統儲存依賴關係
- **AND** 顯示連接箭頭

#### Scenario: 刪除任務依賴
- **GIVEN** 任務之間存在依賴關係
- **WHEN** 使用者刪除該依賴
- **THEN** 系統移除依賴記錄
- **AND** 連接箭頭消失

#### Scenario: 循環依賴檢測
- **GIVEN** 使用者嘗試建立依賴關係
- **WHEN** 該依賴會形成循環（A → B → C → A）
- **THEN** 系統拒絕建立並顯示錯誤訊息
- **AND** 現有依賴關係保持不變

#### Scenario: 依賴類型支援
- **GIVEN** 使用者建立任務依賴
- **WHEN** 使用者選擇依賴類型
- **THEN** 系統支援以下類型：
  - Finish-to-Start (FS): 前置完成後開始
  - Start-to-Start (SS): 前置開始後開始
  - Finish-to-Finish (FF): 前置完成後完成
  - Start-to-Finish (SF): 前置開始後完成

### Requirement: Task Status Management
系統 SHALL 管理任務狀態，包含標準狀態與自定義狀態。

#### Scenario: 狀態變更
- **GIVEN** 使用者擁有更新任務的權限
- **WHEN** 使用者變更任務狀態
- **THEN** 系統更新狀態並記錄變更時間
- **AND** 觸發相關自動化規則（如有設定）

#### Scenario: 阻礙標記
- **GIVEN** 任務遇到阻礙無法進行
- **WHEN** 工程師將任務標記為 "Blocked"
- **THEN** 系統設定 Blocker_Flag = true
- **AND** 強制發送通知給主管要求介入排解

### Requirement: Task Assignment
系統 SHALL 支援任務指派與時間估算。

#### Scenario: 指派任務
- **GIVEN** 使用者擁有指派任務的權限
- **WHEN** 使用者將任務指派給某人
- **THEN** 系統更新 Assignee 並發送通知
- **AND** 任務計入被指派者的工作負載

#### Scenario: 時間估算與追蹤
- **GIVEN** 任務已被指派
- **WHEN** 使用者設定 Original_Estimate 與回報 Time_Spent
- **THEN** 系統記錄並計算剩餘時間
- **AND** 更新資源負載統計

### Requirement: Kanban View
The system SHALL provide a Kanban board view for tasks with drag-and-drop status management.

#### Scenario: View Kanban board
- **GIVEN** user is on the Tasks page
- **WHEN** user selects Kanban view
- **THEN** tasks are displayed in columns grouped by status
- **AND** each column header shows the status name and task count

#### Scenario: Drag task to change status
- **GIVEN** user is viewing the Kanban board
- **WHEN** user drags a task card to a different status column
- **THEN** the task status is updated via API
- **AND** the card moves to the new column
- **AND** other users viewing the board see the update

#### Scenario: View toggle persistence
- **GIVEN** user switches to Kanban view
- **WHEN** user navigates away and returns
- **THEN** the Kanban view is still selected

### Requirement: Task Detail Modal
The system SHALL provide a task detail modal with comments and attachments.

#### Scenario: Open task detail
- **GIVEN** user is viewing tasks in any view
- **WHEN** user clicks on a task
- **THEN** a modal opens showing task details
- **AND** the modal includes comments section
- **AND** the modal includes attachments section

#### Scenario: Edit task in modal
- **GIVEN** user has task detail modal open
- **WHEN** user modifies task fields and saves
- **THEN** the task is updated via API
- **AND** the task list/board reflects the changes

### Requirement: Task Assignment UI
The system SHALL allow assigning tasks to users during creation and editing.

#### Scenario: Assign task during creation
- **GIVEN** user is creating a new task
- **WHEN** user selects an assignee from the dropdown
- **THEN** the task is created with the selected assignee

#### Scenario: Change task assignee
- **GIVEN** user has task detail modal open
- **WHEN** user changes the assignee
- **THEN** the task assignee is updated
- **AND** the new assignee receives a notification

#### Scenario: Set due date and time estimate
- **GIVEN** user is creating or editing a task
- **WHEN** user sets due date and time estimate
- **THEN** the values are saved with the task
- **AND** the task appears on the appropriate date in calendar view

### Requirement: Space Deletion
系統 SHALL 允許空間擁有者刪除空間（軟刪除）。

#### Scenario: 刪除空白空間
- **GIVEN** 使用者是空間的擁有者
- **AND** 空間內沒有任何專案
- **WHEN** 使用者點擊刪除按鈕並確認
- **THEN** 系統將空間標記為已刪除 (is_active = false)
- **AND** 空間不再顯示於列表中
- **AND** 顯示成功通知

#### Scenario: 刪除含專案的空間
- **GIVEN** 使用者是空間的擁有者
- **AND** 空間內包含一個或多個專案
- **WHEN** 使用者點擊刪除按鈕
- **THEN** 系統顯示警告對話框，說明包含 N 個專案
- **AND** 要求使用者輸入空間名稱以確認刪除
- **WHEN** 使用者正確輸入名稱並確認
- **THEN** 系統將空間標記為已刪除
- **AND** 空間內的專案同時被軟刪除
- **AND** 顯示成功通知

#### Scenario: 非擁有者無法刪除空間
- **GIVEN** 使用者不是空間的擁有者
- **WHEN** 使用者嘗試刪除空間
- **THEN** 系統拒絕操作
- **AND** 顯示權限不足的錯誤訊息

### Requirement: Project Deletion
系統 SHALL 允許專案擁有者刪除專案（軟刪除），並記錄於稽核日誌。

#### Scenario: 刪除專案
- **GIVEN** 使用者是專案的擁有者
- **WHEN** 使用者點擊刪除按鈕
- **THEN** 系統顯示確認對話框，說明專案內的任務數量
- **WHEN** 使用者確認刪除
- **THEN** 系統將專案標記為已刪除 (is_active = false)
- **AND** 專案不再顯示於空間的專案列表中
- **AND** 系統記錄刪除事件至稽核日誌
- **AND** 顯示成功通知

#### Scenario: 非擁有者無法刪除專案
- **GIVEN** 使用者不是專案的擁有者
- **WHEN** 使用者嘗試刪除專案
- **THEN** 系統拒絕操作
- **AND** 顯示權限不足的錯誤訊息

#### Scenario: 刪除專案的稽核記錄
- **GIVEN** 專案擁有者刪除專案
- **WHEN** 刪除操作完成
- **THEN** 稽核日誌記錄以下資訊：
  - event_type: "project.delete"
  - resource_type: "project"
  - action: DELETE
  - user_id: 執行刪除的使用者
  - resource_id: 被刪除的專案 ID
  - changes: [{ field: "is_active", old_value: true, new_value: false }]

### Requirement: Task Dependency Cycle Prevention
The system SHALL detect and prevent circular dependencies between tasks to ensure Gantt charts can be properly rendered.

#### Scenario: Direct circular dependency rejected
- **WHEN** user attempts to create dependency where Task A depends on Task B and Task B depends on Task A
- **THEN** system rejects the operation with 400 Bad Request
- **THEN** error message includes the cycle path (e.g., "Circular dependency detected: A -> B -> A")

#### Scenario: Indirect circular dependency rejected
- **WHEN** user attempts to create dependency that would form a cycle (A -> B -> C -> A)
- **THEN** system rejects the operation with 400 Bad Request
- **THEN** error message includes the full cycle path

#### Scenario: Valid dependency chain accepted
- **WHEN** user creates dependencies forming a valid DAG (directed acyclic graph)
- **THEN** system accepts and saves the dependencies
- **THEN** Gantt chart renders correctly with proper task ordering

### Requirement: Optimistic Locking for Task Updates
The system SHALL use optimistic locking to prevent concurrent update conflicts on tasks.

#### Scenario: Concurrent update detected
- **WHEN** user A and user B both load task at version 1
- **WHEN** user A saves changes, incrementing version to 2
- **WHEN** user B attempts to save with version 1
- **THEN** system returns 409 Conflict error
- **AND** response includes a human-readable message instructing refresh and retry
- **AND** response includes the current and provided version numbers

#### Scenario: Sequential updates succeed
- **WHEN** user loads task at version N
- **WHEN** user saves changes with correct version N
- **THEN** system accepts update and increments version to N+1

### Requirement: Soft Delete Cascade Restore
The system SHALL restore child tasks when parent task is restored from soft delete.

#### Scenario: Parent task restored with children
- **WHEN** soft-deleted parent task is restored
- **THEN** system identifies child tasks deleted at same timestamp
- **THEN** system recursively restores all matching child tasks
- **THEN** audit log records restoration of parent and children

#### Scenario: Selective restore without children
- **WHEN** user explicitly requests restore without cascade
- **THEN** only parent task is restored
- **THEN** child tasks remain in deleted state

## Data Model

```
pjctrl_spaces
├── id: UUID (PK)
├── name: VARCHAR(200)
├── description: TEXT
├── owner_id: UUID (FK -> users)
├── created_at: TIMESTAMP
└── updated_at: TIMESTAMP

pjctrl_projects
├── id: UUID (PK)
├── space_id: UUID (FK -> spaces)
├── title: VARCHAR(200)
├── description: TEXT
├── owner_id: UUID (FK -> users)
├── budget: DECIMAL
├── start_date: DATE
├── end_date: DATE
├── security_level: ENUM('public', 'department', 'confidential')
├── status: VARCHAR(50)
├── created_at: TIMESTAMP
└── updated_at: TIMESTAMP

pjctrl_tasks
├── id: UUID (PK)
├── project_id: UUID (FK -> projects)
├── parent_task_id: UUID (FK -> tasks, nullable)
├── title: VARCHAR(500)
├── description: TEXT
├── assignee_id: UUID (FK -> users)
├── priority: ENUM('low', 'medium', 'high', 'urgent')
├── status: VARCHAR(50)
├── original_estimate: DECIMAL (hours)
├── time_spent: DECIMAL (hours)
├── blocker_flag: BOOLEAN DEFAULT false
├── due_date: DATETIME
├── created_at: TIMESTAMP
└── updated_at: TIMESTAMP

pjctrl_custom_fields
├── id: UUID (PK)
├── project_id: UUID (FK -> projects)
├── name: VARCHAR(100)
├── field_type: ENUM('text', 'number', 'dropdown', 'date', 'person', 'formula')
├── options: JSON (for dropdown)
├── formula: TEXT (for formula type)
├── is_required: BOOLEAN
└── created_at: TIMESTAMP

pjctrl_task_custom_values
├── id: UUID (PK)
├── task_id: UUID (FK -> tasks)
├── field_id: UUID (FK -> custom_fields)
├── value: TEXT
└── updated_at: TIMESTAMP
```

## Real-time Sync

系統使用 WebSocket 實現即時同步，當多人同時編輯同一個專案看板時，狀態能即時更新而不需刷新頁面。