docs: record phase seven acceptance and sdk integration

2026-09-21 03:38:25 +08:00
parent 4cd99b8bb6
commit 3c8a9ac47c
5 changed files with 151 additions and 4 deletions
--- a/docs/08-development-plan.md
+++ b/docs/08-development-plan.md
@@ -68,8 +68,8 @@
 | P3 Pulse 完整能力 | 安全重试、延时、Cron/固定间隔、漏跑策略、计划版本、运行中取消、并发许可、配额/背压、可靠结果订阅、批量受理、独立任务核查/人工重试、查询筛选与事务Outbox接入 | 多实例领取/触发竞争、重试上限、取消竞争、队列隔离、积压恢复、事件重复交付 | 已完成平台功能阶段验收：[原范围逐项核对](reports/phase-3.md)、[本轮完整回归](reports/phase-3-delay-recovery.md)。补齐相对延迟、改参数关联示例和四种重试全停恢复场景；20个可运行示例全部通过。全平台生产门槛及SDK首版交付剩余项仍按P6–P7推进 |
 | P4 Weave 主流程 | SDK 定义构建与发布校验、实例、顺序/分支/结构化并行汇合、信号/定时等待、版本绑定 | 重启接续、早到/重复信号、并行竞争、内部事件重放、发布版本兼容；端到端通用流程 | 已完成平台功能阶段验收：[原功能及W01–W17逐项核对](reports/phase-4-5.md)、[版本/暂停/全停回归](reports/phase-4-5-races.md)、[提交故障边界](reports/phase-6-fault-boundaries.md)。研发发布、固定版本、顺序/分支/有限并行、信号/时间等待、公共API/SDK及可运行示例均已交付；生产拓扑与发布兼容继续P6/P7 |
 | P5 Weave 恢复与查询 | 有界查询、暂停继续、取消、人工核查恢复、控制门控与审计 | 轮次与尝试独立预算；暂停/开始/回执/超时竞争；恢复保留预算；未知结果不盲目重复 | 已完成平台功能阶段验收：[原功能核对](reports/phase-4-5.md)。有界查询、独立预算、暂停继续/取消、六类恢复、历史/筛选/事件/来源与SDK场景均已交付；真实竞争、COMMIT断线及进程全停保留原身份、截止和预算。运维、容量与首版发布继续P6/P7 |
