契约、错误与国际化

规则：CORE-CONTRACT-001。适用于 Web 入参/返回、业务共享契约和错误处理。

必须遵守

• 共享 AO/Query/VO/DTO 放业务 *-core 的 contract/*；新代码不生成 pojo/*。
• 对象转换使用 converter/XxxConverter。普通 Converter 直接复用父接口方法，有定制映射才覆盖。
• @Schema(requiredMode = REQUIRED) 不是运行时校验；AO 同步声明适当 Jakarta Validation 注解。
• Web 返回复用 ResultBuild、ResponseResults 与统一异常处理，不另造外壳；不能把裸 Flux 塞入普通 JSON data。
• 响应式普通集合接口收敛为 Mono<ResponseResults<Iterable<T>>>；动作按真实语义使用 Mono<Void>，Web 层用 .then(ResultBuild.success()) 构建结果。
• 框架通用错误复用根级 ErrorCode；业务专有错误先到全局登记表确认范围，再维护模块常量和所有语言资源。

完整接口组合和返回类型见 CRUD/Query 指南。错误机制、约束 key 和 i18n API 的权威正文见 Constant/ErrorCode/I18n，可复制样板见模块样板。

错误码来源

应用错误码登记表是应用私有错误码唯一分配源。不要根据旧模块名、数字长度或旧 Core 表自行推导可用号段。已发布错误码的变更还需考虑调用方和 i18n 兼容。

UK/FK 约束使用通用错误与对应约束 i18n key，避免每个数据库约束再造一套私有码。约束 key 定义在模块 Constant 中。

验证

新增字段至少验证非法输入、创建/编辑后的读取、转换与敏感信息隐藏。新增错误至少验证错误语义、资源 key/语言文件与实际响应。数据库错误和业务校验错误可能来自不同入口，不能只测其中一条。

反例：只补 OpenAPI 必填注解；把 Entity 直接作为公共契约；捕获异常后返回成功；复制另一个模块的错误码数字。