orbit/docs/reports/phase-7-file-conversion.md

P7：通用文件转换示例

验证日期：2026-09-20。本批补齐首版接入清单中“提交任务 → Worker 实际转换 → 查询结果”的通用场景，使用独立 Go SDK 和真实 Orbit HTTP/WebSocket 链路，不包含特定行业或接入方规则。

实现内容

• 新增 sdk/go/examples/file-conversion：提交两行 CSV 快照，由版本化 file.convert.csv-json Worker 转成 JSON 结果。
• 处理器只读取任务输入和执行上下文，使用稳定提交键；同一个运行身份重复提交不创建第二个任务。
• 结果包含输出文件名、格式、转换正文和行数；输入标题重复、行列数不匹配或格式不支持时返回固定 INVALID_FILE，不把原始异常正文写入结果。
• 示例结束前等待 Worker 排空，任务与审计历史保留；单元测试覆盖正常 CSV、重复标题和列数错误。
• 小文件正文仅为可复现演示。生产大文件应由接入方保存不可变对象引用，处理器使用对象版本和业务幂等键；平台不承担对象存储、病毒扫描或外部副作用核查。

验证证据

SDK 单元与静态检查使用 Docker Go 1.25 临时模块文件通过：

go test -race ./examples/file-conversion    PASS
go test ./...                               PASS
go vet ./...                                PASS

真实链路使用 macOS arm64 主机、Docker MySQL 8.4、当前迁移 28、现有 Orbit HTTP 服务，以及 Docker Go 1.25 交叉编译的 darwin/arm64 示例二进制。一次性命名空间和 Worker 凭据运行结果为：

input=records.csv output=records.json rows=2 state=SUCCEEDED worker_drained=true
{"schema_version":28,"migration_count":28,"foreign_key_count":0,"required_index_count":6,"complete":true}

脚本语法、Markdown 本地链接（1242 个，错误 0）和 git diff --check 通过。标准 scripts/test-mysql.sh 已加入该示例；本次尝试用 Go 1.27.1 启动标准全量回归时，第一组集成测试进程被执行环境 SIGKILL 终止，未将其记为代码通过或失败，后续仍需在资源充足的环境完成完整回归。

验收边界

本批证明通用 SDK 示例能在真实平台链路完成一次小文件格式转换。它不证明对象存储持久性、恶意文件处理、外部业务副作用 exactly-once、生产容量、数据库切换、跨故障域可用性或 RPO/RTO；这些仍按 生产验收门槛 和 持续开发计划 单独验证。