feat: declare API errors and authentication with developer tooling

performance/apiDeveloperExperienceAcceptance.md

@@ -0,0 +1,44 @@
+# 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)。
+
+## 远程版本验证
+
+发布后执行以下命令，从全新 module cache 下载 CLI 和框架，验证固定版本且没有本地 replace 的业务项目：
+
+```sh
+python3 scripts/verifyAPIWorkflow.py --version v0.7.0-preview.1 \
+  --report performance/apiDeveloperExperienceRemote.json
+```
+
+远程结果在实际完成后记录；本地通过不代替远程下载验证。
+
+## 边界
+
+鉴权声明负责文档及路由中间件装配；凭证校验、登录和权限策略仍由业务 hook 实现。新 hook 默认返回 501，不会自动放行。
+错误声明不会自动映射数据库错误，也不会拦截运行时返回；Service 需要使用对应错误函数。
+本版每个接口只选择一个认证方案，不含 OAuth2 scopes、组合认证或 SDK 生成；现有 `.api` 继续支持，新声明需升级 CLI。
+
+验收只使用本机临时服务和 MySQL 容器，限制 1 CPU / 768 MiB、绑定 localhost，结束删除临时资源；未使用业务服务器。
+OSS/R2 云账号验收与网络层长时间压力测试不属于本轮。