# 研发定义与发布流程

本例运行真实HTTP发布与读取，验证六种节点的格式以及不可变版本。当前不创建流程实例、不执行外部业务。实际运行另见[并行作业与回执示例](workflow.md)。

源码：[workflow-definition/main.go](../../examples/workflow-definition/main.go)。接口：[定义发布](../api/workflow-definitions.md)；字段规范：[结构版本1](../api/workflow-definition-format.md)。

## 1. 准备与运行

使用专用开发环境，MySQL已完成当前迁移、服务已启动，配置方式见[SDK接入](../sdk/README.md)。从仓库根目录初始化专用发布凭据（ORBIT_MYSQL_DSN已在当前环境安全设置）：

```sh
bin/orbit-admin bootstrap --application definition-demo --namespace default --environment test --queue workflow --workflow-access --output /tmp/orbit-definition.credentials.json
```

首次创建文件后保留，不要覆盖或打印凭据内容。该标志只增加定义读取和发布动作；生产凭据应限制到需要的命名空间及队列。

```sh
cd examples
ORBIT_URL=http://127.0.0.1:8080 \
ORBIT_CREDENTIALS_FILE=/tmp/orbit-definition.credentials.json \
ORBIT_OPERATION_ID=object-definition-demo-001 \
go run ./workflow-definition
```

开发回环地址可用HTTP，生产使用HTTPS。可改用`ORBIT_TOKEN`及`ORBIT_QUEUE_ID`，不把Token写入URL或提交版本库。不传`ORBIT_OPERATION_ID`时随机生成并先输出；发生未知结果时保存此操作ID，保持相同队列及源码再次运行。已成功的相同操作ID也可以重复执行，旧版本与revision不会增加。

## 2. 定义内容与调用链

输入契约为`{object_ref: STRING, operation: STRING, approved: BOOLEAN}`。示例依次定义：

1. `prepare`：对象准备TASK，引用input.object_ref，输出STRING。
2. `route`：根据input.approved选择路径，带显式默认分支。
3. `outputs`：并行定义preview与manifest两个TASK，全部成功后输出命名结果。
4. `approval`：等待与input.operation关联的布尔审核信号。
5. `settle`：1000毫秒TIMER等待。
6. `result`：有界POLL查询，最多5轮、每轮最多2次尝试、总时限20秒；PENDING、DONE、FAILED、REVIEW四种状态完全分组，并声明可选最终回执。

实际调用：CreateWorkflowDefinition → PublishWorkflowVersion(v1) → 原键确认v1 → 新键同内容确认v1 → 发布v2 → GetWorkflowVersion(v1) → GetWorkflowDefinition。v2仅把整个流程时限从60秒改到90秒；测试确认v1内容和原发布身份保持不变。

可直接在自己的Go代码中构建强类型`orbit.WorkflowSpecification`；`orbit.WorkflowRef("input","object_ref")`生成引用。常量使用`json.RawMessage`保留精确JSON数字。条件、步骤与处理器都在研发代码中声明，不上传任意可执行代码。

## 3. 预期输出与异常

输出包含操作ID、定义ID、v1/v2版本记录ID以及以下静态校验结果：

```text
revision=3
steps=8 max_concurrency=2 max_task_attempts=13
Both definitions are stored. No workflow instance or business task has been started.
```

HTTP响应未知时使用原操作ID及相同源码核对，不临时更换版本或键。若有意更改v1内容则返回409，需研发评审并显式发布新业务版本。缺少定义权限为403；引用队列不存在或越权为404；类型/引用/预算错误为400。审计失败不会留下半个发布版本，持续503需核查存储及服务状态。

本例保留定义和发布审计，不直接删库清理；目前没有删除接口。每命名空间最多100个定义，每定义100个版本，重复运行优先复用操作ID。完整隔离回归由`scripts/test-mysql.sh`负责数据库销毁，不能对共享环境做硬删除。