# 任務模型

本頁說明 go-scheduler 任務包含哪些內容，以及會經歷哪些狀態。

## 任務欄位

`Add` 註冊的任務包含排程、action、描述、執行時限、逾時回呼與前置任務清單，並取得以 `atomic.AddInt64` 產生的遞增 `int64` ID。

| action 型別 | 初始狀態 | 可否帶依賴 | 失敗來源 |
|---|---|---|---|
| `func()` | `TaskCompleted` | 否，`Add` 回傳錯誤 | panic（未設執行時限時）、逾時 |
| `func() error` | `TaskPending` | 可 | 回傳 error、panic（未設執行時限時）、逾時 |

只有未設執行時限的任務，panic 才會被 recover 並記為 `TaskFailed`。設定 `time.Duration` 時限後，action 在獨立 goroutine 執行且沒有 `recover`，panic 會讓整個行程結束；見 [超時](/zh/core-concepts-timeouts#逾時行為)。

## 任務狀態

```go
const (
	TaskPending int = iota
	TaskRunning
	TaskCompleted
	TaskFailed
)
```

| 轉換 | 觸發條件 |
|---|---|
| `TaskPending` → `TaskRunning` | 到期觸發，且依賴（如有）已滿足 |
| `TaskRunning` → `TaskCompleted` | action 正常返回 |
| `TaskRunning` → `TaskFailed` | 回傳 error、被 recover 的 panic 或超過執行時限 |
| `TaskPending` → `TaskFailed` | 前置任務失敗（`Stop`）、前置任務不存在，或等待逾時 |
| `TaskCompleted`／`TaskFailed` → `TaskRunning` | 無依賴任務的下一次觸發 |

狀態不會回到 `TaskPending`。有依賴的任務在狀態為 `TaskRunning` 或 `TaskCompleted` 時，後續觸發會直接略過；由於成功後狀態維持 `TaskCompleted`，這類任務最多只會成功執行一次，狀態為 `TaskFailed` 時則會在下一次觸發重新判斷。

## 相關主題

- [排程語法](/zh/core-concepts-schedule) — Cron 欄位、描述符與 `@every`
- [任務依賴](/zh/core-concepts-dependencies) — 前置任務策略與等待規則
- [超時](/zh/core-concepts-timeouts) — 執行時限與逾時回呼
- [排程器生命週期](/zh/core-concepts-lifecycle) — 各操作在 `Start` 前後的行為