412-frameworks-quarkus-panache

用途：在 Quarkus 项目中应用 Hibernate ORM 与 Panache 的数据访问模式，帮助审查与改进实体或仓储设计。主要能力：区分活动记录（PanacheEntity）与 PanacheRepository 的适用场景；使用带参数的 JPQL/Panache 查询，支持位置参数（?1）与命名参数（:param），避免不安全的字符串拼接；在实体上使用 @NamedQuery 获得可复用且构建期校验的查询；通过 project(Class) 做 DTO 投影以避免暴露托管实体；用 Page.of(pageIndex, pageSize) 与 query.count() 实现分页；用 JOIN FETCH 避免 N+1；用 @Version 实现乐观锁并处理 OptimisticLockException；在应用服务上使用 @Transactional；在 @QuarkusTest 中用 @TestTransaction 实现自动回滚；区分实体映射与 REST 边界暴露 DTO；在需要受控 SQL 且同一事务时使用 Hibernate 原生查询。使用方式：先阅读 references/412-frameworks-quarkus-panache.md 并检查项目现状，确定最小安全改动集，按参考规则实施或重构，然后运行验证。约束：改动持久化代码前必须先编译，运行 ./mvnw compile 或 mvn compile；项目须能编译；若编译失败立即停止，编译错误需由用户解决后才能继续；改动后运行 ./mvnw clean verify 或 mvn clean verify。适用场景：审查 Panache 实体或仓储、添加 DTO 投影、JOIN FETCH、分页或乐观锁、修复 N+1、改进活动记录与仓储设计。限制：具体规则与示例需查阅参考文件；资料未提供价格、平台支持范围或效果保证等信息。