feat: expose workflow runtime through HTTP and Go SDK
This commit is contained in:
@@ -26,8 +26,9 @@
|
||||
| `/v1/schedules`、不可变版本、暂停/恢复及触发查询 | P3 已实现 | [计划接口与 SDK 场景](schedules.md) |
|
||||
| `/v1/subscriptions` 及管理、交付查询与重试 | 已实现 HTTP、管理 SDK 和完整管理示例 | [订阅手册](subscriptions.md) |
|
||||
| `/v1/events/connect` | 已实现 WSS、消息 Schema、连接 SDK 和自动消费器 | [消息协议](subscriptions.md#5-websocket-建连与边界) / [消费 SDK](../sdk/event-consumer.md) |
|
||||
| `/v1/workflow-definitions` 创建、发布与固定版本读取 | P4定义子项已实现，实例执行尚未实现 | [定义接口](workflow-definitions.md)、[格式规范](workflow-definition-format.md) |
|
||||
| `/v1/workflows` 与流程管理 | 计划 P4–P5，尚未实现 | [流程接口规划](workflows.md) |
|
||||
| `/v1/workflow-definitions` 创建、发布与固定版本读取 | P4定义子项已实现，实例另用启动接口 | [定义接口](workflow-definitions.md)、[格式规范](workflow-definition-format.md) |
|
||||
| `/v1/workflows`、步骤详情、控制、信号及操作审计 | 已接入HTTP与独立SDK | [实例接口](workflows.md) |
|
||||
| `/v1/workflows/{id}/recovery/*` 六类人工恢复 | 已接入有证据恢复及独立SDK | [恢复接口](workflow-recovery.md) |
|
||||
|
||||
未实现路由返回 404。健康检查就绪不表示任务执行、定时调度或流程引擎已经可用。
|
||||
|
||||
|
||||
@@ -63,3 +63,5 @@ P3 独立任务核查、人工重试和操作审计分别增加 `tasks:review`
|
||||
P3 结果订阅核心新增 `events:read`、`events:manage` 和 `events:consume`，bootstrap 仅显式 `--event-access` 时授予。订阅绑定创建凭据与单个队列，不能用同命名空间的另一张凭据消费或管理。当前 HTTP/WSS、管理及消费 SDK 已接入；凭据重绑继续开发，详见 [订阅接口](subscriptions.md)。
|
||||
|
||||
P4定义发布新增`workflows:definitions:read`与`workflows:definitions:publish`，仅显式`--workflow-access`授予。创建/读取元数据作用于命名空间，发布及读取完整版本额外校验全部引用队列；默认提交/Worker凭据不获此权限。发布不创建任务，不要求tasks:submit，详见[定义API](workflow-definitions.md)。
|
||||
|
||||
P4/P5实例公共接入增加`workflows:start/read/control/signal/recover`及`workflows:audit:read`。五个独立CLI开关`--workflow-run-access`、`--workflow-control-access`、`--workflow-signal-access`、`--workflow-recovery-access`、`--workflow-audit-access`分别明确授予。前四个同时包含实例读取；audit只授予流程操作审计读取。原`--workflow-access`仍仅授予定义读/发布，任务`--recovery-access`不授予流程恢复。全部固定队列仍按当前凭据校验，详见[实例权限表](workflows.md#1-路由权限与-sdk)。初始化权限集合在交付凭据前校验。
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 流程定义与不可变版本
|
||||
|
||||
状态：P4 定义校验、持久化发布及独立 Go SDK 已实现；实例启动、推进、等待和恢复尚未实现。规则格式见[结构版本1](workflow-definition-format.md)，可运行源码及命令见[研发发布场景](../examples/workflow-definition.md)。
|
||||
状态：P4 定义校验、持久化发布及独立 Go SDK 已实现；实例启动、控制、等待和恢复已接入[实例API](workflows.md)及[恢复API](workflow-recovery.md)。规则格式见[结构版本1](workflow-definition-format.md)，可运行源码及命令见[研发发布场景](../examples/workflow-definition.md)。
|
||||
|
||||
## 1. 权限、传输与范围
|
||||
|
||||
|
||||
146
docs/api/workflow-recovery.md
Normal file
146
docs/api/workflow-recovery.md
Normal file
@@ -0,0 +1,146 @@
|
||||
# 流程人工核查与恢复 API / SDK
|
||||
|
||||
状态：六类内部恢复已接入公共HTTP和独立SDK。所有路径以 `/v1/workflows/{id}/recovery/` 开头，均为POST，要求 `workflows:recover`、全部固定队列范围、Bearer凭据、稳定Idempotency-Key及application/json。成功首次与重复响应均为200。身份、读查询、错误码见[实例接口](workflows.md)。
|
||||
|
||||
恢复只针对NEEDS_REVIEW实例。SDK不会自动重试、补齐声明、刷新版本或生成新键。核查前应读取当前实例、当前步骤、相关任务及外部证据；每次新决定使用当前版本，响应未知则用原决定原键核对。输入和结果最多256 KiB，请求体总计最多512 KiB。
|
||||
|
||||
## 1. 公共字段
|
||||
|
||||
所有请求包含WorkflowRecoveryDecision的**扁平字段**：
|
||||
|
||||
| 字段 | 必填与语义 |
|
||||
| --- | --- |
|
||||
| expected_revision | 必填，当前实例的非零revision十进制字符串，不能用control_revision替代 |
|
||||
| reason | 必填，1–1024个Unicode字符；不允许全空白或NUL |
|
||||
| evidence_ref | 必填，1–512个Unicode字符，不含空白或控制字符；平台不访问引用、不存放秘密 |
|
||||
|
||||
步骤类请求还包含WorkflowStepDecision的扁平字段：step_key（固定定义步骤名，最多64个ASCII字符）、activation_id（当前32位激活ID）、expected_step_revision（当前非零步骤版本字符串）。实例版本、步骤版本及激活身份一起检查，旧激活不能操作新工作。
|
||||
|
||||
服务端检查待消费/隔离Inbox、历史任务归属、仍在执行的尝试及未释放许可。声明为true是操作者确认，不替代服务端验证。恢复不会重置原绝对截止、次数或业务关联；已有停止目标不会被撤销。
|
||||
|
||||
## 2. 六类命令
|
||||
|
||||
| 路径后缀 | SDK方法 / 请求类型 | 额外必填字段与结果 |
|
||||
| --- | --- | --- |
|
||||
| task-review | ReviewWorkflowTask / ReviewWorkflowTaskRequest | task_id、expected_task_revision字符串、execution_settled=true、outcome=SUCCEEDED或FAILED、非null result；核实本实例任一历史激活的待核查执行 |
|
||||
| step-resolve | ResolveWorkflowStep / ResolveWorkflowStepRequest | 步骤公共字段、execution_settled=true、outcome=SUCCEEDED或FAILED、result；确认当前叶子步骤的逻辑结论 |
|
||||
| continue | ContinueWorkflow / ContinueWorkflowRequest | review_resolved=true；确认全部核查事项已处理后解除核查 |
|
||||
| step-retry | RetryWorkflowStep / RetryWorkflowStepRequest | 步骤公共字段、safe_to_retry=true；为TASK/POLL创建新激活，保留原预算和截止 |
|
||||
| poll-continue | ContinueWorkflowPoll / ContinueWorkflowPollRequest | 步骤公共字段、pending_confirmed=true；权威结果已确认为PENDING时按原间隔恢复等待，不重查同轮 |
|
||||
| wait-rearm | RearmWorkflowWait / RearmWorkflowWaitRequest | 步骤公共字段、wait_verified=true；独立SIGNAL/TIMER在原截止内更换等待代次，含首次最多32代 |
|
||||
|
||||
所有确认布尔值必须在HTTP中显式提供且为true。拒绝嵌套`Decision`、伪造actor_id、大小写别名和未声明字段。
|
||||
|
||||
执行核查请求示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"expected_revision":"8",
|
||||
"reason":"已核实请求完成且外部作业仍在处理",
|
||||
"evidence_ref":"evidence:query-001",
|
||||
"task_id":"88888888888888888888888888888888",
|
||||
"expected_task_revision":"4",
|
||||
"execution_settled":true,
|
||||
"outcome":"SUCCEEDED",
|
||||
"result":"PENDING"
|
||||
}
|
||||
```
|
||||
|
||||
ReviewTask只改变执行结论，旧UNKNOWN尝试和证据保持原样。它产生新的内部结果，必须等待后台消费，当前步骤及实例不会自动解除核查。POLL请求成功不等于流程业务成功；ResolveStep对POLL的成功结果必须映射到固定的业务成功值，不能把PENDING写成步骤成功。TIMER成功只能在首次等待时长满足后确认，result必须为显式null。
|
||||
|
||||
PENDING接续请求示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"expected_revision":"11",
|
||||
"reason":"沿原间隔继续查询外部作业",
|
||||
"evidence_ref":"evidence:query-001",
|
||||
"step_key":"query",
|
||||
"activation_id":"66666666666666666666666666666666",
|
||||
"expected_step_revision":"3",
|
||||
"pending_confirmed":true
|
||||
}
|
||||
```
|
||||
|
||||
相同字段布局适用于step-resolve、step-retry和wait-rearm，额外字段按上表替换。Continue只有实例公共字段及review_resolved，不要求步骤字段。
|
||||
|
||||
## 3. 回执与当前视图
|
||||
|
||||
六个方法统一返回WorkflowRecoveryResult；HTTP的data字段为该对象：
|
||||
|
||||
| 字段 | 含义 |
|
||||
| --- | --- |
|
||||
| instance | 首次管理事务完成时的完整实例快照，字段同[启动回执](workflows.md#2-固定版本启动) |
|
||||
| audit_id | 本次流程管理审计ID，可用GetWorkflowOperation读取原因、证据及前后摘要 |
|
||||
| step | 步骤类操作返回当前步骤快照，包含激活代次；不是后续实时状态 |
|
||||
| task | task-review或step-retry返回执行任务快照；字段同GetTask |
|
||||
| task_audit_id | task-review对应的独立任务审计ID，与流程审计同事务保存 |
|
||||
| deduplicated | 是否恢复原回执；恢复原键仍检查当前权限 |
|
||||
|
||||
步骤恢复回执示意，省略字段按协议确实不存在，并非JSON占位：
|
||||
|
||||
```json
|
||||
{
|
||||
"request_id":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
|
||||
"data":{
|
||||
"instance":{
|
||||
"id":"22222222222222222222222222222222",
|
||||
"namespace_id":"33333333333333333333333333333333",
|
||||
"definition_id":"11111111111111111111111111111111",
|
||||
"definition_version_id":"44444444444444444444444444444444",
|
||||
"version":"v1","state":"NEEDS_REVIEW","revision":"13",
|
||||
"paused":false,"control_revision":"3",
|
||||
"input":{"n":9007199254740993},"business_key":"operation-001 ",
|
||||
"deadline_at":"2026-09-18T08:01:00Z",
|
||||
"created_at":"2026-09-18T08:00:00Z","updated_at":"2026-09-18T08:00:10Z"
|
||||
},
|
||||
"audit_id":"99999999999999999999999999999999",
|
||||
"step":{
|
||||
"id":"55555555555555555555555555555555","key":"query","kind":"POLL",
|
||||
"state":"WAITING","revision":"4",
|
||||
"activation_id":"66666666666666666666666666666666","activation_sequence":1
|
||||
},
|
||||
"deduplicated":false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
ContinuePoll保留当前激活与信号代次；RetryStep及RearmWait创建新激活。恢复等待或创建新任务后仍须显式Continue解除核查；paused仍为true时还需ControlWorkflow(RESUME)。任何恢复操作都不盲目撤回已发生的外部业务效果。
|
||||
|
||||
## 4. SDK接入顺序
|
||||
|
||||
以下为嵌入接入方函数的调用片段，api是已认证Client，workflowID为目标实例，operationKey与本次完整命令需要由调用方持久保存：
|
||||
|
||||
```go
|
||||
current, err := api.GetWorkflowStep(ctx, workflowID, "query")
|
||||
if err != nil { return err }
|
||||
if current.Step.ActivationID == nil { return errors.New("query is not activated") }
|
||||
command := orbit.ContinueWorkflowPollRequest{
|
||||
WorkflowStepDecision: orbit.WorkflowStepDecision{
|
||||
WorkflowRecoveryDecision: orbit.WorkflowRecoveryDecision{
|
||||
ExpectedRevision: current.Revision,
|
||||
Reason: "已核实权威PENDING结果，沿原预算接续",
|
||||
EvidenceRef: "evidence:query-001",
|
||||
},
|
||||
StepKey: current.Step.Key,
|
||||
ActivationID: *current.Step.ActivationID,
|
||||
ExpectedStepRevision: current.Step.Revision,
|
||||
},
|
||||
PendingConfirmed: true,
|
||||
}
|
||||
receipt, err := api.ContinueWorkflowPoll(ctx, workflowID, operationKey, command)
|
||||
if err != nil { return err } // 不生成新键绕过冲突；结果不明时原命令原键核对。
|
||||
audit, err := api.GetWorkflowOperation(ctx, workflowID, receipt.AuditID)
|
||||
if err != nil { return err }
|
||||
fmt.Println(audit.Action, receipt.Instance.State)
|
||||
```
|
||||
|
||||
完整、可执行的六类SDK场景位于[真实服务集成测试](../../sdk/go/workflow_instances_integration_test.go)：UNKNOWN→执行核查→逻辑结论→解除核查；已知失败→剩余预算重试，同时重建信号等待；UNKNOWN查询→核查为PENDING→原间隔接续。运行方式为仓库根目录`make integration`，由脚本创建隔离MySQL、实际服务及凭据。
|
||||
|
||||
一般步骤是：查询当前事实 → 提交一个有证据的决定 → 等待该决定产生的内部结果消费 → 重新读取当前版本 → 再提交下一决定。不要自动将任意STATE_CONFLICT重试为“最新版本”；冲突可能意味着新的在途结果、权限变化、原截止已到或预算耗尽，应重新核查。相同命令的响应未知则仍使用原版本和原键。
|
||||
|
||||
## 5. 兼容与剩余范围
|
||||
|
||||
新路由仅在本开发版本及之后可用；旧服务返回404时不能降级为普通任务重试来绕过Weave所有权。SDK类型独立、版本字段保留uint64精度。规则及数据模型未增加表、字段、外键或级联。
|
||||
|
||||
本批尚不提供完整历史激活/轮次遍历、实例筛选列表或信号资源审计列表；当前输入结果、当前查询预算、单条信号和流程管理审计可读。生产数据库切换、容量及恢复目标继续按P6验证，见[阶段报告](../reports/phase-5-public-api.md)。
|
||||
@@ -1,15 +1,171 @@
|
||||
# 流程接口状态
|
||||
# 流程实例、控制、信号与操作审计
|
||||
|
||||
状态：定义格式校验、创建与不可变版本发布已实现，详见[定义接口](workflow-definitions.md)、[格式规范](workflow-definition-format.md)和[可运行SDK例子](../examples/workflow-definition.md)。实例执行与管理仍按P4–P5开发。下表仅列后续实例接口。
|
||||
状态：下表公共 HTTP 与独立 Go SDK 已接入。定义发布见[定义接口](workflow-definitions.md)，人工恢复见[恢复接口](workflow-recovery.md)，完整运行例子见[并行作业与回执](../examples/workflow.md)。SDK 尚未发布正式版本，服务端与 SDK 应使用同一开发版本。
|
||||
|
||||
| 操作 | 候选接口 | 完成要求 |
|
||||
实例筛选分页、历史激活/轮次/信号列表及 Pulse 任务的流程来源查询继续开发。旧冻结回执可能不含新增的activation_sequence，应另读当前步骤详情；当前步骤详情只反映当前激活；旧记录保留在数据库，不能把本页的当前视图当作全部历史。
|
||||
|
||||
## 1. 路由、权限与 SDK
|
||||
|
||||
下文 `{id}` 为32位小写十六进制流程实例ID，不是定义ID；身份和命名空间来自凭据。所有读取均检查固定定义引用的全部队列。变更还需要 `Content-Type: application/json`、`Authorization: Bearer <token>` 和一个稳定的 `Idempotency-Key`；键最长128字节，字符规则沿用[任务协议](tasks.md)。请求体最大512 KiB，拒绝重复字段、大小写别名、未声明字段和多余查询参数。
|
||||
|
||||
| 方法与路径 | 权限 | Go SDK 方法 |
|
||||
| --- | --- | --- |
|
||||
| 启动实例 | `POST /v1/workflows` | 固定版本并幂等启动，首批任务与实例原子创建 |
|
||||
| 查询实例 | `GET /v1/workflows/{workflow_id}` | 状态、暂停标记、版本、等待原因、预算摘要 |
|
||||
| 查询步骤 | `GET /v1/workflows/{workflow_id}/steps` | 步骤、激活、查询轮次、输入/结果引用与任务关联 |
|
||||
| 提交信号 | `POST /v1/workflows/{workflow_id}/signals` | 幂等、授权、业务操作匹配；受理与消费分别可查 |
|
||||
| 暂停/继续 | `POST /v1/workflows/{workflow_id}:pause`、`:resume` | 控制版本与门控原子变化，保留进度、预算与审计 |
|
||||
| 取消 | `POST /v1/workflows/{workflow_id}:cancel` | 停止后续工作，收集在途结果，不伪装业务撤销 |
|
||||
| 核查恢复 | 具体接口待实现阶段冻结 | 权限、证据、预期版本与稳定操作身份；保留旧激活历史 |
|
||||
| `POST /v1/workflows` | `workflows:start`；有任务队列时还需 `tasks:submit` | StartWorkflow |
|
||||
| `GET /v1/workflows/{id}` | `workflows:read` | GetWorkflow |
|
||||
| `GET /v1/workflows/{id}/steps` | `workflows:read` | GetWorkflowSteps |
|
||||
| `GET /v1/workflows/{id}/steps/{key}` | `workflows:read` | GetWorkflowStep |
|
||||
| `POST /v1/workflows/{id}/control` | `workflows:control` | ControlWorkflow |
|
||||
| `POST /v1/workflows/{id}/signals` | `workflows:signal` | SendWorkflowSignal |
|
||||
| `GET /v1/workflows/{id}/signals/{signal}` | `workflows:read` | GetWorkflowSignal |
|
||||
| `GET /v1/workflows/{id}/operations` | `workflows:audit:read` | ListWorkflowOperations |
|
||||
| `GET /v1/workflows/{id}/operations/{operation}` | `workflows:audit:read` | GetWorkflowOperation |
|
||||
|
||||
配套场景：并行生成结果、等待审核信号、外部作业有界查询、暂停与核查恢复。正式示例将在对应 API 和 SDK 通过端到端验证后提供。节点与状态设计见 [Weave 功能与设计](../06-workflow-spec.md)。
|
||||
GET成功为200；启动及信号首次受理为201，原键回执为200；控制成功为200。控制响应表示意图已保存，取消结清由后台完成。SDK签名、独立类型及各字段中文说明见[调用方法](../../sdk/go/workflow_instances.go)和[协议类型](../../sdk/go/workflow_instance_types.go)。
|
||||
|
||||
CLI显式开关分别为：`--workflow-access`（定义读/发布）、`--workflow-run-access`（实例读/启动）、`--workflow-control-access`（实例读/控制）、`--workflow-signal-access`（实例读/信号）、`--workflow-recovery-access`（实例读/恢复）、`--workflow-audit-access`（流程操作审计读）。普通 Worker、定义发布及任务核查权限均不会自动获得流程管理权限。初始化会先验证权限集合再交付凭据，具体命令见[示例](../examples/workflow.md)。
|
||||
|
||||
## 2. 固定版本启动
|
||||
|
||||
`StartWorkflow(ctx, key, StartWorkflowRequest)` 的请求：
|
||||
|
||||
```json
|
||||
{
|
||||
"definition_id": "11111111111111111111111111111111",
|
||||
"version": "v1",
|
||||
"input": {"n": 9007199254740993},
|
||||
"business_key": "operation-001 "
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型与约束 |
|
||||
| --- | --- |
|
||||
| definition_id | 必填，当前命名空间的定义ID |
|
||||
| version | 必填，1–64个ASCII版本字符，首字符字母或数字，之后还可用 `_ . -`；不解析latest |
|
||||
| input | 必填，最多256 KiB JSON，必须符合固定版本输入契约；显式null与缺失不同，数字不经过float64 |
|
||||
| business_key | 可选，默认空字符串，最多191个Unicode字符；尾部空格保留，不能替代幂等键 |
|
||||
|
||||
示意完整回执：
|
||||
|
||||
```json
|
||||
{
|
||||
"request_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
|
||||
"data": {
|
||||
"instance": {
|
||||
"id": "22222222222222222222222222222222",
|
||||
"namespace_id": "33333333333333333333333333333333",
|
||||
"definition_id": "11111111111111111111111111111111",
|
||||
"definition_version_id": "44444444444444444444444444444444",
|
||||
"version": "v1",
|
||||
"state": "RUNNING",
|
||||
"revision": "2",
|
||||
"paused": false,
|
||||
"control_revision": "1",
|
||||
"input": {"n": 9007199254740993},
|
||||
"business_key": "operation-001 ",
|
||||
"deadline_at": "2026-09-18T08:01:00Z",
|
||||
"created_at": "2026-09-18T08:00:00Z",
|
||||
"updated_at": "2026-09-18T08:00:00Z"
|
||||
},
|
||||
"deduplicated": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`GetWorkflow`的data直接是instance对象。可能状态为RUNNING、WAITING、CANCELLING、NEEDS_REVIEW、SUCCEEDED、FAILED、CANCELLED；paused是独立标记。`output`在存在结果时返回，成功输出可以为显式null。`cancel_requested_at`、`stop_kind`（CANCEL/FAILURE）、`stop_requested_at`、`completed_at`仅有值时返回。所有时间为UTC RFC3339，revision及control_revision为十进制字符串，SDK使用uint64。
|
||||
|
||||
启动固定定义版本和总截止，并在同事务创建门控、步骤和首批任务。原键同内容返回**首次受理快照**，不重算时间，不代表当前状态；同键不同内容返回IDEMPOTENCY_CONFLICT。网络响应丢失时保持原键和原请求核对，再用GetWorkflow读取当前状态。每命名空间最多10000个未终结实例，已保存的原回执在满额时仍可恢复。
|
||||
|
||||
## 3. 步骤及当前激活
|
||||
|
||||
GetWorkflowSteps返回 `{instance_id, revision, steps}`，steps按key排序、最多128项，不含内部根步骤。每项含 `id/key/kind/state/revision`；已激活时还含 `activation_id/activation_sequence`，TASK还含直接 `task_id`。未激活步骤没有激活ID和代次。步骤状态包括BLOCKED、ACTIVE、WAITING、SUCCEEDED、FAILED、CANCELLED、NEEDS_REVIEW、SKIPPED。
|
||||
|
||||
GetWorkflowStep返回单个步骤详情，实例revision与当前步骤同事务读取：
|
||||
|
||||
```json
|
||||
{
|
||||
"request_id": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
|
||||
"data": {
|
||||
"instance_id": "22222222222222222222222222222222",
|
||||
"revision": "8",
|
||||
"step": {
|
||||
"id": "55555555555555555555555555555555",
|
||||
"key": "receipt",
|
||||
"kind": "SIGNAL",
|
||||
"state": "WAITING",
|
||||
"revision": "2",
|
||||
"activation_id": "66666666666666666666666666666666",
|
||||
"activation_sequence": 1
|
||||
},
|
||||
"input": {"name": "done", "payload_version": "v1", "correlation": "operation-001 "},
|
||||
"activated_at": "2026-09-18T08:00:05Z",
|
||||
"wait": {
|
||||
"id": "77777777777777777777777777777777",
|
||||
"kind": "SIGNAL",
|
||||
"state": "WAITING",
|
||||
"name": "done",
|
||||
"payload_version": "v1",
|
||||
"correlation_key": "operation-001 ",
|
||||
"deadline_at": "2026-09-18T08:00:35Z"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- `input/output`属于当前激活，每次只读取一份；未激活或尚无输出时省略，显式null保留。`activated_at/completed_at`属于当前激活，不能据新激活时间重算原预算。
|
||||
- POLL的 `poll` 包含 used_rounds、first_round、first_round_attempts_used、max_rounds、max_attempts_per_round、interval_ms、deadline_at、last_task_id；current_task_id、next_poll_at、resolved_at在有值时返回。last_task_id指当前激活最后业务轮任务，可再通过GetTask读取其状态/版本。
|
||||
- SIGNAL、TIMER和有最终信号的POLL返回 `wait`，包含当前等待身份、类型、状态、原截止和关联；name/payload_version不适用于TIMER，旧未核验等待也可能缺失。winner_signal_id和resolved_at在有值时返回。已选中赢家不代表在途任务已结清。
|
||||
- 时间预算不会随人工换代增加。信号发送者应读取activation_sequence，不能把激活ID、步骤revision或任务尝试epoch当作等待代次。
|
||||
|
||||
## 4. 暂停、继续与取消
|
||||
|
||||
`ControlWorkflow(ctx, id, key, WorkflowControlRequest)`：
|
||||
|
||||
```json
|
||||
{"operation":"PAUSE","expected_control_revision":"1","reason":"维护期间停止推进新工作"}
|
||||
```
|
||||
|
||||
operation必填，为PAUSE/RESUME/CANCEL；expected_control_revision为读取到的非零control_revision字符串，reason为1–1024个Unicode字符，不允许全空白或NUL。成功data为 `{instance, deduplicated}`，instance字段同启动回执。新决定使用旧控制版本返回STATE_CONFLICT；原键恢复仍返回第一次的冻结决定。
|
||||
|
||||
PAUSE关闭新执行授权，在途结果继续收集；RESUME不清除NEEDS_REVIEW，不撤销首次停止目标，不延长原截止。CANCEL保存取消意图并停止后继，保留在途许可直到真实执行结束；未知效果仍进入核查。后台任务结果改变通用revision，不要求操作者追逐每个结果去更新control_revision。详细结清规则见[控制设计](../15-workflow-controls.md)。
|
||||
|
||||
## 5. 有身份的外部信号
|
||||
|
||||
`SendWorkflowSignal(ctx, id, key, SendWorkflowSignalRequest)`：
|
||||
|
||||
```json
|
||||
{
|
||||
"name":"done",
|
||||
"payload_version":"v1",
|
||||
"target_step_key":"receipt",
|
||||
"target_activation_sequence":1,
|
||||
"correlation_key":"operation-001 ",
|
||||
"payload":{"n":9007199254740993},
|
||||
"reason":"已核验外部回执",
|
||||
"evidence_ref":"evidence:receipt-001"
|
||||
}
|
||||
```
|
||||
|
||||
name/payload_version/target_step_key必填，分别最多128/32/64个ASCII名称字符；代次为非零uint32数字。correlation_key为1–512字节UTF8、精确匹配并保留尾部空格。payload必填、最多256 KiB，符合固定契约时可显式null。reason规则同控制原因；evidence_ref可选、最多512个Unicode字符，不含空白或控制字符，平台不会访问这个引用。
|
||||
|
||||
成功data为 `{signal, deduplicated}`。signal字段：id、namespace_id、workflow_id、revision字符串、name、payload_version、target_step_key、target_activation_sequence、correlation_key、payload、actor_id、state、accepted_at、expires_at；evidence_ref、disposition、consumed_wait_id在有值时返回。actor_id从认证获得。GetWorkflowSignal直接返回当前signal对象。
|
||||
|
||||
受理与消费分离：PENDING可以稍后变为CONSUMED、REJECTED或EXPIRED。每实例全部历史受理记录最多1024条，原键回执先于上限检查。早到信号可以指定首次代次1；当前旧代次信号保存为REJECTED/STALE_ACTIVATION，未来代次冲突。恢复为新代次后，原信号原键仍返回旧回执，不能用重报改变目标。最终查询与信号按原事件时间竞争，PENDING查询不争夺业务完成权，见[信号设计](../14-workflow-signals.md)。
|
||||
|
||||
## 6. 操作审计与错误处理
|
||||
|
||||
ListWorkflowOperations接受HistoryPageRequest：limit默认20、范围1–100；cursor最大1024字节，绑定命名空间、流程ID和查询种类，不可跨资源复用。data为 `{items, next_cursor?}`；每项含 id、workflow_id、operation_id、actor_id、action、created_at，按时间及ID倒序。GetWorkflowOperation除这些字段外还返回reason、evidence_ref（可空省略）、before、after JSON摘要。单独读取正文，避免列表聚合大结果。
|
||||
|
||||
该接口当前查询resource_kind=workflow的启动、推进、控制和恢复审计；独立任务核查审计通过恢复回执的task_audit_id关联。信号自身的受理状态通过GetWorkflowSignal读取，信号资源审计列表及完整激活历史继续开发。
|
||||
|
||||
| HTTP/错误码 | 处理方式 |
|
||||
| --- | --- |
|
||||
| 400 INVALID_ARGUMENT | 修正字段、固定契约或查询游标；不要把遗漏声明默认成true |
|
||||
| 401 UNAUTHENTICATED / 403 PERMISSION_DENIED | 核对凭据和显式动作权限，重报不会绕过撤权 |
|
||||
| 404 NOT_FOUND | 资源不存在、跨命名空间或队列不在授权范围 |
|
||||
| 409 STATE_CONFLICT / IDEMPOTENCY_CONFLICT | 当前状态/版本不符或原键请求改变；先读取权威状态 |
|
||||
| 409 WORKFLOW_INSTANCE_LIMIT / WORKFLOW_SIGNAL_LIMIT | 固定资源数量上限，不能通过新键盲目补发 |
|
||||
| 429 QUEUE_FULL / APPLICATION_FULL | 新工作配额不足；保持原请求身份核对，服务端给Retry-After |
|
||||
| 413 BODY_TOO_LARGE / 415 UNSUPPORTED_MEDIA_TYPE | 缩小请求或使用application/json |
|
||||
| 503 UNAVAILABLE / 网络异常 | 提交结果可能不明，保持原键和原命令核对；SDK不自动换键 |
|
||||
|
||||
已实现路由之外的路径为404。回归证据和剩余交付范围见[公共接入报告](../reports/phase-5-public-api.md)。
|
||||
|
||||
Reference in New Issue
Block a user