-| P6 生产验证与运维 | 完整监控、凭据轮换、备份恢复、滚动升级、运行手册、可复现负载和故障工具 | 对照生产验收清单执行，报告环境/指标/遗留项；容量、RPO/RTO 按真实拓扑验证 | 进行中；已补[精确故障边界](reports/phase-6-fault-boundaries.md)和[进程观测](reports/phase-6-observability.md)；继续业务积压/阶段延迟、凭据轮换及其余生产门槛 |
-| P7 首版交付核对 | SDK 兼容与发布准备、完整 API 手册、场景示例、全量回归及交付清单 | 新接入者按文档跑通全部示例；所有首版能力可追溯到实现与测试；报告实际生产边界 | 进行中；已补[通用文件转换示例](reports/phase-7-file-conversion.md)、[SDK独立发布门禁](reports/phase-7-sdk-release.md)、[当前协议兼容矩阵](reports/phase-7-compatibility.md)、[历史任务 API 双向演练](reports/phase-7-historical-compatibility.md)、[当前回归状态](reports/phase-7-regression-status.md)、[首版交付核对清单](release-checklist.md)、[发布物身份清单](api/operations.md#发布物身份清单)和[容器发布说明](21-container-deployment.md)，镜像已完成 linux/amd64 构建验证，节点版本身份可由 `/version` 核对；`verify --manifest` 已可在数据库核验前绑定候选二进制身份；仍需带标签的完整跨版本矩阵和目标拓扑验收 |
+| P6 生产验证与运维 | 完整监控、凭据轮换、备份恢复、滚动升级、运行手册、可复现负载和故障工具 | 对照生产验收清单执行，报告环境/指标/遗留项；容量、RPO/RTO 按真实拓扑验证 | 进行中；已补[精确故障边界](reports/phase-6-fault-boundaries.md)、[进程观测](reports/phase-6-observability.md)、数据库短暂不可用、备份恢复、GTID 手工提升和定时积压样本；继续业务积压/阶段延迟、凭据轮换及其余生产门槛 |
+| P7 首版交付核对 | SDK 兼容与发布准备、完整 API 手册、场景示例、全量回归及交付清单 | 新接入者按文档跑通全部示例；所有首版能力可追溯到实现与测试；报告实际生产边界 | 进行中；已补[通用文件转换示例](reports/phase-7-file-conversion.md)、[SDK独立发布门禁](reports/phase-7-sdk-release.md)、[当前协议兼容矩阵](reports/phase-7-compatibility.md)、[历史任务 API 双向演练](reports/phase-7-historical-compatibility.md)、[当前回归状态](reports/phase-7-regression-status.md)、[四项闭环验收](reports/phase-7-acceptance-20260921.md)、[首版交付核对清单](release-checklist.md)、[发布物身份清单](api/operations.md#发布物身份清单)和[容器发布说明](21-container-deployment.md)，镜像已完成 linux/amd64 构建验证，节点版本身份可由 `/version` 核对；`verify --manifest` 已可在数据库核验前绑定候选二进制身份；仍需带标签的完整跨版本矩阵和目标拓扑验收 |

 SDK、文档与示例随 P1–P5 同步开发，P7 是全量核对，不是最后才开始补文档。

--- a/docs/release-checklist.md
+++ b/docs/release-checklist.md
@@ -14,6 +14,7 @@
 | 当前协议线一致 | `make protocol-check` | 已通过：HTTP `/v1`、Worker/Event v1、流程 schema 1 |
 | SDK 独立性和发布门禁 | `make sdk-check` | Go 1.27.1 Docker 下独立 module、示例和业务模块 race/vet/build 已通过 |
 | 文档与示例 | 本清单、[接口手册](api/README.md)、[SDK手册](sdk/README.md)、[场景示例](examples/README.md) | 文档链接和 JSON 块已检查；宿主机全量端到端见[当前回归状态](reports/phase-7-regression-status.md) |
+| 四项闭环验收 | [P7 四项验收记录](reports/phase-7-acceptance-20260921.md) | 当前 Docker/MySQL 环境已通过流程恢复、指标告警、故障容量和 SDK 接入闭环；目标生产拓扑仍需单独验收 |

 ## 数据库与安全

@@ -34,14 +35,14 @@
 | 派发未送达、提交前后断线、最终信号竞争 | [故障边界报告](reports/phase-6-fault-boundaries.md)、[当前回归状态](reports/phase-7-regression-status.md) | Go 1.27.1 已通过 MySQL 存储、关键 SDK/Orbit 进程故障组、24 个示例串跑和两个独立业务模块集成；跨版本矩阵和目标拓扑仍待发布环境 |
 | 备份恢复 | `scripts/test-backup-restore.sh`、[恢复报告](reports/phase-6-backup-restore.md) | Go 1.27.1 构建的当前二进制已通过隔离恢复；生产介质待验收 |
 | MySQL 短暂不可用恢复 | `scripts/test-db-recovery.sh`、[恢复报告](reports/phase-6-db-recovery.md) | Go 1.27.1 构建的当前二进制已通过单节点同卷演练；主从/跨故障域待验收 |
-| 运行观测和只读快照 | `/metrics`、`orbit-admin observe snapshot`、[观测手册](api/observability.md) | 固定基数和有界单节点快照已实现 |
+| 运行观测和只读快照 | `/metrics`、`orbit-admin observe snapshot`、[观测手册](api/observability.md) | 固定基数、有界单节点快照、8 条告警规则及离线规则测试已通过；生产采集网络和通知仍待目标环境 |
 | 告警、值守、回滚/前向修复 | 目标监控、值班和发布工单 | 待目标环境 |

 ## 容量与生产高可用

 | 项目 | 必须提供的证据 | 状态 |
 | --- | --- | --- |
-| 受理、派发、流程推进和恢复吞吐 | 固定硬件、数据量、任务/流程混合模型，p50/p95/p99和资源曲线 | 已有受理样本、[真实Worker短/混合/中长执行样本](reports/phase-6-execution-load.md)、[Weave双分支流程样本](reports/phase-6-workflow-load.md)及[定时集中触发/积压曲线样本](reports/phase-6-backlog.md)；目标硬件资源曲线、生产容量和HA仍未验收 |
+| 受理、派发、流程推进和恢复吞吐 | 固定硬件、数据量、任务/流程混合模型，p50/p95/p99和资源曲线 | 已有受理样本、[真实Worker短/混合/中长执行样本](reports/phase-6-execution-load.md)、[Weave双分支流程样本](reports/phase-6-workflow-load.md)、[定时集中触发/积压曲线样本](reports/phase-6-backlog.md)及本轮[四项闭环验收](reports/phase-7-acceptance-20260921.md)；目标硬件资源曲线、生产容量和HA仍未验收 |
 | 100万+企业规模推导 | [容量模型](19-capacity-model.md)：租户、队列、连接、事件、索引和保存周期的参数化推导 | 已建立计算方法和演算样例；目标业务数据、硬件、拓扑和生产容量仍未验收，不能由企业数直接承诺 |
 | MySQL 复制、切换、RPO/RTO | [隔离 GTID 复制与手工提升演练](reports/phase-6-mysql-replication.md)；目标拓扑上的实际切换、复制确认、恢复点和恢复时间 | 隔离源库/副本复制、手工提升和原幂等键重放已通过；自动切换、目标拓扑、RPO/RTO仍未验收 |
 | 慢消费者、重连风暴、磁盘和锁等待 | 受控故障负载及积压清空证据 | SDK 受控连续断线和真实 HTTP/WebSocket 容量1慢消费者已回归（见[重连报告](reports/phase-6-reconnect-storm.md)、[慢消费者报告](reports/phase-6-slow-consumer.md)）；跨节点风暴、磁盘和锁等待未验收 |
--- a/docs/reports/phase-7-acceptance-20260921.md
+++ b/docs/reports/phase-7-acceptance-20260921.md
@@ -0,0 +1,69 @@
+# P7 四项闭环验收记录
+
+日期：2026-09-21。本文把流程恢复、运行观测、故障/容量和 SDK 接入放在同一次当前提交验收中。所有结果来自本地 Docker、一次性 MySQL 8.4 和 Go 1.27.1；它们证明代码链路可复现，不替代目标生产拓扑的容量、复制切换、RPO/RTO 和发布审批。
+
+## 1. 真实流程恢复闭环
+
+执行：
+
+```sh
+make integration
+```
+
+关键结果：
+
+- `TestIntegrationWorkflowRecovery` 通过 UNKNOWN 执行核查、步骤结论、继续、任务重试、POLL PENDING、SIGNAL/TIMER 等待恢复、旧证据保护、预算和截止时间保护、审计失败回滚及权限/修订冲突。
+- `TestIntegrationWorkflowRuntimeProcess` 通过控制器全停、两个新进程接管、人工恢复后继续、POLL 同轮恢复和等待代次重建。
+- `TestIntegrationWorkflowInstancesSDK` 通过公共 HTTP 与独立 SDK 的六类恢复命令、流程控制、信号、审计和真实 Worker 执行。
+- WebSocket 结果交付、ACK 丢失、慢消费者、自然租约重投和跨节点接管均通过；完整 MySQL 集成退出 0。
+
+控制台资源也使用同一公共接口：`/console/`、`/console/app.js`、`/console/styles.css` 返回 200，`NEEDS_REVIEW` 恢复入口要求当前修订、证据引用、原因、显式确认和幂等键。
+
+## 2. 指标与告警
+
+执行：
+
+```sh
+go test ./internal/observability ./cmd/orbit -count=1
+docker run --rm --entrypoint /bin/promtool \
+  -v "$PWD:/work:ro" prom/prometheus:v3.5.0 \
+  check rules /work/deploy/monitoring/orbit.rules.yml
+docker run --rm --entrypoint /bin/promtool \
+  -v "$PWD:/work:ro" prom/prometheus:v3.5.0 \
+  test rules /work/deploy/monitoring/orbit.rules.test.yml
+```
+
+结果：指标单元与真实进程采样通过；Prometheus 规则加载 8 条成功，触发、启动宽限、健康不报警、错误恢复和截断恢复测试通过。指标保持独立监听、固定基数、无业务 ID 标签；告警只触发调查，不自动改写任务或流程状态。
+
+## 3. 故障、备份和容量样本
+
+| 场景 | 命令 | 当前结果 |
+| --- | --- | --- |
+| MySQL 短暂不可用 | `scripts/test-db-recovery.sh` | readiness 在故障时 503，恢复后 200，恢复后任务可受理 |
+| 逻辑备份恢复 | `scripts/test-backup-restore.sh` | 源库/恢复库核心计数一致，schema 28、外键 0、固定观测索引 6 |
+| GTID 复制与手工提升 | `scripts/test-mysql-replication.sh` | 复制同步、源库停止、副本手工提升和原幂等键重放通过；自动切换仍未宣称完成 |
+| 集中定时积压 | `ORBIT_BACKLOG_RUN_TIMEOUT=20s scripts/test-schedule-backlog.sh` | 256 个 occurrence 全部持久化，32 个计划均暂停确认，外键 0；保留有界曲线和指标采样，工具的预期 `tool_exit=1` 表示到达负向截止样本 |
+
+长时积压样本继续使用 180 秒默认窗口；样本只用于比较积压清空、CPU/RSS、MySQL 资源和连接池曲线，不能直接外推生产吞吐或百万企业容量。
+
+## 4. SDK 与业务接入
+
+执行：
+
+```sh
+make sdk-check
+make protocol-check
+make docs-check
+make release-local-check
+```
+
+结果：SDK 独立 module、`GOWORK=off`、竞态测试、vet、全包构建、协议版本检查和 149 个 Markdown 本地链接均通过；公共 SDK 的流程恢复、事件消费、Outbox/Inbox、提交回执丢失和 WebSocket 重连已有真实服务示例。新增[生产接入闭环](../sdk/production-integration.md)，明确 Outbox、HTTP 受理、WebSocket 通知、Inbox 去重、错误分类和上线清单。
+
+## 5. 仍需目标环境验收
+
+- 生产硬件和混合负载下的 p50/p95/p99、磁盘、锁等待、复制延迟和容量余量。
+- 自动故障切换、目标拓扑 RPO/RTO、备份介质和恢复工单。
+- 生产监控通知、值班升级、凭据托管、日志脱敏和发布审批。
+- 正式标签之间的完整 SDK/服务端双向兼容矩阵。
+
+这些项目继续保留在[首版交付清单](../release-checklist.md)中，不能用本地回归结果替代。
--- a/docs/sdk/README.md
+++ b/docs/sdk/README.md
@@ -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 和全包构建均通过；门禁不替代业务副作用回归。
--- a/docs/sdk/production-integration.md
+++ b/docs/sdk/production-integration.md
@@ -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 切换和容量阈值，再进入生产审批。