orbit/docs/api/README.md

Orbit HTTP / WebSocket 接口手册

更新：2026-09-18。接口实现状态随 开发计划 更新。

当前接口状态

接口	状态	手册
GET /health/live	已实现	健康检查
GET /health/ready	已实现，验证数据库、迁移记录及零外键要求	健康检查
独立监听的 GET /metrics	已实现基础运行指标，默认关闭	运行观测
/v1/tasks 提交、查询、分页与待执行取消	已实现，P3扩展业务键与创建时间筛选	任务接口 / 查询契约
GET /v1/tasks/{task_id}/source	已实现普通、人工重试、计划固定版本及流程历史激活/轮次来源	来源查询
POST /v1/tasks:batch	P3 已实现逐项受理、独立幂等、部分结果与补交	批量任务
/v1/tasks/{task_id}:review / :retry 与 /operations	P3 已实现带证据核查、关联新任务与操作审计	人工恢复
/v1/tasks/{task_id}/attempts 与尝试详情	P2 已实现	执行历史
/v1/tasks/{task_id}/attempts/{attempt_id}/evidence 与证据详情	P2 已实现	执行历史
/v1/queues 创建、查询及 :configure 控制	已实现队列并发、开始速率、积压背压与暂停/恢复	队列接口与 SDK 场景
/v1/application/resources 查询及 :configure 管理	P3 已实现跨命名空间应用配额	应用配额与 SDK 场景
任务 concurrency_key 与尝试 concurrency_token	P3 已实现跨队列资源键互斥	资源键接口与 SDK 场景
任务 priority 与节点领取池	P3 已实现有界优先级加速、应用/队列轮转	优先级与公平派发
凭据校验、初始化、固定操作文件轮换/撤销与回执重放 CLI	P1/P6 已实现；不提供公网管理路由，测试专用提交不明切点已回归	鉴权、凭据报告
orbit-admin verify 发布前结构核验	已实现只读迁移、零外键和 000026–000028 固定索引检查	运维核验
orbit-admin observe snapshot 只读运行快照	已实现固定状态、事件窗口和阶段耗时的有界单节点快照	运维核验
orbit-admin retention inventory 保留清单	已实现带 UTC 截止时间的只读盘点；不执行归档、删除或权限变更	保留清单
sdk/go/cmd/orbit-load 有界受理负载工具	已实现固定并发、无自动重试、延迟百分位和错误分类；只用于隔离环境	负载工具
sdk/go/cmd/orbit-exec-load 有界任务执行测量	已实现真实Worker、固定混合时长、最终结果/尝试核验及阶段耗时分布	执行测量
sdk/go/cmd/orbit-workflow-load 有界流程执行测量	已实现固定版本、双分支并行、真实Worker、步骤/来源/尝试/输出核验及阶段耗时分布	流程测量
定时集中触发测量	已实现	有界计划测量工具
scripts/test-backup-restore.sh 隔离备份恢复演练	已实现一次性 MySQL 逻辑备份、独立恢复、核心计数及零外键核验	备份恢复演练
scripts/test-db-recovery.sh MySQL 短暂不可用恢复演练	已实现 readiness 503、同卷恢复 200 及恢复后任务受理核验	数据库恢复演练
scripts/test-mysql-replication.sh MySQL GTID 复制与手工提升演练	已实现隔离源库/副本复制、源库停止、副本提升、结构核验和原幂等键重放；不提供自动切换	复制与手工提升报告
/v1/worker/connect	P2 已实现并通过阶段验收	Worker 契约、Schema
任务相对延迟 delay_ms	已实现数据库计时、原键恢复与实际执行例子	任务接口、延迟示例
任务冻结策略与 Worker retryable	P3 安全重试已实现	安全重试
/v1/tasks/{task_id}:cancel 与 task.cancel 通知	P3 运行中取消已实现	取消及 SDK 场景
/v1/schedules、不可变版本、暂停/恢复及触发查询	P3 已实现	计划接口与 SDK 场景
/v1/subscriptions 及管理、交付查询与重试	已实现 HTTP、管理 SDK 和完整管理示例	订阅手册
/v1/events/connect	已实现 WSS、消息 Schema、连接 SDK 和自动消费器	消息协议 / 消费 SDK
/v1/workflow-definitions 创建、发布与固定版本读取	P4定义子项已实现，实例另用启动接口	定义接口、格式规范
/v1/workflows、步骤详情、控制、信号及操作审计	已接入HTTP与独立SDK	实例接口
历史激活/轮次/信号列表、历史激活详情及信号资源审计	已接入有界分页HTTP与独立SDK	历史查询
/v1/workflows/{id}/events 及单条事件详情	已接入不可变状态事件、审计权限及独立SDK	状态时间线
/v1/workflows/{id}/recovery/* 六类人工恢复	已接入有证据恢复及独立SDK	恢复接口

未实现路由返回 404。健康检查就绪不表示任务执行、定时调度或流程引擎已经可用。

业务接口统一要求

P1 业务接口已遵守下述约定，后续接口继续沿用：

• 生产使用 HTTPS/WSS，凭据通过授权头或受控握手传递，不放入 URL。
• 应用身份、命名空间和操作权限分别校验；知道资源 ID 不等于拥有权限。
• 稳定幂等键与请求追踪 ID 分开；超时重报保留原键。
• 可能超过跨语言整数精度的 ID 和执行代次使用字符串。
• 时间为 UTC RFC 3339，时长字段带单位；查询和批量操作有上限。
• 错误码、字段、分页游标和限制值在对应阶段实现及回归后冻结。

健康接口直接返回状态对象。已实现的业务接口使用 request_id + data / error 信封；当前实际字段以本目录手册为准，其他尚未实现的接口见 通信协议草案。

每个正式接口的文档模板

实现时必须补齐：用途与权限、HTTP 方法和路径、请求头、字段类型/必填/默认值/限制、完整请求与响应、错误码、幂等与并发规则、超时/重试/取消语义、SDK 对应方法、可运行示例、兼容版本和已覆盖的回归场景。

流程实例筛选分页与权限已接入，固定筛选沿游标分页，覆盖未执行分支的全部队列权限。