go-omni/reports/contractFollowupAcceptance.md

v0.16.0-preview 契约与生成体验验收

日期：2026-09-25。范围是通用数组响应、OpenAPI 引用、共享 Go 错误目录与环境覆盖；没有引入业务专属错误或外部服务依赖。

验证结果

• 字符串、布尔、各支持整数/浮点类型与 any 数组可以校验并生成 Go 类型；实际生成消费者验证中文字符串、int64 精度、混合对象/数组/null/标量、nil 根数组归一和 raw 数组。未知类型、byte/File/根嵌套数组明确拒绝。
• 重复响应先共享，再依据体积收益共享 schema/示例，避免组件表本身膨胀。引用全部可解析，编译与压缩可重复；示例业务数据中的字面 $ref 不被解释。HTTP 200 同时含成功/业务错误时，两种 schema、所有模板示例和 data:null 保留。
• 两个独立生成服务共享一次 Go Catalog 导出；服务/路由文档筛选不生成运行期目录。支持 internal 包，临时 Go overlay、模块文件及导出程序在工作结束后删除。check 完整文件快照不变；过期目录、编译错误、非法路径和 symlink 输出拒绝。
• 重新生成保留 Logic；生成 --check、独立消费者 race 与编译通过。根 go run/go build、信号退出、nethttp/native、下载/原始回调/multipart 和生命周期清理继续通过。
• 环境覆盖验证同一个 Lookup、allow/ignore/reject、完整名优先、显式空与未设置区别、false/0、JSON 集合、默认值不被修改、错误不带输入值。框架旧短名称入口兼容；存储/MySQL 生成组合验证了新版模板。

实际契约文档

服务	原字节数	新字节数	操作数	展开后内容
eTax API	20,751,149	847,171	67	完全一致
eTax ID	1,008,210	392,481	3	完全一致

文档报告 保存原/新 SHA256 与生成源码摘要。通过只读 api export 写入临时目录，逐项比较完整 paths 操作；业务项目未做迁移或修改。

全量回归报告 与 进程验收 保存本次检查结果。

复验

GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race ./... -count=1 -timeout=300s
go vet ./...
go build ./...
python3 scripts/verifyManagedProject.py --report reports/contractFollowupLocal.json
python3 scripts/verifyManagedRelease.py --version v0.16.0-preview --report reports/contractFollowupRemote.json

共享 Catalog 提供方是清单显式指定的可信代码。框架隔离自己的文件操作，但不能保证用户提供方自身没有副作用；提供方应保持纯粹。该版本仍为 preview，未承诺支持完整 Go/goctl 类型语法或替业务完成数据库、权限、事务迁移。