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