feat: establish Orbit models, migrations and development baseline

docs/api/README.md

@@ -0,0 +1,34 @@
+# Orbit HTTP / WebSocket 接口手册
+
+更新：2026-09-17。接口实现状态随 [开发计划](../08-development-plan.md) 更新。
+
+## 当前接口状态
+
+| 接口 | 状态 | 手册 |
+| --- | --- | --- |
+| `GET /health/live` | 已实现 | [健康检查](health.md) |
+| `GET /health/ready` | 已实现，仅验证数据库与迁移记录 | [健康检查](health.md) |
+| `/v1/tasks` 与任务管理 | 计划 P1–P3，尚未实现 | [任务接口规划](tasks.md) |
+| `/v1/worker/connect` | 计划 P2，尚未实现 | [协议草案](../03-http-websocket-protocol.md) |
+| `/v1/schedules` 与计划管理 | 计划 P3，尚未实现 | [协议草案](../03-http-websocket-protocol.md) |
+| `/v1/events/connect` | 计划 P3，尚未实现 | [协议草案](../03-http-websocket-protocol.md) |
+| `/v1/workflows` 与流程管理 | 计划 P4–P5，尚未实现 | [流程接口规划](workflows.md) |
+
+当前服务对未实现路由返回 404。健康检查就绪不表示任务调度、鉴权或流程引擎已经可用。
+
+## 业务接口统一要求
+
+下述业务契约尚在实现阶段细化，不能用于声称当前已有业务 API：
+
+- 生产使用 HTTPS/WSS，凭据通过授权头或受控握手传递，不放入 URL。
+- 应用身份、命名空间和操作权限分别校验；知道资源 ID 不等于拥有权限。
+- 稳定幂等键与请求追踪 ID 分开；超时重报保留原键。
+- 可能超过跨语言整数精度的 ID 和执行代次使用字符串。
+- 时间为 UTC RFC 3339，时长字段带单位；查询和批量操作有上限。
+- 错误码、字段、分页游标和限制值在对应阶段实现及回归后冻结。
+
+健康接口目前直接返回状态对象。业务接口计划使用 `request_id` + `data` / `error` 信封，详见 [通信协议](../03-http-websocket-protocol.md)。
+
+## 每个正式接口的文档模板
+
+实现时必须补齐：用途与权限、HTTP 方法和路径、请求头、字段类型/必填/默认值/限制、完整请求与响应、错误码、幂等与并发规则、超时/重试/取消语义、SDK 对应方法、可运行示例、兼容版本和已覆盖的回归场景。

docs/api/health.md

@@ -0,0 +1,45 @@
+# 健康检查接口
+
+状态：已实现，基础阶段。无需鉴权；默认仅监听 `127.0.0.1:8080`。
+
+## GET /health/live
+
+返回进程 HTTP 服务是否存活，不访问数据库。
+
+```sh
+curl -i http://127.0.0.1:8080/health/live
+```
+
+HTTP 200，`Content-Type: application/json`：
+
+```json
+{"status":"alive"}
+```
+
+## GET /health/ready
+
+检查数据库连接和迁移记录是否与当前二进制的版本、校验和一致且没有 dirty 标记。内部检查最多 2 秒。
+
+```sh
+curl -i http://127.0.0.1:8080/health/ready
+```
+
+通过时 HTTP 200：
+
+```json
+{"status":"ready","scope":"database_and_schema"}
+```
+
+数据库不可用、迁移缺失、记录被修改或存在 dirty 标记时 HTTP 503：
+
+```json
+{"status":"not_ready"}
+```
+
+响应不包含 DSN、数据库错误文本或凭据。检查迁移记录不能发现所有人工 DDL 漂移，运行账户权限和迁移流程仍需受控。
+
+## SDK 与运行限制
+
+对应 `Client.Liveness(ctx)` 和 `Client.Readiness(ctx)`，见 [SDK 接入](../sdk/README.md)。HTTP 503 返回 `*orbit.HTTPError`。
+
+此阶段的 ready 只表示数据库与迁移基础可用；尚无任务、Worker、流程或业务鉴权服务。SDK 默认请求超时为 10 秒，调用方可通过 context 设置更短期限。

docs/api/tasks.md

@@ -0,0 +1,16 @@
+# 任务接口规划
+
+状态：计划 P1–P3，尚未实现。以下为后续落地清单；实际字段与可运行请求将在相应阶段补齐。
+
+| 操作 | 候选接口 | 关键行为 |
+| --- | --- | --- |
+| 提交 | `POST /v1/tasks` | 携带稳定 `Idempotency-Key`，受理提交完成后响应 |
+| 批量提交 | `POST /v1/tasks:batchSubmit` | 每项独立幂等与结果；顶层成功不代表全部成功 |
+| 查询 | `GET /v1/tasks/{task_id}` | 校验命名空间和权限，返回当前状态与结果 |
+| 执行历史 | `GET /v1/tasks/{task_id}/attempts` | 分页返回历史尝试，不展示执行秘密凭据 |
+| 取消 | `POST /v1/tasks/{task_id}:cancel` | 待执行时取消生效；在途工作先记录取消意图 |
+| 人工重试 | `POST /v1/tasks/{task_id}:retry` | 带原因与权限；流程关联任务通过 Weave 恢复 |
+
+提交契约需要队列、处理器/参数版本、业务输入或引用、执行时间、时限、恢复安全等级和重试策略。业务参数内容由接入方解释。
+
+P1 回归完成前，此页不提供看似可调用的 SDK 方法或 HTTP 请求体。接口实现后同步增加完整请求/响应、错误码及文件转换场景。

docs/api/workflows.md

@@ -0,0 +1,16 @@
+# 流程接口规划
+
+状态：计划 P4–P5，尚未实现。研发通过 Go SDK 描述流程并显式发布，服务端保存不可变定义版本。
+
+| 操作 | 候选接口 | 完成要求 |
+| --- | --- | --- |
+| 发布版本 | `POST /v1/workflow-definitions/{definition_id}/versions` | 图结构、类型、预算校验；同版本同内容幂等，不同内容冲突 |
+| 启动实例 | `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` | 停止后续工作，收集在途结果，不伪装业务撤销 |
+| 核查恢复 | 具体接口待实现阶段冻结 | 权限、证据、预期版本与稳定操作身份；保留旧激活历史 |
+
+配套场景：并行生成结果、等待审核信号、外部作业有界查询、暂停与核查恢复。正式示例将在对应 API 和 SDK 通过端到端验证后提供。节点与状态设计见 [Weave 功能与设计](../06-workflow-spec.md)。