orbit/examples/README.md

Orbit 可运行示例

这里集中提供 27 个场景：24 个轻量 SDK 程序和 3 个包含业务数据库的完整工程。每个目录的 README 都有用途、前置条件、运行命令、预期结果及详细接口链接。

第一次使用

1. 按根 README迁移数据库、设置管理员并启动 Orbit。
2. 从 health 检查服务，再运行 worker 看完整提交与执行结果。
3. 接入已有业务优先阅读 http-service；只需要事务发送器，使用公共 Outbox 适配包。

轻量示例在根 examples/go.mod 中，仓库 go.work 联调本地 SDK；GOWORK=off 时使用已发布的最低兼容版本 v0.1.0。v0.1.1 的这些 SDK API 保持不变。三个业务工程各有独立 go.mod，用 GOWORK=off 运行；它们保留仓库内开发用的 replace。业务方自己的项目安装正式 v0.1.1，无需复制这些 replace。

从仓库根目录执行：

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

SDK 凭据是程序调用接口的身份，不是业务数据。任务、流程、结果与审计在 MySQL；控制台使用账号密码登录，无需上传凭据文件。

全部示例

目录	功能	本例实际演示
health	健康检查	查询存活、数据库/迁移就绪状态与运行版本。
tasks	任务提交与幂等	同一请求提交两次，查询任务和直接来源，再按版本取消。
worker	自动 Worker	注册文本处理器，执行三条任务，确认结果后有界排空。
file-conversion	CSV 转 JSON	提交小型 CSV 内容，Worker 转为 JSON，并核对行数和输出。
delayed-task	延迟任务	等待 1500 毫秒后执行，核对未提前开始及原受理回执。
batch	批量与部分补交	三项受理中两项成功、一项满额；原身份核对并只补交失败项。
retry	有限安全重试	第一次明确失败且未产生效果，退避后第二次成功。
cancellation	运行中取消	处理器收到取消意图后配合停止，确认没有未结清效果。
task-query	任务筛选与分页	按精确业务键和创建时间翻页，核对时间上界与原载荷，再取消收尾。
history	执行历史与迟到证据	保存成功结果后提交冲突报告，查询尝试及证据，确认原结果没有被覆盖。
recovery	人工核查与关联重试	模拟未知效果，凭证据核查为失败，再创建关联的新任务并成功执行。
schedules	定时计划	创建有限周期计划，恢复运行，读取固定版本触发来源，最后暂停并排空。
resources	队列配额与限速	制造队列积压背压，释放额度后以原身份补交，并验证受控执行。
application-resources	跨命名空间共享额度	同一应用下两个命名空间共享上限，释放后原身份重报，并恢复配置。
keyed-concurrency	跨队列资源互斥	两队列操作同一资源键，验证许可序号递增及资源端拒绝旧写。
priority	优先级	以单执行槽展示近同时到期的任务按 9、4、0 优先级执行。
subscriptions	结果订阅管理	创建订阅、同键核对、暂停、恢复及查询，最后暂停本次订阅。
event-protocol	WebSocket 结果通知与 ACK	接收取消事件并确认，断开后重报原证明，验证 ACK 去重。
worker-protocol	Worker 底层协议	手动完成注册、领取、开始授权、结果确认和查询，了解协议边界。
workflow-definition	流程定义与版本发布	研发通过 SDK 定义并发布 v1/v2，核对原版本与结构预算。
workflow	并行流程、汇合与信号	两条并行任务汇合，等待信号后推进，并查询来源和状态时间线。
workflow-query	流程实例筛选与分页	创建带业务键的实例，按业务键/状态/时间分页并核对尾部空格精确匹配。
workflow-poll	有界查询	提交外部作业一次，区分处理中轮次与请求失败重试，并演示轮次耗尽。
workflow-recovery	流程证据核查与恢复	外部受理后丢响应，按证据核查、解决步骤、解除核查并显式恢复暂停。
task-outbox	业务事务 Outbox	业务记录与待发请求同事务，后台提交及原身份恢复
result-inbox	业务结果 Inbox	同事务去重和更新业务视图，提交后 ACK
http-service	嵌入 HTTP 服务	HTTP → Outbox → Worker → 结果 Inbox，完整启动、就绪和关闭

权限与准备

根 README 的快速开始凭据用于专用演示环境，包含 Worker、计划、订阅、任务恢复和全部流程权限。若单独初始化，按各例要求选择：

能力	bootstrap 参数
Worker 执行	--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
应用共享额度	--resource-access，见 application-resources 的双命名空间初始化

已有凭据不会因修改命令自动增加权限。不要重复 bootstrap 覆盖原凭据；需要另一个场景时按对应手册创建独立示例应用并保存新文件。生产凭据按实际角色和队列收紧权限。

需要完整流程演示凭据时，在已配置 ORBIT_MYSQL_DSN 的仓库根目录执行一次：

umask 077
mkdir -p .local
go run ./cmd/orbit-admin bootstrap \
  --application workflow-examples --namespace default --environment development \
  --queue workflow --worker-access --workflow-access --workflow-run-access \
  --workflow-control-access --workflow-signal-access --workflow-recovery-access \
  --workflow-audit-access --output .local/workflow.credentials.json
export ORBIT_CREDENTIALS_FILE="$PWD/.local/workflow.credentials.json"
cd examples
go run ./workflow
go run ./workflow-poll
go run ./workflow-recovery

三个业务数据库工程的 init 仅用于新建专用空库；连接配置、命令参数与 API 请求分别在各自 README 链接的运行手册中。其数据库不能用 Orbit 平台库替代。

执行与恢复约定

• ACCEPTED 是任务已被平台受理；执行成功以查询或结果事件为准。
• 短示例通常随机创建身份用于独立演示；重启短示例不是恢复旧业务，持久恢复参考 Outbox/Inbox 工程。
• PENDING 查询结果表示继续等待，网络失败重试属于另一层预算。
• 示例使用真实接口并保留审计，不清空平台数据库。订阅、定义和队列会累计，应在专用环境演练。
• 外部系统有未知效果时应核查；处理器自己的幂等、事务和证据不能由重连机制替代。

回归

从仓库根目录执行 make test vet build 覆盖全部示例模块；make integration 使用临时 MySQL 和真实 Orbit 进程运行场景与故障测试。仅跑 go test ./... 而未提供集成环境时，外部服务用例会跳过。