docs: record phase seven acceptance and sdk integration
This commit is contained in:
@@ -2,6 +2,8 @@
|
||||
|
||||
已实现健康查询、任务单项与[批量提交](../api/batch-tasks.md)/查询/分页/待执行取消、队列创建/查询、[自动 Worker](worker-runtime.md)、[Worker 底层协议 SDK](worker.md) 和 [执行历史查询](../api/execution-history.md)。[人工核查与重试](../api/task-recovery.md) 已提供 ReviewTask、RetryTask 与任务操作审计查询。[安全重试](../api/retries.md) 已提供有限策略、WorkerFailure.Retryable、历史查询及完整例子。[计划调度](../api/schedules.md) 已支持创建、查询、版本发布、暂停/恢复、触发历史与完整示例。[订阅管理](../api/subscriptions.md) 已支持创建、查询、暂停恢复、交付历史与人工重试；[事件消费 SDK](event-consumer.md) 已支持连接、自动心跳、重连与确认。[流程定义发布](../api/workflow-definitions.md)、[实例/控制/信号/操作审计](../api/workflows.md)及[六类人工恢复](../api/workflow-recovery.md)已提供独立SDK；完整历史与更多场景按[开发计划](../08-development-plan.md)继续实现。
|
||||
|
||||
生产接入推荐按[生产接入闭环](production-integration.md)执行：业务 Outbox 持久化幂等身份，SDK 负责 HTTP 受理和查询，Event WebSocket 负责可靠通知，业务 Inbox 负责去重和确认；网络结果不明时始终保留原键核对。
|
||||
|
||||
module：`git.yuntuo.hk/k2safe/orbit/sdk/go`。SDK 使用独立 go.mod，依赖 Go 标准库与 `github.com/coder/websocket v1.8.15`，不引用服务端模型或数据库实现。
|
||||
|
||||
发布候选先执行 [SDK 独立发布门禁](release.md) 和[协议兼容矩阵](compatibility.md)，确认 `GOWORK=off` 下依赖图、竞态测试、vet 和全包构建均通过；门禁不替代业务副作用回归。
|
||||
|
||||
75
docs/sdk/production-integration.md
Normal file
75
docs/sdk/production-integration.md
Normal file
@@ -0,0 +1,75 @@
|
||||
# 生产接入闭环
|
||||
|
||||
这份手册把 SDK、HTTP 查询和 WebSocket 结果通知串成一条可落地的接入链路。它只描述平台协议，不包含任何业务系统名称、行业规则或外部副作用。
|
||||
|
||||
## 1. 接入边界
|
||||
|
||||
业务服务保存操作身份和请求正文，再调用 SDK 提交。`Idempotency-Key` 必须由业务库或 Outbox 持久化，网络超时、进程重启和响应不明时复用原键；不能生成新键猜测服务端是否已提交。受理回执只表示平台已经保存请求，不能当作任务或流程完成。
|
||||
|
||||
```go
|
||||
api, err := orbit.NewClient(baseURL, orbit.Options{Token: token})
|
||||
if err != nil { return err }
|
||||
|
||||
// operationKey 与请求正文一起写入业务库；重试始终复用它。
|
||||
receipt, err := api.SubmitTask(ctx, operationKey, orbit.SubmitTaskRequest{
|
||||
QueueID: queueID, Handler: "file.convert", HandlerVersion: "v1",
|
||||
PayloadVersion: "v1", Payload: json.RawMessage(`{"source_ref":"objects/input.csv"}`),
|
||||
RecoverySafety: orbit.RecoveryReconcileOnly,
|
||||
})
|
||||
if err != nil { return err }
|
||||
taskID := receipt.Task.ID
|
||||
```
|
||||
|
||||
凭据只授予调用方所需的命名空间、队列和动作范围。生产使用 HTTPS；SDK 不负责 TLS 终止、密钥托管或外部业务核查。所有 API 错误都保留 `RequestID`、稳定错误码和 HTTP 状态，日志不得写入 Token、完整业务键或结果正文。
|
||||
|
||||
## 2. 完成通知与权威查询
|
||||
|
||||
结果通知使用 Event WebSocket。连接时声明 `orbit.events.v1` 子协议和允许的来源，SDK 自动发送心跳、在连接断开后重连，并把上一次未确认的投递证明带回新连接。处理器完成业务事务后再调用 `Ack`；处理器失败或进程在提交前退出时不要确认，平台会在租约到期后重投同一交付。
|
||||
|
||||
```go
|
||||
consumer := orbit.NewEventConsumer(api, orbit.EventConsumerOptions{
|
||||
SubscriptionID: subscriptionID,
|
||||
MaxHandlers: 8,
|
||||
})
|
||||
err := consumer.Run(ctx, func(ctx context.Context, delivery orbit.EventDelivery) error {
|
||||
// 先在业务 Inbox 中按 delivery.EventID 去重，再提交业务事务。
|
||||
// 返回 nil 后 SDK 才发送 ACK；返回错误会保留交付等待重投。
|
||||
return applyOnce(ctx, delivery)
|
||||
})
|
||||
if err != nil { return err }
|
||||
```
|
||||
|
||||
通知只推动业务侧再次读取权威状态。收到 `task.completed`、`workflow.stopped` 或 `workflow.review_required` 后，调用 `GetTask`、`GetWorkflow` 或对应历史接口；事件快照不替代当前状态，也不表示外部效果已经完成。没有 WebSocket 时可以使用有界 HTTP 查询作为兜底，但必须使用退避、截止时间和业务键，不得无限轮询。
|
||||
|
||||
## 3. 流程实例的恢复顺序
|
||||
|
||||
流程进入 `NEEDS_REVIEW` 后，接入方按下面顺序处理：
|
||||
|
||||
1. 读取当前实例、当前步骤、相关任务和外部证据，保存当时的 `revision`、步骤 `revision` 与 `activation_id`。
|
||||
2. 使用对应恢复方法提交一个有证据的决定：任务核查、步骤结论、步骤重试、PENDING 接续或等待重建。
|
||||
3. 等待内部结果被消费，再重新读取实例和步骤；不要把恢复回执快照当作实时状态。
|
||||
4. 所有核查事项完成后提交 `ContinueWorkflow`，如果实例仍暂停，再单独提交 `Resume`。
|
||||
5. 使用恢复回执的 `audit_id` 查询操作审计，记录操作者、原因、证据引用和前后状态。
|
||||
|
||||
`STATE_CONFLICT`、`UNAVAILABLE` 或响应未知时保留原请求体和原幂等键，先用相同身份核对；不要把版本刷新后重放成另一种决定。服务端会检查流程版本、步骤版本、激活代次、任务归属、未确认结果、预算和截止时间。
|
||||
|
||||
## 4. 错误处理约定
|
||||
|
||||
| 情况 | 接入方动作 |
|
||||
| --- | --- |
|
||||
| HTTP 超时、连接断开、响应未知 | 保留原键和原请求，查询或用原键重报；不生成新键 |
|
||||
| `STATE_CONFLICT` | 重新读取当前事实和审计，确认是否已有新结果；不能盲目覆盖 |
|
||||
| `UNAVAILABLE` / readiness 503 | 保留业务 Outbox，等待服务恢复；不能把故障改写为任务失败 |
|
||||
| `QUEUE_FULL` / `APPLICATION_FULL` | 按业务退避或转人工，保留原身份；释放前不要无限加并发 |
|
||||
| `NEEDS_REVIEW` | 进入证据核查流程；禁止自动重试未知外部效果 |
|
||||
| WebSocket 断线 | 不确认未完成处理；让租约自然重投，并使用交付证明去重 |
|
||||
|
||||
SDK 的 `revision`、`sequence` 和游标使用字符串 JSON 编码或 `uint64`，业务侧不得转成浮点数。结果正文使用 `json.RawMessage` 保留精确数字；大正文传对象引用并在业务侧设置独立保留和访问策略。
|
||||
|
||||
## 5. 上线前清单
|
||||
|
||||
- 固定服务端版本和 `git.yuntuo.hk/k2safe/orbit/sdk/go` 的 SDK 版本，执行 `go mod verify`。
|
||||
- 运行 `make protocol-check`、`make sdk-check` 和对应版本的真实 MySQL 集成回归。
|
||||
- 持久化提交键、恢复键、业务 Outbox 和消费 Inbox；演练提交回执丢失、进程强杀和 WebSocket 重连。
|
||||
- 为 `/health/live`、`/health/ready` 和独立 `/metrics` 配置内部监控；确认告警不会自动改写业务状态。
|
||||
- 验证凭据轮换、权限撤销、备份恢复、MySQL 切换和容量阈值，再进入生产审批。
|
||||
Reference in New Issue
Block a user