流程实例、控制、信号与操作审计

状态：下表公共 HTTP 与独立 Go SDK 已接入。定义发布见定义接口，人工恢复见恢复接口，完整运行例子见并行作业与回执。SDK 尚未发布正式版本，服务端与 SDK 应使用同一开发版本。

实例筛选分页、历史激活、轮次、信号和信号资源审计、状态事件时间线和Pulse任务流程来源均已接入。旧冻结回执可能不含新增的activation_sequence，应另读当前步骤详情；当前步骤详情只反映当前激活；旧记录保留在数据库，不能把本页的当前视图当作全部历史。

1. 路由、权限与 SDK

下文 {id} 为32位小写十六进制流程实例ID，不是定义ID；身份和命名空间来自凭据。所有读取均检查固定定义引用的全部队列。变更还需要 Content-Type: application/json、Authorization: Bearer <token> 和一个稳定的 Idempotency-Key；键最长128字节，字符规则沿用任务协议。请求体最大512 KiB，拒绝重复字段、大小写别名、未声明字段和多余查询参数。

方法与路径	权限	Go SDK 方法
`POST /v1/workflows`	`workflows:start`；有任务队列时还需 `tasks:submit`	StartWorkflow
`GET /v1/workflows`	`workflows:read`	ListWorkflows；过滤与游标见查询手册
`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

GET成功为200；启动及信号首次受理为201，原键回执为200；控制成功为200。控制响应表示意图已保存，取消结清由后台完成。SDK签名、独立类型及各字段中文说明见调用方法和协议类型。

CLI显式开关分别为：--workflow-access（定义读/发布）、--workflow-run-access（实例读/启动）、--workflow-control-access（实例读/控制）、--workflow-signal-access（实例读/信号）、--workflow-recovery-access（实例读/恢复）、--workflow-audit-access（流程操作审计读）。普通 Worker、定义发布及任务核查权限均不会自动获得流程管理权限。初始化会先验证权限集合再交付凭据，具体命令见示例。

2. 固定版本启动

StartWorkflow(ctx, key, StartWorkflowRequest) 的请求：

{
  "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字符；尾部空格保留，不能替代幂等键

示意完整回执：

{
  "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与当前步骤同事务读取：

{
  "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)：

{"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。详细结清规则见控制设计。

5. 有身份的外部信号

SendWorkflowSignal(ctx, id, key, SendWorkflowSignalRequest)：

{
  "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查询不争夺业务完成权，见信号设计。

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。回归证据和剩余交付范围见公共接入报告。

实例集合读取 GET /v1/workflows 已接入筛选分页，参数、权限及SDK见查询手册。

12 KiB Raw Blame History Unescape Escape