orbit/docs/api/README.md

Orbit HTTP / WebSocket 接口手册

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

当前接口状态

接口	状态	手册
GET /health/live	已实现	健康检查
GET /health/ready	已实现，仅验证数据库与迁移记录	健康检查
/v1/tasks 提交、查询、分页与待执行取消	P1 已实现	任务接口
/v1/queues 创建与查询	P1 已实现	队列接口
凭据校验与初始化 CLI	P1 已实现	鉴权
/v1/worker/connect	计划 P2，尚未实现	协议草案
/v1/schedules 与计划管理	计划 P3，尚未实现	协议草案
/v1/events/connect	计划 P3，尚未实现	协议草案
/v1/workflows 与流程管理	计划 P4–P5，尚未实现	流程接口规划

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

业务接口统一要求

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

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

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

每个正式接口的文档模板

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