docs: consolidate runnable examples and publish v0.1.1 guides

README.md

@@ -1,122 +1,277 @@
 # Orbit · 星轨
 
-Orbit 是面向多个业务项目的通用任务调度与流程编排平台，采用 **Go + MySQL + HTTP/WebSocket**。
+**Go + MySQL 构建的任务调度与流程编排平台。** 业务应用通过 HTTP 提交任务，Worker 通过 WebSocket 执行，结果通过可靠订阅交付；任务状态、计划、流程检查点与审计保存在 MySQL。
 
-- **Pulse · 脉动**：异步任务、定时调度、执行授权与安全重试。
-- **Weave · 织流**：研发定义发布流程，管理步骤、等待、有界查询与恢复。
-- 业务处理器运行在接入方 Worker 中；平台不内置行业规则。
+- **Pulse · 脉动**：异步任务、延迟执行、定时计划、执行授权、重试与结果订阅。
+- **Weave · 织流**：研发定义并发布流程，支持顺序、并行、条件分支、等待信号、有界查询和人工恢复。
+- **Console**：账号密码登录的管理页面，查看任务、计划、流程、结果交付及归档作业。
 
-## 当前进度
+主分支：`main`。当前版本：**`v0.1.1`**。源码、SDK 和 Outbox 适配包采用固定版本发布，已发布标签不覆盖。变更见 [CHANGELOG](CHANGELOG.md)。
 
-已完成 P0–P5 平台功能阶段验收：36 个数据模型、版本化迁移、凭据及范围校验、队列与任务 API、WSS 执行、独立 SDK、自动 Worker 和 [执行尝试/证据查询](docs/api/execution-history.md)。[Worker Schema](docs/api/worker-schema.md) 与真实进程强杀恢复回归已通过；[安全重试](docs/api/retries.md)、[定时计划](docs/api/schedules.md)、[运行中取消](docs/api/cancellation.md) 、[队列资源控制](docs/api/queues.md) 、[应用共享配额](docs/api/application-resources.md) 、[资源键互斥](docs/api/keyed-concurrency.md) 和 [优先级/节点公平派发](docs/api/priority-and-fairness.md) 已接入服务端和 SDK，[可靠结果订阅](docs/api/subscriptions.md) 已实现持久化核心、HTTP/WSS、管理 SDK 与示例，[消费 SDK](docs/sdk/event-consumer.md) 和 [独立 MySQL Inbox 示例](docs/examples/result-inbox.md) 已实现；[批量任务受理](docs/api/batch-tasks.md) 已提供逐项幂等、失败分类与 SDK 示例；[人工核查与重试](docs/api/task-recovery.md) 已提供带证据的管理接口、关联新任务、审计查询及运行示例；[业务键与时间范围查询](docs/api/task-queries.md) 已提供过滤、分页与SDK场景；[任务来源查询](docs/api/task-source.md) 已提供人工重试父任务、计划触发记录与固定版本；[业务事务Outbox](docs/examples/task-outbox.md) 已提供独立业务库、稳定提交身份、发送恢复与CLI；[相对延迟执行](docs/examples/delayed-task.md)已提供数据库计时及原请求恢复；完整范围核对见[P3验收](docs/reports/phase-3.md)，生产验证与首版交付按 [持续开发计划](docs/08-development-plan.md) 继续推进。
+## 从这里开始
 
