# 工作流事件日志

工作流事件日志会为每个持久化工作流边界记录跟踪信息。每个跟踪事件都可以包含步骤输入、输出、步骤前的公开状态、步骤后的公开状态、运行时上下文、制品引用、流式分块、时间信息和错误详情。

## 记录的内容

| 事件 | 发生时机 | 捕获的数据 |
|---|---|---|
| `step_started` | 步骤处理程序运行之前 | 作业 ID、队列、尝试次数、步骤名称、步骤类型、输入和执行前的状态 |
| `step_completed` | 步骤处理程序成功之后 | 输入、输出、执行前的状态、执行后的状态、上下文、制品、分块和持续时间 |
| `step_failed` | 步骤处理程序抛出异常时 | 输入、执行前的状态、可用时的执行后状态、上下文、错误类、错误消息、跟踪信息和持续时间 |
| `step_branch_completed` | 一个并行分支成功时 | 分支输入、输出、执行前的状态、执行后的状态、上下文和持续时间 |
| `step_item_completed` | 一个 for-each 项成功时 | 项目输入、输出、执行前的状态、执行后的状态、项目元数据、上下文和持续时间 |
| `workflow_waiting` | 等待步骤暂停运行时 | 等待类型、等待目标、等待模式、结果键、匹配元数据和等待期间的状态 |
| `workflow_resumed` | 等待步骤满足条件时 | 恢复执行的载荷、恢复执行前的状态和恢复执行后的状态 |
| `workflow_replayed` | 重新创建导出时 | 源工作流元数据和重放状态 |

## 查询时间线

```php
$events = Queuety::workflow_timeline( $workflow_id );

foreach ( $events as $event ) {
    echo $event['step_index'] . ' ' . $event['event'] . ' ' . $event['handler'] . "\n";

    if ( 'step_completed' === $event['event'] ) {
        $input        = $event['input'];
        $output       = $event['output'];
        $state_before = $event['state_before'];
        $state_after  = $event['state_after'];
    }

    if ( 'step_failed' === $event['event'] ) {
        echo 'Error: ' . $event['error']['message'] . "\n";
    }
}
```

每条事件记录都包含：

- `id`
- `workflow_id`
- `job_id`
- `parent_event_id`
- `step_index`
- `step_name`
- `step_type`
- `handler`
- `event`
- `queue`
- `attempt`
- `input`
- `output`
- `state_before`
- `state_after`
- `context`
- `artifacts`
- `chunks`
- `error`
- `duration_ms`
- `created_at`

## 规范化跟踪数据包

构建调试器 UI 时，请使用 `workflow_trace()`：

```php
$trace = Queuety::workflow_trace( $workflow_id );
```

跟踪数据包包含：

- `workflow`
- `steps`
- `events`
- `jobs`
- `logs`
- `artifacts`
- `chunks`
- `signals`
- `wait_dependencies`

`steps` 按步骤索引对事件分组，并为每个步骤包含最新的重要事件。

## 步骤状态查询

```php
$state = Queuety::workflow_state_at( $workflow_id, $step_index );
```

这会返回该步骤最近一次已完成或已恢复事件中的公开 `state_after`；如果未记录状态，则返回 `null`。

## 运行时跟踪元数据

处理程序运行期间可以添加应用级跟踪详情：

```php
Queuety::trace_input( [ 'resolved' => $resolved_input ] );
Queuety::trace_context( [ 'ability' => 'content/load-post' ] );
Queuety::trace_output( [ 'post' => $post ] );
```

步骤处理程序也可以返回保留的跟踪元数据：

```php
return [
    'result' => 'done',
    '_queuety_trace' => [
        'input' => [ 'resolved' => $resolved_input ],
        'context' => [ 'node_id' => 'loadPost' ],
        'artifacts' => [
            [ 'key' => 'brief', 'kind' => 'markdown' ],
        ],
    ],
];
```

`_queuety_trace` 键会存储在事件日志中，不会合并到工作流状态。

## CLI

以表格形式查看时间线：

```bash
wp queuety workflow timeline 42
```

查看步骤执行后的状态：

```bash
wp queuety workflow state-at 42 0
```

## 保留期限

事件日志会随着时间累积。使用 `prune()` 删除旧的跟踪事件：

```php
$deleted = Queuety::workflow_events()->prune( 30 );
```