PROJECT-CONTORL/openspec/specs/automation/spec.md

# Automation

## Purpose

自動化系統，提供觸發器與自動報告生成功能。
## Requirements
### Requirement: Trigger-Based Automation
系統 SHALL 支援觸發器 (Triggers)，當特定條件滿足時自動執行動作。

#### Scenario: 狀態變更觸發通知
- **GIVEN** 專案設定了「當任務狀態變更為待測試時，通知設備工程師」的觸發器
- **WHEN** 任務狀態變更為「待測試」
- **THEN** 系統自動發送通知給指定的設備工程師群組

#### Scenario: 截止日期觸發提醒
- **GIVEN** 專案設定了「截止日前 3 天自動提醒」的觸發器
- **WHEN** 任務距離截止日還有 3 天
- **THEN** 系統自動發送提醒給任務指派者

#### Scenario: 建立觸發器
- **GIVEN** 專案管理者需要建立自動化規則
- **WHEN** 管理者設定觸發條件與動作
- **THEN** 系統儲存觸發器規則
- **AND** 規則立即生效

### Requirement: Trigger Conditions
系統 SHALL 支援多種觸發條件類型，包含欄位變更、時間條件、以及 AND-only 複合條件。欄位變更條件 SHALL 支援 `status_id`、`assignee_id`、`priority`、`due_date`、`start_date` 與 `custom_fields`（含 formula），並支援 `equals`、`not_equals`、`changed_to`、`changed_from`、`before`、`after`、`in` 運算子。日期欄位的 `in` SHALL 使用 `{start, end}` 區間且包含邊界。

#### Scenario: 欄位變更條件
- **GIVEN** 觸發器設定為「當 Status 欄位變更為特定值」
- **WHEN** 任務的 Status 欄位變更為該值
- **THEN** 觸發器被觸發

#### Scenario: 時間條件
- **GIVEN** 觸發器設定為「每週五下午 4:00」
- **WHEN** 系統時間達到設定時間
- **THEN** 觸發器被觸發

#### Scenario: 複合條件
- **GIVEN** 觸發器設定為「當 Status = 完成 且 Priority = 高」
- **WHEN** 任務同時滿足兩個條件
- **THEN** 觸發器被觸發

#### Scenario: 日期區間條件
- **GIVEN** 觸發器設定為「due_date in {start, end}」且區間為含邊界
- **WHEN** 任務的 due_date 落在該區間內
- **THEN** 觸發器被觸發

#### Scenario: 自訂欄位（公式）條件
- **GIVEN** 觸發器設定為「custom_fields(公式欄位) equals 目標值」
- **WHEN** 任務的公式欄位計算值符合目標值
- **THEN** 觸發器被觸發

#### Scenario: Cron 表達式觸發
- **GIVEN** 觸發器設定為 cron 表達式 (如 `0 9 * * 1` 每週一早上 9 點)
- **WHEN** 系統時間匹配 cron 表達式
- **THEN** 系統評估並執行該觸發器
- **AND** 記錄執行結果至 trigger_logs

#### Scenario: 截止日期提醒
- **GIVEN** 觸發器設定為「截止日前 N 天提醒」
- **WHEN** 任務距離截止日剩餘 N 天
- **THEN** 系統發送提醒通知給任務指派者
- **AND** 每個任務每個提醒設定只觸發一次

### Requirement: Trigger Actions
系統 SHALL 支援多種觸發動作類型。通知動作 SHALL 支援單人與群組目標（`assignee`、`creator`、`project_owner`、`project_members`、`department:<id>`、`role:<name>`、`user:<id>`），並對收件人去重且排除觸發者本人。

#### Scenario: 發送通知動作
- **GIVEN** 觸發器動作設定為發送通知
- **WHEN** 觸發器被觸發
- **THEN** 系統發送通知給指定對象
- **AND** 通知內容可使用變數（如任務名稱、指派者）

#### Scenario: 群組通知目標
- **GIVEN** 觸發器通知目標為 `project_members` 或 `department:<id>` 或 `role:<name>`
- **WHEN** 觸發器被觸發
- **THEN** 系統通知所有對應成員
- **AND** 去除重複收件人
- **AND** 排除觸發者本人

#### Scenario: 更新欄位動作
- **GIVEN** 觸發器動作設定為更新欄位
- **WHEN** 觸發器被觸發
- **THEN** 系統自動更新指定欄位的值

#### Scenario: 指派任務動作
- **GIVEN** 觸發器動作設定為自動指派
- **WHEN** 觸發器被觸發
- **THEN** 系統自動將任務指派給指定人員

### Requirement: Automated Weekly Report
系統 SHALL 每週五下午 4:00 自動彙整完整任務清單，發送給已訂閱的專案成員（含跨部門成員）。週報內容 SHALL 以收件人為 owner 或 project member 的專案為範圍。

#### Scenario: 週報內容完整清單
- **GIVEN** 週報生成中
- **WHEN** 系統彙整資料
- **THEN** 週報包含各專案的：
  - 本週已完成任務清單（含 completed_at, assignee_name）
  - 進行中任務清單（含 assignee_name, due_date）
  - 逾期任務警示（含 due_date, days_overdue）
  - 阻礙中任務清單（含 blocker_reason, blocked_since）
  - 下週預計完成任務（含 due_date, assignee_name）
