业务对象与能力组合

区分 AO、Query、VO、DTO、Entity 与 Converter，明确字段的读写边界。

3.0.0-SNAPSHOT网站同步 2026-09-20

对象如何分工

新业务 contract 放在 contract/ao、contract/query、contract/vo、contract/dto；转换实现放 converter/。MyBatis-Flex 的 mapper/ 专用于持久化接口。

字段从 SQL → Entity → AO/VO/Query 不一定一对一暴露。例如审计字段由框架维护，秘密字段不能原样返回，关联名称可以是查询投影。为每个字段明确读写权限和转换来源。

先判断实体需要租户、树、逻辑删除、排序、数据状态或所有者能力，再选择对应数据栈基类。不要为得到一个字段顺带开放所有动作。

@EnableDataStatus 声明数据状态能力；基础实体默认提供的能力与最终实体打开的能力见数据状态指南。能力接口、Controller 暴露动作、权限清单与前端按钮必须保持一致。

一个对象是否“可以删除”和是否“有物理删除接口”是两回事。生命周期拦截仍会检查实体状态、租户和业务引用。

新增条目说明字段时，按以下顺序检查：SQL 列与默认值 → 各目标数据栈 Entity → 可写 AO 与校验 → Converter → VO → OpenAPI/i18n → 测试。如果还需要按说明搜索，再改 Query、各栈查询实现和查询测试。

不要只看编译通过：补一个创建后查询的断言，才能发现转换遗漏；补旧记录读取场景，才能发现默认值或兼容问题。

源码参考：AbstractAO、AbstractBaseQuery、IEntity。完整生成输入见需求模板。