feat: declare API errors and authentication with developer tooling

RELEASE.md

@@ -1,12 +1,12 @@
-# v0.7.0-preview
+# v0.7.0-preview.1
 
-这一版把 API 定义、项目生成、基础模块初始化和完整业务示例接通。
+这一版完善接口开发体验：业务错误和鉴权可在 .api 中声明，代码调用与 OpenAPI 同步；增加路由总览、文档导出和无写入的生成预览。
 预览版用于固定版本试用；API 方言有明确范围，HTTP/2 仍是独立实验适配器。
 
 ## 安装与开始
 
 ```sh
-GOPRIVATE=git.yuntuo.hk go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.7.0-preview
+GOPRIVATE=git.yuntuo.hk go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.7.0-preview.1
 
 go-omni api new --module example.com/demo ./demo
 cd demo
@@ -29,6 +29,13 @@ MySQL 与存储需要按生成 README 设置环境变量。任意契约生成的
 
 ## 主要变化
 
+- `error (...)` + `@errors` 声明业务错误，生成 `apierrors.EmailTaken()` 等全新实例构造函数和错误码常量。
+- `auth Name (...)` + `@auth` 同步 OpenAPI security 与实际路由中间件，声明本身不替代凭证验证。
+- 多行 `@doc` 支持 description/tags/deprecated；一个状态可有多个业务错误示例。
+- 项目内直接 `api inspect`、`api export`、`api generate --dry-run`，无需重复指定入口文件。
+
+此前 v0.7.0-preview 已提供：
+
 - `.api` 生成项目、绑定/校验、路由、业务骨架和 OpenAPI；支持分组、导入、命名中间件。
 - 同一入口初始化 MySQL、日志、Local / S3 / R2 / OSS；标准 context 与 httpx 保持业务/网络分离。
 - 生成器保护手写业务文件，校验自有文件哈希，支持只读 --check；基础设施选项持久化到 manifest。
@@ -43,7 +50,8 @@ MySQL 与存储需要按生成 README 设置环境变量。任意契约生成的
 2. Gen.go 由生成器维护，业务实现/配置/迁移由项目维护。新增 API 后执行 generate 和 go test；修改或删除类型需要同步处理自己的业务代码。
 3. `.goOmni/apiManifest.json` 需随代码提交。切换数据库或存储选项时，在新目录生成对照后迁移；重新生成不会改写现有基础设施文件。
 4. 配置使用 lowerCamelCase。DSN、Token、存储密钥由环境变量提供；`database.Config` 的 DSN 不会被 JSON/YAML 序列化。
-5. API 的 none/memory 数据库选项仅表示不打开连接，不会从 HTTP DTO 自动推导内存仓库或数据表。
+5. 旧 `.api` 仍可解析。新语法需要本版 CLI；生成的错误函数沿用已有框架错误类型。旧 CLI 无法解析新增声明，请一起升级。鉴权引用的已有 hook 和业务函数仍保留，不会自动重写。
+6. API 的 none/memory 数据库选项仅表示不打开连接，不会从 HTTP DTO 自动推导内存仓库或数据表。
 
 ## 验证入口
 
@@ -52,12 +60,12 @@ GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -p=2 -count=1 -timeout=300s ./...
 go vet ./...
 go build ./...
 python3 scripts/verifyAPIWorkflow.py
-python3 scripts/verifyAPIWorkflow.py --version v0.7.0-preview \
-  --report performance/apiWorkflowRemote.json
+python3 scripts/verifyAPIWorkflow.py --version v0.7.0-preview.1 \
+  --report performance/apiDeveloperExperienceRemote.json
 ```
 
 最后一项在全新 module cache 安装远程 CLI，并验证无本地 replace 的项目生成、
 真实 MySQL、nethttp/native 启动与业务流程。容器只使用本机临时资源，结束时清理。
-本轮验收见 [API 业务闭环报告](performance/apiWorkflowAcceptance.md)。
+本轮验收见 [接口开发体验报告](performance/apiDeveloperExperienceAcceptance.md)；此前业务闭环见 [API 业务验收](performance/apiWorkflowAcceptance.md)。
 
 OSS/R2 云端仍需项目自己的账号做上线环境验收；当前云端适配器检查不等同于这些账号的实网测试。