用途:该技能约束业务逻辑入口点的返回载荷类型。当入口点需要返回领域实体数据时,载荷类型必须是领域实体类型本身,而不是派生的 DTO、视图模型、投影或响应模型。
主要能力:识别载荷是否承载领域实体数据;检查声明的返回类型中是否插入了包装类型、DTO、响应模型或投影;追踪 toDto、toPayload、toResponse、fromEntity 等转换代码,并将业务逻辑边界上的实体到载荷映射视为违规。
使用方式:在编写或修改业务逻辑载荷时,先判断入口点应返回领域实体、实体 ID 还是其他业务结果,仅在应包含领域实体数据时应用本技能。单一实体直接使用实体类型,多实体使用实体类型的集合;若载荷包装在成功类型中,则把实体类型直接放入包装器。删除仅镜像实体形状或仅重新包装实体的类型与转换代码,保留实体的类型、身份与行为契约。例如应写 type FindCustomerByIdQueryHandlerSuccess = { customer: Customer },而非使用 CustomerPayload;应写 orders: Order[],而非 OrderListItem[]。
适用场景:定义业务逻辑入口点成功载荷、定义携带实体数据的 QueryHandlerSuccess 或 CommandHandlerSuccess 类型、在业务逻辑边界映射领域实体、从业务逻辑返回一个或多个领域实体、以及在载荷应含实体数据处引入 DTO 或响应模型等场景。
限制:仅适用于入口点本应返回领域实体数据的情况,需与其他入口点规则共存,例如非创建命令处理器返回项目约定的空等价物、创建命令处理器只返回创建的 ID。不得为满足返回形状而扁平化或重命名实体字段。具体安装命令与配套工具用法暂未提供。