# API 错误、鉴权声明与开发体验验收

目标版本：`v0.7.0-preview.1`。本轮修改 CLI 和示例，不改变网络适配器或业务 Service 的调用接口。

## 完成范围

- `.api` 集中声明业务错误，可通过 import 拆分；组级继承、路由追加/清空，生成错误码常量和每次返回新实例的 `apierrors` 函数。
- bearer、header API key、cookie API key 声明关联实际命名中间件；鉴权先于普通中间件执行，支持单接口覆盖和公共接口。
- OpenAPI 同步安全方案、401/403/409 等响应、同状态多个错误示例及业务错误码；支持接口描述、标签、弃用标记。
- 项目根目录自动发现契约入口；`api inspect` 查看路由，`api export` 输出文档，`api generate --dry-run` 预览文件变更。
- 用户示例使用同一份错误声明，并增加只读凭证，实际覆盖未认证 401、写入被拒绝 403、重复邮箱 409。

## 本地验证

- 完整框架 `GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -p=2 -count=1 -timeout=300s ./...`：39 个有测试的包通过。
- 包含 10 种 API 基础设施组合、10 种既有 CRUD 模块组合，以及新增的错误/鉴权消费者项目实际编译、运行与 race 检查。
- CLI 最后补充路径参数前缀回归（`:id` 和 `:idLong`），再次执行 `go test -race ./cmd/go-omni/...` 通过。
- `go vet ./...`、`go build ./...` 和格式/差异检查通过。
- 现有 API 真实 HTTP 回归在 nethttp/native 共 54 项通过。
- 用户示例在真实临时 MySQL 下，nethttp/native 共 34 项 HTTP、业务和生命周期检查通过；事务提交/回滚、初始化失败清理等测试同时通过。
- 检查鉴权优先顺序、未实现 hook 拒绝放行、缺失 hook 时不注册任何路由、公共接口覆盖、多鉴权方案和错误实例独立性。
- 检查只读预览不创建目录/锁文件、不改变文件；重复生成保留业务实现；无效声明报告源文件位置；恶意 manifest 路径被拒绝。

证据：[完整框架测试](apiDeveloperExperienceTests.txt)、[本地业务报告](apiDeveloperExperienceLocal.json)、[API 基础回归](apiGenerationLocal.json)。

## 远程版本验证

已发布 `v0.7.0-preview.1`，标签指向 `2913e94a0a4764ca70f0d19d198bd6c4852d8149`。
执行以下命令，从全新 module cache 下载 CLI 和框架，验证固定版本且没有本地 replace 的业务项目：

```sh
python3 scripts/verifyAPIWorkflow.py --version v0.7.0-preview.1 \
  --report performance/apiDeveloperExperienceRemote.json
```

远程验证通过：

- 远程安装的 CLI 在新目录生成 MySQL + local 项目，依赖固定为本版，无本地 replace，编译和测试通过。
- 用户示例从远程下载框架；module checksum 为 `h1:Eavj6gW9/v0y/knsQne5eNYIHxZZ9+e/r4Nu5PRUQfI=`。
- nethttp/native 共 34 项 HTTP、业务及生命周期检查通过，包括真实 401/403/409 与对应 OpenAPI 文档。
- 数据库迁移、事务提交/回滚、初始化失败清理测试通过；重新生成前后 29 份开发者拥有的文件逐字节保持一致。
- [远程业务报告](apiDeveloperExperienceRemote.json) 记录版本、检查列表与实际源码哈希；源码哈希已与本轮最终代码核对一致。

验收全部结束，临时服务、数据库容器及测试目录已清理。发布标签保持不变，后续验收记录维护在 main。

## 边界

鉴权声明负责文档及路由中间件装配；凭证校验、登录和权限策略仍由业务 hook 实现。新 hook 默认返回 501，不会自动放行。
错误声明不会自动映射数据库错误，也不会拦截运行时返回；Service 需要使用对应错误函数。
本版每个接口只选择一个认证方案，不含 OAuth2 scopes、组合认证或 SDK 生成；现有 `.api` 继续支持，新声明需升级 CLI。

验收只使用本机临时服务和 MySQL 容器，限制 1 CPU / 768 MiB、绑定 localhost，结束删除临时资源；未使用业务服务器。
OSS/R2 云账号验收与网络层长时间压力测试不属于本轮。