feat: add typed error message templates and stable replay snapshots

RELEASE.md

@@ -1,38 +1,31 @@
-# v0.10.0-preview
+# v0.11.0-preview
 
-统一错误目录：由项目集中定义逻辑标识、对外业务码、公开提示和 HTTP 状态，业务只选择错误。支持 HTTP 200 的业务失败，并贯通响应、错误函数生成、日志与 OpenAPI。
+错误目录支持提示模板和有序类型参数。业务调用 `apierrors.TextTooLong("企业名称", 100)`，错误目录统一定义业务码、HTTP 状态与文案，运行时入口和生成函数共用解析逻辑。
 
-## 升级
+## 升级与接入
 
 ```sh
-go get git.yuntuo.hk/k2safe/go-omni@v0.10.0-preview
-go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.10.0-preview
-# 使用 .api 的项目再执行：
+go get git.yuntuo.hk/k2safe/go-omni@v0.11.0-preview
+go install git.yuntuo.hk/k2safe/go-omni/cmd/go-omni@v0.11.0-preview
 go-omni api generate --dry-run
 go-omni api generate
 go test ./...
 ```
 
-先升级项目依赖，再使用同版 CLI。新生成代码最低运行时为本版；旧的 APIError/New/BadRequest、Codes/Messages、error 声明及旧生成代码继续支持。API 错误包增加 `Catalog()`，该名称成为保留符号。项目的手写 main、Service 和 Repository 不被重生成覆盖。
+先升级依赖，再使用同版 CLI。新生成代码最低要求本版；已有固定错误、v0.10.0 目录、无参数函数和旧生成代码继续支持。模板错误一旦声明参数，修改其顺序/类型会改变生成函数签名，项目需同步修改调用方。手写文件仍受重生成保护。
 
-## 接入
+从 [README](README.md) 接入，完整规则见 [错误目录与模板参数](errors/README.md)，可直接生成的契约见 [errorParams.api](examples/contracts/errorParams.api)。
 
-- 手写项目：`omni.New(omni.WithErrors(catalog), omni.WithResponse(responseConfig))`，业务返回 `omnierrors.ByCode(key)`，按需 `.WithCause(err)`。
-- 契约项目：`.api errorCatalog` 定义一次，路由 `@errors` 或 `@server errors` 引用，生成 `apierrors.UsernameInvalid()` 等函数、Catalog、路由策略及 OpenAPI。
-- 项目目录的 `defaultStatus` 可以设为 200，单条错误可设置 403、409 等；默认只作用于目录条目，不改变未配置系统错误的兜底。
-- 逻辑标识必须唯一，对外业务码可以重复，支持字符串/int32/int64；整数精度与所选响应类型在加载/编译时校验。
-- HTTP 200 失败使用错误响应模板，OpenAPI 的 200 使用 anyOf 保留成功 DTO 和错误体；同码错误保留不同示例。
-- App 和路由目录隔离、初始化复制；每次生成/解析错误都返回独立对象。未知标识转系统兜底，默认公开响应不暴露 cause。
+## 能力与边界
 
-完整接入从 [README](README.md) 开始；目录/作用域/配置边界见 [错误目录](errors/README.md)；可直接生成的例子见 [errors.api](examples/contracts/errors.api)。
-
-## 配置边界
-
-生成路由的目录和响应以 `.api` 为准，优先于 App 默认配置；ByCode 需要当前目录中存在该标识。使用生成函数后仍须声明实际路由的 @errors，保持文档准确。不同路由可使用不同码类型与返回格式。
-
-目录与响应模板分开，自定义 Encoder 继续控制最终 HTTP 状态和文本/XML 等协议。直接输出与已提交响应不会被再次包装。旧同标识 Codes/Messages 若与新目录冲突会明确拒绝。
-
-访问日志记录实际提交状态，并带 failed/errorKey/可用的 businessCode。指标与链路识别 HTTP 200 业务失败；标准中间件和本地/共享幂等重放保留错误标识，旧缓存缺少标记时不补推历史状态。业务代码中的散落提示仍需业务项目按目录逐步迁移；本轮没有改写 eTax/ePay 业务逻辑。
+- 有序 `params` 决定函数参数顺序；支持 string/bool/int/int32/int64/float64。目录初始化检查模板、占位符、参数类型与文档 example。
+- `ByCode(key).WithParams(values)` 复制标量参数；生成函数立即解析完整 Message，非 HTTP 使用显式 Registry，不引入全局注册器。
+- HTTP 200 或逐项覆盖的状态、返回体模板、data:null、RawJSON 及自定义 Encoder 保持项目配置。内部 cause 不自动进入公开提示。
+- 运行时缺参、多参、类型/范围错误转系统兜底，日志包含 ParamError 诊断；不发送未替换的模板或原始参数值。
+- 路由、中间件和 Context 克隆保留参数。幂等重放保存已解析公开快照，目录更新不覆盖历史响应；不保存原始参数/cause，大整数码不经浮点转换。
+- OpenAPI 保留模板参数定义，响应 examples 显示具体提示。文档 example 不作为运行时缺参默认值。
+- 省略 params 的旧固定提示保留字面花括号；空 params 数组明确拒绝。模板错误同标识旧 messages 映射需移除。
+- 本轮没有修改 eTax/ePay 业务代码；业务侧需升级版本并声明自己的通用校验错误。
 
 ## 验证入口
 
@@ -40,13 +33,12 @@ go test ./...
 GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -race -p=1 -count=1 -timeout=300s ./...
 go vet ./...
 go build ./...
-python3 scripts/verifyErrorCatalogRelease.py --version v0.10.0-preview
-python3 scripts/verifyCompatibilityRelease.py --version v0.10.0-preview \
-  --report performance/errorCatalogCompatibilityRemote.json
+# 使用已有 redis:7-alpine 镜像启动本机有资源限制的临时容器：
+python3 scripts/verifyErrorParamsRedis.py
+# 发布后的远程固定版本消费者：
+python3 scripts/verifyErrorParamsRelease.py --version v0.11.0-preview
+python3 scripts/verifyErrorCatalogRelease.py --version v0.11.0-preview --report performance/errorParamsCatalogRemote.json
+python3 scripts/verifyCompatibilityRelease.py --version v0.11.0-preview --report performance/errorParamsCompatibilityRemote.json
 ```
 
-测试覆盖多 App 隔离、并发原因隔离、精确 int64、重复/非法定义拒绝、200 失败与 403 覆盖、未知错误兜底、已提交响应不追加、文本回执、访问日志、指标/链路、标准桥接、本地与序列化共享幂等存储，以及真实生成项目的 early middleware、raw 输出和重生成保护。远程脚本从全新缓存安装 CLI，检查固定版本、模块校验和与没有本地 replace。
-
-本版结果见 [统一错误目录验收](performance/errorCatalogAcceptance.md)。
-
-历史 Connector/HTTP 配置验收保留在 [v0.9.1 记录](performance/connectorAcceptance.md)，历史版本变化见 [CHANGELOG](CHANGELOG.md)。
+验收结果见 [提示模板验收](performance/errorParamsAcceptance.md)。历史 [v0.10.0 错误目录验收](performance/errorCatalogAcceptance.md) 保留。