- **AND** 不設任務數量上限

#### Scenario: 週報收件人範圍
- **GIVEN** 使用者為專案成員且已開啟週報訂閱
- **WHEN** 週報排程執行
- **THEN** 使用者收到週報

#### Scenario: 阻礙任務識別
- **GIVEN** 任務有未解除的 Blocker 記錄
- **WHEN** 週報查詢阻礙任務
- **THEN** 系統查詢 Blocker 表 resolved_at IS NULL 的任務
- **AND** 顯示阻礙原因與開始時間

#### Scenario: 下週預計任務
- **GIVEN** 任務的 due_date 在下週範圍內
- **WHEN** 週報查詢下週預計任務
- **THEN** 系統篩選 due_date >= 下週一 且 < 下週日
- **AND** 排除已完成狀態的任務

### Requirement: Formula Field Cycle Prevention
The system SHALL detect and prevent circular references in custom field formulas to avoid infinite calculation loops.

#### Scenario: Formula self-reference rejected
- **WHEN** user creates a formula field that references itself
- **THEN** system rejects with 400 Bad Request
- **THEN** error message indicates self-reference is not allowed

#### Scenario: Formula circular reference chain rejected
- **WHEN** user creates formula where Field A references Field B and Field B references Field A
- **THEN** system rejects with 400 Bad Request
- **THEN** error message includes the reference cycle path

#### Scenario: Valid formula references accepted
- **WHEN** user creates formula referencing other fields without cycles
- **THEN** system saves the formula and calculates values correctly

### Requirement: Trigger Execution Retry
The system SHALL retry failed trigger executions with exponential backoff to handle transient failures.

#### Scenario: Trigger succeeds after retry
- **WHEN** trigger execution fails due to transient error
- **THEN** system retries after 1 second delay
- **WHEN** retry succeeds
- **THEN** trigger is marked as successful in execution log

#### Scenario: Trigger exhausts retries
- **WHEN** trigger execution fails 3 consecutive times
- **THEN** system marks trigger execution as permanently failed
- **THEN** system sends alert notification to system administrators
- **THEN** execution log contains all retry attempts with error details

#### Scenario: Non-retryable error
- **WHEN** trigger fails with validation or permission error (4xx)
- **THEN** system does not retry and marks as failed immediately
- **THEN** error is logged with appropriate categorization

### Requirement: Weekly Report Subscription
系統 SHALL 提供週報訂閱管理功能，讓使用者手動開啟或關閉週報。

#### Scenario: 開啟週報訂閱
- **GIVEN** 使用者尚未訂閱週報
- **WHEN** 使用者在 MySettings 開啟週報訂閱
- **THEN** 系統建立或啟用該使用者的 weekly 訂閱

#### Scenario: 關閉週報訂閱
- **GIVEN** 使用者已訂閱週報
- **WHEN** 使用者在 MySettings 關閉週報訂閱
- **THEN** 系統停用該使用者的 weekly 訂閱
- **AND** 後續排程不再發送週報

#### Scenario: 未訂閱預設行為
- **GIVEN** 使用者未開啟週報訂閱
- **WHEN** 週報排程執行
- **THEN** 使用者不會收到週報

## Data Model

```
pjctrl_triggers
├── id: UUID (PK)
├── project_id: UUID (FK -> projects)
├── name: VARCHAR(200)
├── description: TEXT
├── trigger_type: ENUM('field_change', 'schedule', 'creation')
├── conditions: JSON
│   └── { "field": "status", "operator": "equals", "value": "testing" }
├── actions: JSON
│   └── [{ "type": "notify", "target": "group:equipment_engineers" }]
├── is_active: BOOLEAN DEFAULT true
├── created_by: UUID (FK -> users)
├── created_at: TIMESTAMP
└── updated_at: TIMESTAMP

pjctrl_trigger_logs
├── id: UUID (PK)
├── trigger_id: UUID (FK -> triggers)
├── task_id: UUID (FK -> tasks, nullable)
├── executed_at: TIMESTAMP
├── status: ENUM('success', 'failed')
└── error_message: TEXT

pjctrl_scheduled_reports
├── id: UUID (PK)
├── report_type: ENUM('weekly', 'monthly', 'custom')
├── recipient_id: UUID (FK -> users)
├── schedule_cron: VARCHAR(50)
├── last_sent_at: TIMESTAMP
├── next_run_at: TIMESTAMP
├── is_active: BOOLEAN DEFAULT true
├── email_enabled: BOOLEAN DEFAULT false (Email 發送開關)
└── created_at: TIMESTAMP

pjctrl_report_history
├── id: UUID (PK)
├── scheduled_report_id: UUID (FK -> scheduled_reports)
├── generated_at: TIMESTAMP
├── content: JSON
├── sent_to: JSON (array of user IDs)
├── channels_used: JSON (e.g., ["in_app"] or ["in_app", "email"])
├── email_status: ENUM('sent', 'skipped', 'failed', null)
└── status: ENUM('sent', 'failed')
```

## Technical Notes

- 使用 Celery + Redis 處理排程任務
- 觸發器執行採用非同步處理，避免阻塞主流程
- 所有觸發器執行都記錄日誌供追蹤