orbit/docs/examples/file-conversion.md

文件格式转换示例

本例使用独立 Go SDK 提交一份小型 CSV 文件快照，由真实 Worker 转换成 JSON 文件正文，再查询平台权威结果。它只演示通用的任务受理、处理器版本、执行授权和结果确认，不包含行业规则或接入方项目名称。

前置

需要当前迁移、已启动 Orbit 服务，以及具备任务提交/读取和 Worker 消费权限的专用凭据。凭据文件应只保存在本地受保护目录：

cd sdk/go
ORBIT_URL=http://127.0.0.1:8080 \
  ORBIT_CREDENTIALS_FILE=../../.local/worker.credentials.json \
  go run ./examples/file-conversion

调用链与预期

示例生成独立的运行身份和处理器能力，提交以下输入：

{
  "file_name": "records.csv",
  "content": "name,amount\nalpha,2\nbeta,3\n",
  "target_format": "json"
}

Worker 使用固定的 file.convert.csv-json 处理器版本完成转换。预期输出类似：

input=records.csv output=records.json rows=2 state=SUCCEEDED worker_drained=true

任务结果中的 content 是：

[{"amount":"2","name":"alpha"},{"amount":"3","name":"beta"}]

提交键由本次运行身份和场景组成；网络结果不明时必须复用相同提交键查询，不能生成随机新键。示例只执行一次处理器，Worker 结束前等待排空，任务和审计历史保留。

生产接入边界

示例将小文件正文放在任务 JSON 中，方便隔离运行和回归。生产大文件应由业务侧先保存到受控对象存储，再把不可变对象引用、格式和业务操作键放入任务；处理器需要使用上下文取消、对象版本和业务幂等键，不能把 AttemptID 当作跨尝试的业务幂等键。

如果处理器在外部写入后失去连接，普通错误只能报告未知效果，接入方应使用查询或证据核对；不能因为 HTTP 或 Worker 回执超时就再次生成文件。平台保存的是任务结果快照，不替代业务对象存储、病毒扫描、权限策略或归档策略。

回归

单元转换校验：

cd sdk/go
GOWORK=off go test ./examples/file-conversion

make integration 会在一次性 MySQL 和真实 Orbit HTTP 服务上运行该示例，确认提交、Worker 执行、结果查询和排空均通过。该场景不证明外部对象存储的持久性，也不替代生产容量、故障切换或 RPO/RTO 验收。