feat: declare API errors and authentication with developer tooling

examples/userService/README.md

@@ -29,7 +29,7 @@ go run ./cmd/server
 ## 接口
 
 除健康检查、OpenAPI 和持有效签名的对象下载外，业务接口需要 `Authorization: Bearer <Token>`。
-这个 Token 代表示例的管理员；可通过同一个命名中间件槽位替换为 JWT/OIDC 和业务授权策略。
+这个 Token 代表示例的管理员；可选设置不同的 `USER_SERVICE_READ_TOKEN`，允许 GET/HEAD，写请求返回 403。可通过同一个命名中间件槽位替换为 JWT/OIDC 和业务授权策略。
 框架不会推断租户模型或自动给接口放行。
 
 | 接口 | 行为 |
@@ -43,8 +43,8 @@ go run ./cmd/server
 | GET /health/ready | 数据库不可用时返回 503，恢复后重新就绪 |
 | GET /openapi.json | 与 docs/openapi.json 一致 |
 
-参数不合法返回 400，认证失败 401，邮箱重复 409，内部故障只返回通用 500。
-OpenAPI 的业务数据类型来自契约；401/404/409 的业务错误码见上表。
+参数不合法返回 400，认证失败 401，只读身份写入 403，邮箱重复 409，内部故障只返回通用 500。
+OpenAPI 的数据类型、鉴权和业务错误均来自契约；401/403/404/409 带具体命名示例。业务使用生成的 `apierrors.UserNotFound()`、`apierrors.EmailTaken()` 等函数。
 
 创建、更新、删除都会在**同一个 MySQL 事务**写入 user_audit；审计写入失败时业务变更一起回滚。
 事务提交后才写成功业务日志，requestId 同时出现在 HTTP 响应、业务日志和审计记录。
@@ -57,8 +57,10 @@ OpenAPI 的业务数据类型来自契约；401/404/409 的业务错误码见上
 ## 开发与验证
 
 ```sh
-go-omni api generate --api api/user.api --dir .
-go-omni api generate --api api/user.api --dir . --check
+go-omni api inspect
+go-omni api generate --dry-run
+go-omni api generate
+go-omni api generate --check
 go test ./...
 ```
 
@@ -70,7 +72,7 @@ Gen.go 和 docs/openapi.json 由生成器维护；Service、Repository、迁移
 ```sh
 python3 scripts/verifyAPIWorkflow.py
 # 已发布版本：全新 module cache 安装 CLI，无本地 replace 消费框架。
-python3 scripts/verifyAPIWorkflow.py --version v0.7.0-preview \
+python3 scripts/verifyAPIWorkflow.py --version v0.7.0-preview.1 \
   --report performance/apiWorkflowRemote.json
 ```