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** 系統自動重新計算公式欄位的值

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

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

#### Scenario: 看板視角
- **GIVEN** 使用者選擇看板視角
- **WHEN** 系統載入專案任務
- **THEN** 任務依狀態分組顯示為卡片
- **AND** 支援拖拉變更狀態

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

#### Scenario: 列表視角
- **GIVEN** 使用者選擇列表視角
- **WHEN** 系統載入專案任務
- **THEN** 任務以表格形式顯示
- **AND** 支援欄位排序與篩選

#### Scenario: 行事曆視角
- **GIVEN** 使用者選擇行事曆視角
- **WHEN** 系統載入專案任務
- **THEN** 任務依截止日期顯示在行事曆上

### 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

## 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 實現即時同步，當多人同時編輯同一個專案看板時，狀態能即時更新而不需刷新頁面。