-Weave已提供[定义发布](docs/api/workflow-definitions.md)、[实例启动、步骤详情、暂停/继续/取消、信号和操作审计](docs/api/workflows.md)，以及[六类人工核查恢复](docs/api/workflow-recovery.md)的HTTP与独立Go SDK。持久运行器支持顺序、分支、有限并行、TIMER、SIGNAL及有界POLL，恢复沿用原预算与截止。[并行作业与回执示例](docs/examples/workflow.md)提供完整调用链；[历史激活/轮次/信号及信号审计](docs/api/workflow-history.md)已接入；[实例筛选分页](docs/api/workflow-queries.md)已接入，[状态事件时间线](docs/api/workflow-events.md)已接入，独立[轮询](docs/examples/workflow-poll.md)与[恢复](docs/examples/workflow-recovery.md)示例已接入，已补[版本/暂停竞争/全停回归](docs/reports/phase-4-5-races.md)，功能阶段证据见[P4/P5核对](docs/reports/phase-4-5.md)，提交断线及派发未送达见[故障边界](docs/reports/phase-6-fault-boundaries.md)；[任务流程来源](docs/api/task-source.md#5-流程固定来源)已接入，P4/P5功能阶段已通过，P6生产验证和P7发布交付继续推进。
+| 你要做什么 | 入口 |
+| --- | --- |
+| 第一次启动平台、设置管理员 | [快速开始](#快速开始) |
+| 使用 Docker 启动，后续接入域名 | [Docker 与域名部署](#docker-与域名部署) |
+| 了解全部能力和用法 | [功能一览](#功能一览) |
+| 业务 Go 项目接入 | [SDK 怎么调用](#sdk-怎么调用) |
+| 直接运行完整场景 | [examples：27 个可运行示例](examples/README.md) |
+| 嵌入现有 HTTP 服务 | [HTTP + Outbox + Worker + Inbox](examples/http-service/README.md) |
+| 查字段、错误码、权限及协议 | [HTTP / WebSocket API](docs/api/README.md)、[Go SDK 手册](docs/sdk/README.md) |
+| 配置、排障、备份、发布 | [配置与运维](#配置与运维)、[运行手册](docs/20-operations-runbook.md) |
 
-数据库禁止外键，关联一致性通过服务端事务校验，索引、唯一约束和 CHECK 保留；新装库使用无外键当前版本基线，已有库沿不可变迁移链升级；readiness 同时检查迁移及零外键要求。[运行观测](docs/api/observability.md)提供固定基数 HTTP、数据库池和后台批次指标；发布前可执行只读的 [`orbit-admin verify`](docs/api/operations.md) 核验迁移、零外键和固定索引。这不表示完整平台已具备生产服务能力。验证证据见 [P0](docs/reports/phase-0.md)、[P1](docs/reports/phase-1.md)、[P2 阶段验收](docs/reports/phase-2.md)、[安全重试](docs/reports/phase-3-safe-retry.md)、[计划调度](docs/reports/phase-3-schedules.md)、[取消与无外键回归](docs/reports/phase-3-cancellation.md) 及 [队列资源回归](docs/reports/phase-3-queue-resources.md)。
+## 功能一览
 
-## 目录
+每个示例目录都有 README、源码、启动方式和结果核对。接口手册包含字段、权限、错误码和恢复约定。
 
-```text
-cmd/orbit/                    基础 HTTP 服务入口
-cmd/orbit-migrate/            独立数据库迁移命令
-cmd/orbit-admin/              受控初始化与私密凭据交付
-model/                       公共 ID、JSON、摘要与记录原语
-platform/model/              应用、命名空间、幂等、事件和审计
-platform/auth/               凭据格式与动作/队列授权范围
-pulse/model/                 任务、尝试、队列、计划和执行许可
-pulse/service/               任务与队列应用契约、输入校验
-pulse/worker/                会话、开始、续租、结果和恢复契约
-pulse/retry/                 冻结策略、有限退避与未知效果决策
-pulse/schedule/              Cron/间隔、漏跑、版本及计划接口
-internal/timezone/           随计划冻结的内置时区数据快照
-weave/model/                 定义、实例、步骤、信号和查询轮次
-weave/definition/            有限结构/类型校验与定义发布契约
-weave/engine/                不可变规则的有限步骤决策与精确结果映射
-weave/instance/              实例受理、当前详情及操作审计契约
-weave/signal/                内部可靠信号受理/查询契约及显式激活身份
-weave/control/               内部版本化暂停/继续/取消契约
-internal/config/             配置校验
-internal/storage/mysql/      连接、事务、迁移及集成测试
-internal/transport/httpserver/ HTTP 接入
-sdk/go/                      独立 Go SDK module 与示例
-adapters/outbox/mysql/        可直接引用的业务事务 Outbox 独立模块
-examples/http-service/       HTTP + Outbox + Worker + Inbox 完整服务示例
-scripts/                     可复现的回归工具
-docs/                        设计、接口、SDK、场景与验证报告
-```
+### Pulse：任务与调度
 
-## 本地运行
+| 功能 | 做什么 / 怎么用 | 可运行示例 / 接口 |
+| --- | --- | --- |
+| 即时任务与提交幂等 | `SubmitTask` 提交固定处理器版本与 JSON；重报复用原操作键，`GetTask` 查当前状态 | [tasks](examples/tasks/README.md) · [任务接口](docs/api/tasks.md) |
+| 延迟任务 | `DelayMS` 从首次受理计时；`AvailableAt` 指定绝对时刻 | [delayed-task](examples/delayed-task/README.md) |
+| 批量受理 | `SubmitTasks` 最多 32 项，逐项返回受理/拒绝/未知，按原身份补交 | [batch](examples/batch/README.md) · [批量接口](docs/api/batch-tasks.md) |
+| 自动 Worker | 注册处理器与版本，`NewWorker(...).Run(ctx)` 负责连接、授权、续租、上报与排空 | [worker](examples/worker/README.md) · [运行器手册](docs/sdk/worker-runtime.md) |
+| 安全重试 | 冻结次数、退避与总时限；明确可重试失败自动再执行，未知效果按安全策略核查 | [retry](examples/retry/README.md) · [重试策略](docs/api/retries.md) |
+| 取消 | `CancelTask` 保存取消意图；运行中的处理器配合停止并结清 | [cancellation](examples/cancellation/README.md) |
+| 定时计划 | Cron / 固定间隔、时区、不可变版本、漏跑策略、暂停/恢复和触发历史 | [schedules](examples/schedules/README.md) · [计划接口](docs/api/schedules.md) |
+| 队列资源控制 | 创建/配置队列并发、开始速率、积压上限和暂停；满额返回背压 | [resources](examples/resources/README.md) · [队列接口](docs/api/queues.md) |
+| 应用共享配额 | 同一应用的多个命名空间/队列共享总额度 | [application-resources](examples/application-resources/README.md) |
+| 资源键互斥 | `ConcurrencyKey` 协调跨队列同资源任务，资源端核验递增许可序号 | [keyed-concurrency](examples/keyed-concurrency/README.md) |
+| 优先级 | 任务优先级 0–9，结合等待时间排序与节点轮转派发 | [priority](examples/priority/README.md) |
+| 查询与来源 | 按队列、状态、业务键、创建时间分页；追溯普通提交、计划、流程和人工重试来源 | [task-query](examples/task-query/README.md) · [来源接口](docs/api/task-source.md) |
+| 历史与证据 | 查询每次尝试、原结果及迟到/冲突报告，保留原始记录 | [history](examples/history/README.md) |
+| 人工核查与重试 | `ReviewTask` 提交证据；`RetryTask` 创建关联新任务并保留审计 | [recovery](examples/recovery/README.md) |
 
-要求 Go 1.27.1、MySQL 8.4+。先准备专用数据库和凭据，通过环境变量注入；程序不会自动读取 `.env` 文件。
+### Weave：流程编排
+
+| 功能 | 做什么 / 怎么用 | 可运行示例 / 接口 |
+| --- | --- | --- |
+| 定义与版本 | 研发使用 SDK 创建定义、发布不可变版本；运行实例固定启动版本 | [workflow-definition](examples/workflow-definition/README.md) · [定义格式](docs/api/workflow-definition-format.md) |
+| 顺序、条件、并行与汇合 | 用有限结构组合任务与结果映射；持久化每一步和推进检查点 | [workflow](examples/workflow/README.md) · [实例接口](docs/api/workflows.md) |
+| 时间与外部信号等待 | TIMER 到期继续；SIGNAL 按固定等待身份接收外部回执 | [workflow](examples/workflow/README.md) · [信号设计](docs/14-workflow-signals.md) |
+| 有界重复查询 | POLL 分别限制业务查询轮次和单轮请求重试，处理中继续等待，耗尽转核查 | [workflow-poll](examples/workflow-poll/README.md) |
+| 暂停、继续、取消 | 停止推进后续工作，同时收集已发出的在途结果 | [控制接口](docs/api/workflows.md) · [控制语义](docs/15-workflow-controls.md) |
+| 人工恢复 | 按原因、证据、版本核查任务/步骤/等待；恢复沿用原历史、预算和截止 | [workflow-recovery](examples/workflow-recovery/README.md) · [恢复接口](docs/api/workflow-recovery.md) |
+| 实例查询与审计 | 筛选分页，查步骤详情、历史激活、查询轮次、信号及状态时间线 | [workflow-query](examples/workflow-query/README.md) · [历史接口](docs/api/workflow-history.md) · [时间线](docs/api/workflow-events.md) |
+
+### 业务接入与管理
+
+| 功能 | 做什么 / 怎么用 | 入口 |
+| --- | --- | --- |
+| 可靠结果订阅 | 先创建订阅，再由 EventConsumer 通过 WebSocket 接收结果；业务提交后 ACK，失败按预算重新交付 | [subscriptions](examples/subscriptions/README.md) · [消费 SDK](docs/sdk/event-consumer.md) |
+| 事务 Outbox 公共包 | `EnqueueTx` 将待发请求写入业务事务，`Run` 后台发送；网络结果不明复用原身份 | [MySQL 适配包](docs/sdk/outbox-mysql.md) · [task-outbox](examples/task-outbox/README.md) |
+| 业务结果 Inbox | 事件去重与业务更新同事务，提交成功后确认交付 | [result-inbox](examples/result-inbox/README.md) |
+| HTTP 服务完整生命周期 | 业务接口、Outbox、Worker、结果消费、就绪检查和有界关闭放进同一业务服务 | [http-service](examples/http-service/README.md) |
+| 平台身份与凭据 | 应用/命名空间/队列授权范围、凭据轮换/撤销；SDK 不直连平台数据库 | [鉴权](docs/api/authentication.md) · [凭据管理](docs/api/authentication.md) |
+| 账号密码控制台 | 初始化管理员，登录查看统计、任务/计划/流程/交付详情和管理操作，未登录跳转登录页 | [Console 手册](docs/console.md) |
+| 保留策略与周期归档 | 配置各类数据保留天数，持久化归档计划/作业，分页、续跑、重试与文件核验 | [保留策略](docs/api/retention.md) · [周期归档](docs/api/archive-scheduler.md) |
+| 运维与观测 | 健康/readiness、独立指标端口、迁移核验、负载工具、备份恢复与故障演练 | [观测](docs/api/observability.md) · [运维](docs/20-operations-runbook.md) |
+
+## 快速开始
+
+需要 **Go 1.27.1、MySQL 8.4**，先创建专用数据库 `orbit`；下方管理员密码提示和读取队列 ID 的辅助命令使用 Python 3。程序通过环境变量配置，**不会自动读取 `.env`**。如当前 shell 设置了 `GOTOOLCHAIN=local`，必须安装满足版本要求的 Go。
+
+### 1. 获取代码并迁移数据库
 
 ```sh
+git clone --branch v0.1.1 https://git.yuntuo.hk/k2safe/orbit.git
+cd orbit
 export ORBIT_MYSQL_DSN='user:password@tcp(127.0.0.1:3306)/orbit'
 export ORBIT_HTTP_ADDR='127.0.0.1:8080'
 go run ./cmd/orbit-migrate up
+```
+
+DSN 替换为实际账号密码。`--branch v0.1.1` 检出固定发布版本；参与开发使用 `git switch main`。已有库先备份，再按[升级与发布手册](docs/20-operations-runbook.md)停旧写节点、迁移和核验；不修改已应用的迁移文件。
+
+### 2. 一次性创建示例资源与管理员
+
+下面在独立演示应用中授予所有流程及任务演示所需权限，并设置一个管理员。密码至少 12 字节，通过标准输入传递，不写入命令行或 Git。
+
+```sh
+umask 077
+mkdir -p .local
+python3 -c 'import getpass; print(getpass.getpass("设置管理员密码（至少12字节）："))' | \
+  go run ./cmd/orbit-admin bootstrap \
+    --application sample-app --namespace default --environment development \
+    --queue examples --worker-access --schedule-access --event-access \
+    --recovery-access --workflow-access --workflow-run-access \
+    --workflow-control-access --workflow-signal-access \
+    --workflow-recovery-access --workflow-audit-access \
+    --console-username admin --console-display-name 'Orbit 管理员' \
+    --console-password-stdin --output .local/development.credentials.json
+```
+
+初始化只运行一次，后续重启复用数据库、账号和 SDK 凭据。凭据 JSON 是服务端程序访问 API 的秘密文件，**控制台不需要选择或上传它**。已有资源增加管理员的方法见 [Console 手册](docs/console.md)；真实接入按实际角色缩小权限。
+
+### 3. 启动平台，进入控制台
+
+```sh
+export ORBIT_CONSOLE_QUEUE_ID="$(python3 -c 'import json; print(json.load(open(".local/development.credentials.json"))["queue_id"])')"
 go run ./cmd/orbit
 ```
 
-上方 DSN 为本地占位示例，需替换为实际凭据。部署时使用秘密管理和经过验证的 TLS 配置；迁移账户与运行账户分开授权。运行程序不自动迁移数据库。
+打开 **<http://127.0.0.1:8080/console/>**，用 `admin` 和刚设置的密码登录。页面自动使用当前访问地址请求服务端，统计与列表从平台接口读取 MySQL 中的数据。
 
-另一个终端执行 SDK 示例：
+### 4. 跑一条完整执行链
+
+另开终端，从仓库根目录执行：
 
 ```sh
-cd sdk/go
-ORBIT_URL=http://127.0.0.1:8080 go run ./examples/health
+export ORBIT_URL=http://127.0.0.1:8080
+export ORBIT_CREDENTIALS_FILE="$PWD/.local/development.credentials.json"
+cd examples
+go run ./health
+go run ./worker
 ```
 
-任务接入从 [初始化凭据](docs/api/authentication.md) 开始，再按 [SDK 接入](docs/sdk/README.md) 运行受理/取消示例。[自动 Worker 示例](docs/sdk/worker-runtime.md) 演示处理器注册、并发消费、结果确认与排空；特殊接入也可使用 [底层协议示例](docs/sdk/worker.md)。
+健康检查显示 `liveness=alive readiness=ready`；Worker 示例实际创建并执行三条文本任务，最后输出：
 
-## 开发与回归
+```text
+task=<任务ID> state=SUCCEEDED result={"text":"HELLO ORBIT"}
+task=<任务ID> state=SUCCEEDED result={"text":"REUSABLE WORKER"}
+task=<任务ID> state=SUCCEEDED result={"text":"DURABLE RESULT"}
+worker_drained=true started=3 confirmed=3 running=0
+```
+
+刷新控制台可查看这些任务。继续在 `examples` 目录运行 `go run ./schedules`、`go run ./workflow` 或 `go run ./workflow-poll` 体验定时和流程；全部 27 个场景及特殊准备条件见 [examples/README.md](examples/README.md)。
+
+## SDK 怎么调用
+
+### 安装固定版本
+
+在自己的业务项目中执行：
 
 ```sh
-make fmt
-make test
-make vet
-make build
-make image
-make integration
-make console-e2e
-make protocol-check
-make docs-check
+go get git.yuntuo.hk/k2safe/orbit/sdk/go@v0.1.1
+# 业务事务需要 MySQL Outbox 时再安装：
+go get git.yuntuo.hk/k2safe/orbit/adapters/outbox/mysql@v0.1.1
 ```
 
-首版发布前按[交付核对清单](docs/release-checklist.md)逐项留存命令输出和目标环境证据；当前阶段回归不替代生产拓扑、容量、复制切换或 RPO/RTO 验收。
+无需本地源码或 `replace`。SDK 是独立 Go module，只依赖标准库和 WebSocket 客户端；MySQL 驱动属于可选适配包。子模块的 Git 标签分别为 `sdk/go/v0.1.1` 和 `adapters/outbox/mysql/v0.1.1`。
 
-`make integration` 要求 Docker、OpenSSL 等标准命令，启动独立的临时 MySQL 容器，使用随机凭据和回环随机端口；完成后删除该测试容器。不会连接已有业务数据库。可通过 `GO`、`DOCKER` 和 `ORBIT_TEST_MYSQL_IMAGE` 指定工具/测试镜像。
+### 提交、执行、接收结果
 
-受理层负载采样工具见 [有界受理负载工具](docs/api/load.md)，只允许在隔离命名空间或一次性数据库中运行；它不自动重试、不启动 Worker，也不提供生产容量承诺。
+一次完整接入分为三个角色，可以分进程，也可以嵌入同一业务 HTTP 服务：
 
-历史数据可通过控制台配置保留窗口，也可使用 [`orbit-admin retention archive`](docs/api/retention-jobs.md) 自动分批落盘、断点续跑和离线核验。当前保留源数据，周期归档调度和删除执行器另行交付。
+```text
+业务事务 → Outbox → HTTP 提交到 Orbit → WebSocket Worker 执行业务
+                                      ↓
+业务数据 ← Inbox ← WebSocket 结果订阅 ← 持久化结果
+```
 
-真实Worker与任务完成路径测量使用[`orbit-exec-load`](docs/api/execution-load.md)：短/混合/中长模拟任务、持久结果和单次尝试核验、阶段延迟分布；不修改队列额度、不调用外部业务系统。定时积压复现可运行 `make schedule-backlog`，它只使用一次性 MySQL，并保留有界截止负例的实际分母。Weave 并行流程链路使用[`orbit-workflow-load`](docs/api/workflow-load.md)，核对固定版本、步骤、来源和最终输出。定时集中触发使用[`orbit-schedule-load`](docs/api/schedule-load.md)，逐项核对触发、任务、唯一尝试与来源，并保留超时分母和暂停收尾证据。
+下面是业务函数中的提交片段；完整 imports、main、Worker 注册和收尾见 [worker/main.go](examples/worker/main.go)。`baseURL` 为实际平台地址，例如 `https://orbit.example.com`；`token` 和 `queueID` 从业务配置/Secret 注入。
 
-SDK 独立发布门禁使用 `make sdk-check`，在 `GOWORK=off` 下检查完整依赖图，并运行 SDK 的竞态测试、vet 和全包构建；规则和接入边界见 [SDK 发布门禁](docs/sdk/release.md)。
+```go
+client, err := orbit.NewClient(baseURL, orbit.Options{Token: token})
+if err != nil { return err }
 
-修改已应用迁移时会触发校验和拒绝；新增结构使用新的前向迁移。初始结构尚未部署生产。
+// operationKey 和完整 request 必须先保存在业务库；网络重报仍使用原值。
+request := orbit.SubmitTaskRequest{
+    QueueID: queueID,
+    Handler: "object.prepare", HandlerVersion: "v1", PayloadVersion: "v1",
+    Payload: json.RawMessage(`{"object_ref":"objects/input"}`),
+    TaskTimeoutMS: 60000,
+    Retry: orbit.RetryPolicy{MaxAttempts: 1, AttemptTimeoutMS: 10000},
+    RecoverySafety: orbit.RecoveryReconcileOnly,
+}
+accepted, err := client.SubmitTask(ctx, operationKey, request)
+if err != nil { return err }
+current, err := client.GetTask(ctx, accepted.Task.ID)
+if err != nil { return err }
+fmt.Println(current.ID, current.State)
+```
 
-## 文档入口
+导入路径为 `orbit "git.yuntuo.hk/k2safe/orbit/sdk/go"`。处理器的名称、处理器版本和载荷版本必须与 Worker 注册能力一致；没有匹配的在线 Worker 时，提交成功也不会立即执行。
 
-- [持续开发与回归计划](docs/08-development-plan.md)
-- [数据模型与约束](docs/07-data-model.md)
-- [HTTP / WebSocket 接口手册](docs/api/README.md)
-- [Go SDK 接入](docs/sdk/README.md)
-- [通用场景示例](docs/examples/README.md)
-- [Orbit Console 控制台](docs/console.md)
-- [运行与发布手册](docs/20-operations-runbook.md)
-- [容器发布说明](docs/21-container-deployment.md)
-- [设计文档总览](docs/README.md)
+**任务受理不等于执行成功。** 同键重报返回原回执，最新状态用 `GetTask` 或结果事件核对。平台不能替外部系统保证“恰好执行一次”；副作用须使用业务幂等键、事务或证据核查。
 
-Git 远端：[k2safe/orbit](https://git.yuntuo.hk/k2safe/orbit)，主分支 `main`。首个接入版本为 `v0.1.0`，业务项目使用 Go 1.27.1 或更高版本安装：
+结果通知使用 `NewEventConsumer(...).Run(ctx)`。先创建持久订阅，再提交希望接收的任务；消费函数在 Inbox 与业务变更明确提交后返回 nil，SDK 才 ACK。断线重连、重复交付和业务去重见[消费手册](docs/sdk/event-consumer.md)。
+
+### 现有 HTTP 服务如何接入
+
+直接从 [examples/http-service](examples/http-service/README.md) 开始，完整命令、配置及 curl 请求见[运行手册](docs/examples/http-service.md)。该工程提供：
+
+1. `init`：在独立业务库创建 Outbox、业务表、Inbox 和结果视图。
+2. `provision`：创建可靠结果订阅，将订阅 ID 保存到部署配置。
+3. `serve`：启动业务 HTTP、Outbox 发送器、Worker 和结果消费者。
+4. 业务请求返回本地受理状态；随后查询到平台 TaskID、执行结果和业务视图。
+5. 收到退出信号后，依次收尾 HTTP、发送器/Worker、结果消费者，最后关闭数据库。
+
+只抽取发送器时使用[公共 Outbox 包](adapters/outbox/mysql/README.md)：`EnqueueTx` 加入调用方事务，不提交事务、不发网络请求；`Run` 在后台提交并核对平台回执。业务确认钩子与 Outbox 确认同事务执行。
+
+## Docker 与域名部署
+
+仓库提供 [Dockerfile](Dockerfile)、[Compose 启动链](deploy/docker-compose.yml)和 [Nginx 配置](deploy/nginx/orbit.conf.example)。按[完整 Compose 手册](docs/22-compose-deployment.md)注入数据库密码、构建镜像、启动 MySQL/迁移/核验、初始化管理员，最后启动 Orbit。手册也包括停止、更新与两节点覆盖配置。
+
+- Console 同源访问：域名反向代理到 Orbit 后，页面自动使用这个域名，无需在界面填写服务地址。
+- 业务 SDK：把自己的 `baseURL` / 示例 `ORBIT_URL` 配置为该 HTTPS 域名，SDK 使用相应 WSS 地址。
+- 网关保留 WebSocket Upgrade/Connection 头，健康检查使用 `/health/ready`。
+- 停止容器保留 MySQL 和归档持久卷；更换镜像不等于删除数据。
+
+## 配置与运维
+
+配置完整示例见 [.env.example](.env.example)。由 shell、部署平台或 Secret 管理器显式注入：
+
+| 配置 | 用途 |
+| --- | --- |
+| `ORBIT_MYSQL_DSN` | 平台数据库连接，迁移账号与运行账号按部署手册分开 |
+| `ORBIT_HTTP_ADDR` | 服务进程监听地址，例 `127.0.0.1:8080` |
+| `ORBIT_CONSOLE_QUEUE_ID` | 控制台默认队列；不授予账号额外权限 |
+| `ORBIT_DB_MAX_OPEN` / `ORBIT_DB_MAX_IDLE` | 数据库连接池上限 |
+| `ORBIT_SHUTDOWN_TIMEOUT` | SIGTERM 关闭窗口，默认 10s |
+| `ORBIT_WORKFLOW_TICK_INTERVAL` / `ORBIT_SCHEDULE_TICK_INTERVAL` | 流程/计划后台扫描间隔，默认 1s |
+| `ORBIT_RECOVERY_TICK_INTERVAL` / `ORBIT_RUNTIME_BATCH_LIMIT` | 恢复扫描间隔与每批上限，默认 2s / 100 |
+| `ORBIT_WORKER_CONNECTION_LIMIT` / `ORBIT_EVENT_CONNECTION_LIMIT` | 每节点 WS 连接上限，默认各 128 |
+| `ORBIT_DISPATCH_WORKERS` / `ORBIT_DISPATCH_CAPACITY` | 派发并发和有界内存队列，默认 4 / 128 |
+| `ORBIT_METRICS_ADDR` | 独立内部指标监听，默认关闭 |
+| `ORBIT_RETENTION_*_DAYS` | 首次初始化保留窗口；控制台保存后以数据库策略为准 |
+| `ORBIT_ARCHIVE_ROOT` / `ORBIT_ARCHIVE_STORAGE_ID` | 周期归档卷路径与固定卷身份，二者一起配置 |
+| `ORBIT_ARCHIVE_MAX_BYTES` / `ORBIT_ARCHIVE_TICK_INTERVAL` | 归档卷预算和调度间隔，默认 10 GiB / 10s |
+
+默认保留窗口：任务、流程、事件各 **365 天**，交付、Inbox、幂等记录各 **90 天**，审计 **2555 天**。控制台可修改策略并配置周期归档；未结清任务、未知效果、未确认交付等受保护记录不会按时间简单处理。**当前归档导出并保留源数据，尚未提供源数据自动删除执行器。** 详细规则见[保留策略](docs/api/retention.md)和[归档作业](docs/api/archive-scheduler.md)。
+
+常用检查：
 
 ```sh
-go get git.yuntuo.hk/k2safe/orbit/sdk/go@v0.1.0
+curl --fail http://127.0.0.1:8080/health/ready
+go run ./cmd/orbit-admin verify
+go run ./cmd/orbit-admin observe snapshot
 ```
 
-无需本地 `replace`；导入方式、完整调用与版本边界见 [SDK 接入](docs/sdk/README.md#5-外部项目通过远端接入)。
+数据库禁止外键和级联删除；关联一致性由事务校验，保留唯一约束、索引和 CHECK。持久化模型及 SQL 字段都有中文注释。已有迁移不可回改，演进采用前向迁移。
 
-[流程实例筛选分页](docs/api/workflow-queries.md)已提供独立SDK和[完整示例](docs/examples/workflow-query.md)，按固定版本全部队列鉴权，数据库保持零外键。
+## 项目目录
 
-- [周期归档与作业管理](docs/api/archive-scheduler.md)
+```text
+cmd/                         平台、数据库迁移和管理命令
+platform/                    应用、身份、授权、幂等、事件、审计
+pulse/                       任务、Worker、重试、队列、定时计划
+weave/                       流程定义、实例、步骤、等待和恢复
+model/                       公共持久化类型与校验
+internal/                    MySQL 存储、HTTP/WS、配置与观测
+sdk/go/                      可独立引用的 Go SDK
+adapters/outbox/mysql/        可独立引用的 MySQL Outbox 包
+examples/                    27 个可运行场景及各自 README
+deploy/                      Compose、Nginx 和部署配置
+scripts/                     构建、回归、故障和发布核验
+docs/                        API、SDK、场景、设计及验收报告
+```
 
-业务接入可直接使用[MySQL 事务 Outbox 适配包](docs/sdk/outbox-mysql.md)和[完整 HTTP 生命周期示例](docs/examples/http-service.md)，覆盖已有事务、后台发送、结果入库以及有界关闭。
+## 测试、版本与边界
+
+在仓库根目录执行：
+
+```sh
+make test vet build          # 7 个模块的竞态测试、静态检查与构建
+make sdk-check protocol-check docs-check
+make integration             # 临时 MySQL、真实平台、示例及故障回归
+make console-e2e             # 控制台端到端回归
+```
+
+集成测试需要 Docker、Python 3 和 OpenSSL 等工具，由脚本创建独立临时数据库并清理自建容器。生产容量与故障域验收另见[交付清单](docs/release-checklist.md)；有限样本不能代表百万企业规模的生产容量。
+
+`v0.1.1` 包含账号密码控制台、归档策略/周期作业、Outbox 公共包、HTTP 生命周期示例及统一示例目录；与上一版本的升级说明和验证结果见 [CHANGELOG](CHANGELOG.md) 与 [发布记录](docs/reports/v0.1.1-release.md)。当前未提供源数据删除、其他数据库 Outbox 适配，也不把单机或隔离环境多节点测试等同于生产跨故障域高可用验收。
+
+更多资料：[设计文档](docs/README.md) · [持续开发计划](docs/08-development-plan.md) · [接口目录](docs/api/README.md) · [示例目录](examples/README.md) · [发布规则](docs/sdk/release.md)。