orbit/docs/sdk/README.md

Go SDK 接入说明

当前已实现客户端创建、存活与就绪查询。任务提交、Worker 和流程构建接口按开发计划逐阶段实现。

SDK module：git.yuntuo.hk/k2safe/orbit/sdk/go。服务端与 SDK 在同一 Git 仓库，使用独立 go.mod；SDK 当前仅依赖 Go 标准库。

1. 本地运行当前示例

前置条件：Go 1.27.1、MySQL 8.4+，先按项目根目录 README 迁移数据库并启动服务。

在仓库根目录执行：

cd sdk/go
ORBIT_URL=http://127.0.0.1:8080 go run ./examples/health

期望输出：

liveness=alive readiness=ready scope=database_and_schema

完整示例源码。示例 context 最多等待 5 秒；数据库或迁移未就绪时返回错误并以非零状态退出。

2. 当前真实调用方式

client, err := orbit.NewClient("http://127.0.0.1:8080", orbit.Options{})
if err != nil {
    return err
}

ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()

health, err := client.Readiness(ctx)
if err != nil {
    var responseErr *orbit.HTTPError
    if errors.As(err, &responseErr) {
        // responseErr.StatusCode 是实际 HTTP 状态，例如 503。
    }
    return err
}
fmt.Println(health.Status, health.Scope)

片段需在调用函数中使用并导入标准库包和 orbit；完整可运行程序见上方源码。

Options.HTTPClient 可注入专用 HTTP 客户端。SDK 复制其配置，不修改调用方客户端；禁止自动跟随重定向，限制健康响应大小，不自动重试请求，不将服务端响应正文放进错误。

3. 外部项目的本地接入

仓库尚未发布 SDK 版本。开发期间可使用独立工作区或本地 replace，例如在接入项目中执行：

go mod edit -require=git.yuntuo.hk/k2safe/orbit/sdk/go@v0.0.0
go mod edit -replace=git.yuntuo.hk/k2safe/orbit/sdk/go=/absolute/path/to/orbit/sdk/go
go mod tidy

示例路径需替换为本机实际目录。不要将本机绝对路径 replace 提交为发布依赖。后续发布 SDK 时使用独立 module 标签与兼容说明，在真实仓库取包路径验证后给出 go get 命令；当前不提供不存在的发行版本。

4. 后续 SDK 交付

• P1：凭据配置、幂等提交、查询与待执行取消。
• P2：处理器注册、Worker 容量、WSS、续租与结果确认、优雅退出。
• P3：计划管理、可靠结果订阅与队列控制。
• P4：流程定义、发布、启动、信号与查询。
• P5：有界查询、暂停继续和人工恢复入口。

每阶段同步更新可运行场景、错误处理与兼容测试。业务幂等、外部结果核查与 Outbox 接入责任会与真实代码示例一起说明。