ai-engineering-init 1.4.2 → 1.5.0

package/src/skills/leniu-java-mq/SKILL.md

@@ -0,0 +1,338 @@
+---
+name: leniu-java-mq
+description: |
+  leniu-tengyun-core / leniu-yunshitang 项目消息队列规范。当使用消息队列（MQ）时使用此skill，包括消息发送、消费和事务消息规范。
+
+  触发场景：
+  - 使用消息队列发送/消费消息
+  - 实现延迟消息（延迟队列）
+  - 消息消费失败重试处理
+  - 事务消息（保证消息和数据库事务一致性）
+
+  适用项目：
+  - leniu-tengyun-core：/Users/xujiajun/Developer/gongsi_proj/leniu-api/leniu-tengyun-core
+  - leniu-yunshitang：/Users/xujiajun/Developer/gongsi_proj/leniu-api/leniu-tengyun/leniu-yunshitang
+
+  触发词：消息队列、MQ、MqUtil、@MqConsumer、延迟消息、消息重试、事务消息
+---
+
+# leniu-tengyun-core 消息队列规范
+
+## 项目特征
+
+| 特征 | 说明 |
+|------|------|
+| **包名前缀** | `net.xnzn.core.*` |
+| **JDK 版本** | 21 |
+| **消息工具** | `MqUtil` |
+| **消费者注解** | `@MQMessageListener(group, topic, tag)` |
+| **消费者接口** | `implements MQListener<MqPayload<String>>` |
+| **主题常量** | `LeMqConstant.Topic` |
+| **延迟枚举** | `LeMqConstant.DelayDuration` |
+| **JSON工具** | `JacksonUtil` |
+| **异常类** | `LeException` |
+
+## 核心架构：三层分工
+
+```
+MsgSend（静态工具类）→ Listener（接收消息）→ Handler（分发处理）
+```
+
+| 层 | 职责 | 示例 |
+|----|------|------|
+| **XxxMessageSend** | 静态工具类，封装消息发送逻辑 | `OrderMessageSend` |
+| **XxxMqListenerYyy** | 消费者，接收 MQ 消息并分发到 Handler | `OrderMqListenerAsyncSave` |
+| **XxxMqHandler** | 业务处理，统一处理各类消息 | `OrderMqHandler` |
+
+## 消息发送
+
+### 三种发送方式
+
+```java
+import net.xnzn.core.common.mq.MqUtil;
+import net.xnzn.core.common.constant.LeMqConstant;
+import net.xnzn.core.common.utils.JacksonUtil;
+
+// 1. 普通消息（立即发送）
+MqUtil.send(JacksonUtil.writeValueAsString(po), LeMqConstant.Topic.XXX_TOPIC);
+
+// 2. 事务消息（在 DB 事务提交后发送，保证一致性）
+MqUtil.sendByTxEnd(JacksonUtil.writeValueAsString(po), LeMqConstant.Topic.XXX_TOPIC);
+
+// 3. 延迟消息（指定延迟时长后触发）
+MqUtil.sendDelay(JacksonUtil.writeValueAsString(po), LeMqConstant.Topic.XXX_TOPIC, LeMqConstant.DelayDuration.ONE_MINUTE);
+```
+
+**关键点**：
+- 消息体必须用 `JacksonUtil.writeValueAsString()` 序列化为 **String** 再发送
+- 事务消息用 `sendByTxEnd()`（如 DB 事务回滚则不发送）
+- 延迟时间用 `LeMqConstant.DelayDuration` 枚举（不用 `Duration.ofMinutes()`）
+
+### DelayDuration 枚举（常用值）
+
+```java
+LeMqConstant.DelayDuration.ONE_MINUTE      // 1分钟
+LeMqConstant.DelayDuration.THIRTY_MINUTES  // 30分钟
+// 其他枚举值参见 LeMqConstant.DelayDuration
+```
+
+### 消息发送类（静态工具类模式）
+
+```java
+/**
+ * 订单消息发送
+ * 关键特征：
+ * 1. 不是 @Component，是纯静态工具类
+ * 2. 私有构造器
+ * 3. PO 中包含 traceId 和 tenantId（用于跨线程追踪）
+ */
+@Slf4j
+public class XxxMessageSend {
+
+    private XxxMessageSend() {}  // 禁止实例化
+
+    private static final String MQ_ERROR_LOG = "发送MQ消息失败";
+
+    /**
+     * 普通消息（适用于非事务性发送）
+     */
+    public static void sendXxxEvent(XxxPO po) {
+        log.info("[XxxMQ]发送xxx事件");
+        po.setTraceId(LogUtil.getCurrentTraceId());
+        po.setTenantId(TenantContextHolder.getTenantId());
+        MqUtil.send(JacksonUtil.writeValueAsString(po), LeMqConstant.Topic.XXX_TOPIC);
+    }
+
+    /**
+     * 事务消息（在 @Transactional 方法中使用，事务提交后才发送）
+     */
+    public static void sendXxxEventByTx(XxxPO po) {
+        log.info("[XxxMQ]发送xxx事务消息");
+        po.setTraceId(LogUtil.getCurrentTraceId());
+        po.setTenantId(TenantContextHolder.getTenantId());
+        try {
+            MqUtil.sendByTxEnd(JacksonUtil.writeValueAsString(po), LeMqConstant.Topic.XXX_TOPIC);
+        } catch (Exception e) {
+            log.error(MQ_ERROR_LOG, e);
+        }
+    }
+
+    /**
+     * 延迟消息（超时取消等场景）
+     */
+    public static void sendXxxDelay(XxxPO po, LeMqConstant.DelayDuration delayDuration) {
+        log.info("[XxxMQ]发送xxx延迟消息");
+        po.setTraceId(LogUtil.getCurrentTraceId());
+        po.setTenantId(TenantContextHolder.getTenantId());
+        MqUtil.sendDelay(JacksonUtil.writeValueAsString(po), LeMqConstant.Topic.XXX_TOPIC, delayDuration);
+    }
+}
+```
+
+### PO 消息体规范
+
+```java
+import lombok.Data;
+
+/**
+ * MQ 消息 PO（Message Payload Object）
+ * 必须包含 traceId 和 tenantId 字段
+ */
+@Data
+public class XxxPO {
+
+    /** 链路追踪ID */
+    private String traceId;
+
+    /** 租户ID */
+    private String tenantId;
+
+    /** 业务字段 */
+    private Long orderId;
+    private String outTradeNo;
+    // 其他字段...
+}
+```
+
+## 消息消费
+
+### Listener 类（真实代码模式）
+
+```java
+import lombok.extern.slf4j.Slf4j;
+import net.xnzn.core.common.mq.MqPayload;
+import net.xnzn.framework.mq.MQListener;
+import net.xnzn.framework.mq.MQMessageListener;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.context.annotation.Lazy;
+
+/**
+ * MQ 消费者 Listener
+ * @see LeMqConstant.Topic#XXX_TOPIC
+ */
+@Slf4j
+@MQMessageListener(
+    group = "module-xxx-topic-name",   // 消费组，格式：模块名-topic-tag
+    topic = "xxx",                     // Topic 名称
+    tag = "xxx-topic-name"             // Tag 名称（对应 LeMqConstant.Topic）
+)
+public class XxxMqListenerYyy implements MQListener<MqPayload<String>> {
+
+    @Autowired
+    @Lazy   // ⚠️ 必须 @Lazy，避免循环依赖
+    private XxxMqHandler xxxMqHandler;
+
+    @Override
+    public void onMessage(MqPayload<String> payload) {
+        // 委托给 Handler 处理，使用方法引用
+        xxxMqHandler.handleMessage(payload, XxxPO.class, XxxMqHandler::handleXxx);
+    }
+}
+```
+
+### Handler 类（统一处理消息）
+
+```java
+import cn.hutool.core.text.CharSequenceUtil;
+import com.pig4cloud.pigx.common.core.exception.LeException;
+import lombok.extern.slf4j.Slf4j;
+import net.xnzn.core.common.export.util.I18nUtil;
+import net.xnzn.core.common.mq.MqPayload;
+import net.xnzn.core.common.utils.JacksonUtil;
+import net.xnzn.framework.data.tenant.TenantContextHolder;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.context.annotation.Lazy;
+import org.springframework.stereotype.Service;
+
+import java.util.function.BiConsumer;
+
+@Slf4j
+@Service
+public class XxxMqHandler {
+
+    @Lazy
+    @Autowired
+    private XxxService xxxService;
+
+    /**
+     * 统一处理调用（核心模板方法）
+     * 负责：反序列化、设置租户上下文、异常兜底
+     */
+    public <T> void handleMessage(MqPayload<String> payload, Class<T> clz, BiConsumer<XxxMqHandler, T> handleFunc) {
+        I18nUtil.loadDefaultLocale();
+        try {
+            log.info("[Xxx消息]收到消息 {}", payload);
+            T payloadData = JacksonUtil.readValue(payload.getData(), clz);
+            if (payloadData != null) {
+                TenantContextHolder.setTenantId(payload.getTenantId());  // 设置租户上下文
+                handleFunc.accept(this, payloadData);
+            } else {
+                log.error("[Xxx消息]解析失败");
+            }
+        } catch (Exception e) {
+            log.error("[Xxx消息]处理异常", e);
+        }
+    }
+
+    /**
+     * 处理 xxx 事件
+     */
+    public void handleXxx(XxxPO payload) {
+        try {
+            log.info("[Xxx事件]MQ消费：开始");
+            xxxService.processXxx(payload);
+            log.info("[Xxx事件]MQ消费：消息消费完成");
+        } catch (Exception e) {
+            log.error("[Xxx事件]MQ消费：处理异常", e);
+        }
+    }
+}
+```
+
+## 常见场景
+
+### 场景1：事务消息（下单后通知）
+
+```java
+@Transactional(rollbackFor = Exception.class)
+public void createOrder(OrderParam param) {
+    // 1. 保存订单
+    OrderInfo order = OrderInfo.newDefaultInstance();
+    order.setCanteenId(param.getCanteenId());
+    orderMapper.insert(order);
+
+    // 2. 事务提交后发送消息（保证一致性）
+    OrderPlacedPO po = new OrderPlacedPO();
+    po.setOrderInfo(order);
+    OrderMessageSend.sendOrderPlacedByTx(po);  // 内部使用 sendByTxEnd
+
+    log.info("订单创建成功，orderId:{}", order.getId());
+}
+```
+
+### 场景2：延迟消息（订单超时取消）
+
+```java
+public static LocalDateTime sendOrderTimeout(String macOrderId, LeMqConstant.DelayDuration delayDuration) {
+    log.info("[订单MQv3]发送未支付订单异步支付超时通知");
+    OrderCancelPO po = new OrderCancelPO();
+    po.setMacOrderId(macOrderId);
+    po.setTenantId(TenantContextHolder.getTenantId());
+    po.setTraceId(LogUtil.getCurrentTraceId());
+
+    // 延迟发送
+    MqUtil.sendDelay(JacksonUtil.writeValueAsString(po), LeMqConstant.Topic.ORDER_V3_ASYNC_TIMEOUT, delayDuration);
+
+    // 返回预计触发时间
+    return LocalDateTime.now().plusSeconds(delayDuration.getMilliseconds() / 1000);
+}
+```
+
+### 场景3：带 Redisson 分布式锁的 MQ 消费
+
+```java
+public void orderAsyncSave(OrderSavePO payload) {
+    // 消费时加分布式锁（防止并发处理同一订单）
+    RLock lock = RedisUtil.getLock(OrderCacheConstants.orderCacheSaveLockKey(payload.getMacOrderId()));
+    lock.lock();
+    try {
+        log.info("[订单异步保存]MQ消费：开始");
+        doSaveOrder(payload);
+        log.info("[订单异步保存]MQ消费：消息消费完成");
+    } catch (Exception e) {
+        log.error("[订单异步保存]MQ消费：处理异常", e);
+    } finally {
+        // 安全释放锁
+        try {
+            if (lock.isHeldByCurrentThread() && lock.isLocked()) {
+                lock.unlock();
+            }
+        } catch (Exception e) {
+            log.error("解锁异常", e);
+        }
+    }
+}
+```
+
+## 日志规范
+
+```java
+// 发送端日志格式
+log.info("[模块MQv3]发送xxx事件");
+
+// 消费端日志格式
+log.info("[xxx事件]MQ消费：开始");
+log.info("[xxx事件]MQ消费：消息消费完成");
+log.error("[xxx事件]MQ消费：处理异常", e);
+```
+
+## 常见错误
+
+| 错误写法 | 正确写法 | 说明 |
+|---------|---------|------|
+| `MqUtil.send(dto, topic)` 直接传对象 | `MqUtil.send(JacksonUtil.writeValueAsString(dto), topic)` | 必须先序列化为 String |
+| `@MqConsumer(topic = ...)` | `@MQMessageListener(group, topic, tag)` + `implements MQListener<MqPayload<String>>` | 实际框架注解不同 |
+| `Duration.ofMinutes(30)` | `LeMqConstant.DelayDuration.THIRTY_MINUTES` | 延迟枚举不是 Duration |
+| 忘记在 PO 中设置 `traceId`/`tenantId` | `po.setTraceId(LogUtil.getCurrentTraceId())` | 多租户追踪必须设置 |
+| 消费方法直接 `@Autowired` 服务 | `@Autowired @Lazy` | 避免循环依赖 |
+| 在 MQ 发送类上加 `@Component` | 纯静态工具类（私有构造器，不注入 Spring） | 发送类是静态工具 |

package/src/skills/leniu-java-mybatis/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: leniu-java-mybatis
+description: |
+  leniu-tengyun-core 项目 MyBatis/MyBatis-Plus 使用规范。当编写 Mapper、XML 映射、分页查询时使用此 skill。
+
+  触发场景：
+  - 编写 Mapper 接口（extends BaseMapper）
+  - 编写 MyBatis XML 映射文件（动态 SQL）
+  - 使用 LambdaQueryWrapper 构建查询
+  - 分页查询（PageHelper + PageVO）
+  - 租户隔离控制（@InterceptorIgnore）
+
+  触发词：MyBatis、MyBatisPlus、Mapper、LambdaQueryWrapper、XML映射、动态SQL、BaseMapper、分页查询、租户隔离、报表Mapper、PageHelper
+---
+
+# leniu MyBatis 规范
+
+## 项目特征速查
+
+| 项 | 值 |
+|---|---|
+| XML 位置 | **与 Mapper 接口同目录**（非 `resources/mapper/`） |
+| 分页 | PageHelper → `PageMethod.startPage(PageDTO)` → `PageVO.of(list)` |
+| 逻辑删除 | **1=删除，2=正常**（与 RuoYi 相反） |
+| Service | 无接口，直接 `@Service` 类，Mapper 字段名统一用 `baseMapper` |
+| 循环依赖 | 跨模块依赖用 `@Autowired @Lazy` |
+
+## Mapper 接口模板
+
+### 基础 Mapper
+
+```java
+@Mapper
+public interface XxxMapper extends BaseMapper<XxxEntity> {
+
+    List<XxxVO> listByParam(@Param("param") XxxParam param);
+}
+```
+
+### 忽略租户隔离（方法级）
+
+```java
+@Mapper
+public interface XxxMapper extends BaseMapper<XxxEntity> {
+
+    @InterceptorIgnore(tenantLine = "true")
+    List<XxxVO> queryWithoutTenant(@Param("param") XxxParam param);
+}
+```
+
+### 全量忽略拦截器（类级别）
+
+```java
+@Mapper
+@InterceptorIgnore  // 无参数，跳过所有拦截器（租户、数据权限等）
+public interface XxxMapper extends BaseMapper<XxxEntity>, BaseExistsMapper<XxxEntity> {
+
+    List<XxxVO> listVoByIds(@Param("orderIds") List<Long> ids, @Param("tenantId") String tenantId);
+
+    @QueryExtension
+    List<XxxIdDateVO> queryXxx(@Param("param") XxxSearchParam param,
+                               @Param("permission") XxxUserPermissionDTO permission);
+}
+```
+
+- `BaseExistsMapper` 提供 `existsOne(Wrapper)` 方法（比 `selectCount > 0` 高效）
+- 适用于数据量大、需跨租户查询的核心表
+
+## XML 模板
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
+    "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
+<mapper namespace="net.xnzn.core.xxx.mapper.XxxMapper">
+
+    <select id="listByParam" resultType="net.xnzn.core.xxx.vo.XxxVO">
+        SELECT
+            t.id,
+            t.name,
+            t.status
+        FROM table_name t
+        <where>
+            t.del_flag = 2
+            <if test="param.status != null">
+                AND t.status = #{param.status}
+            </if>
+            <if test="param.keyword != null and param.keyword != ''">
+                AND t.name LIKE CONCAT('%', #{param.keyword}, '%')
+            </if>
+        </where>
+        ORDER BY t.crtime DESC
+    </select>
+</mapper>
+```
+
+### XML 编写规则
+
+| 规则 | 说明 |
+|------|------|
+| 禁止 `SELECT *` | 必须明确指定字段 |
+| `del_flag = 2` | 正常数据条件 |
+| `#{}` 占位符 | 禁止 `${}`（SQL 注入） |
+| `<where>` 标签 | 自动处理 AND 前缀 |
+| 特殊字符 | `&lt;` / `&gt;` 或 `<![CDATA[ ]]>` |
+
+### 常用动态 SQL 片段
+
+```xml
+<!-- IN 查询 -->
+<if test="param.ids != null and param.ids.size() > 0">
+    AND t.id IN
+    <foreach collection="param.ids" item="id" open="(" separator="," close=")">
+        #{id}
+    </foreach>
+</if>
+
+<!-- 多条件 OR -->
+<if test="param.keyword != null and param.keyword != ''">
+    AND (t.name LIKE CONCAT('%', #{param.keyword}, '%')
+         OR t.code LIKE CONCAT('%', #{param.keyword}, '%'))
+</if>
+
+<!-- 时间范围 -->
+<if test="param.startDate != null">
+    AND t.crtime >= #{param.startDate}
+</if>
+<if test="param.endDate != null">
+    AND t.crtime &lt;= #{param.endDate}
+</if>
+```
+
+## LambdaQuery 使用
+
+```java
+List<XxxEntity> list = mapper.selectList(
+    Wrappers.lambdaQuery(XxxEntity.class)
+        .eq(XxxEntity::getStatus, 1)
+        .eq(XxxEntity::getDelFlag, 2)  // 2=正常
+        .in(CollUtil.isNotEmpty(idList), XxxEntity::getId, idList)
+        .like(StrUtil.isNotBlank(name), XxxEntity::getName, name)
+        .ge(startDate != null, XxxEntity::getCrtime, startDate)
+        .le(endDate != null, XxxEntity::getCrtime, endDate)
+        .orderByDesc(XxxEntity::getCrtime)
+);
+```
+
+## Service 注入规范
+
+```java
+@Slf4j
+@Service
+@Validated
+public class XxxService {
+
+    @Autowired
+    private XxxMapper baseMapper;        // ✅ 统一命名 baseMapper
+
+    @Autowired @Lazy
+    private XxxDetailService xxxDetailService;  // ✅ 跨模块用 @Lazy
+
+    public XxxEntity getOne(Long id) {
+        return baseMapper.selectById(id);
+    }
+
+    public boolean exists(String macOrderId) {
+        return baseMapper.existsOne(
+            Wrappers.lambdaQuery(XxxEntity.class)
+                .eq(XxxEntity::getMacOrderId, macOrderId)
+                .eq(XxxEntity::getDelFlag, 2)
+        );
+    }
+}
+```
+
+## 分页查询
+
+```java
+public PageVO<XxxVO> pageList(XxxParam param) {
+    // ✅ 传入 PageDTO 对象（不要拆 pageNum/pageSize）
+    if (Objects.nonNull(param.getPage())) {
+        PageMethod.startPage(param.getPage());
+    }
+
+    List<XxxVO> records = xxxMapper.listByParam(param);
+
+    return PageVO.of(records);  // 自动提取 total 等信息
+}
+```
+
+Mapper 方法返回 `List<XxxVO>` 即可，PageHelper 拦截器自动处理分页。
+
+## 报表 Mapper（无 BaseMapper）
+
+```java
+@Mapper
+public interface ReportXxxMapper {  // ✅ 不继承 BaseMapper
+
+    List<XxxVO> listSummary(
+        @Param("param") XxxParam param,
+        @Param("authPO") MgrUserAuthPO authPO,
+        @Param("dataPermission") ReportDataPermissionParam dataPermission
+    );
+
+    XxxVO getSummaryTotal(  // 合计行
+        @Param("param") XxxParam param,
+        @Param("authPO") MgrUserAuthPO authPO,
+        @Param("dataPermission") ReportDataPermissionParam dataPermission
+    );
+}
+```
+
+**命名规律**：`listXxx()` 分页数据 / `listXxx_COUNT()` 计数 / `getSummaryTotal()` 合计行 / `listXxxByDay()` 按维度
+
+## 合计行查询
+
+```xml
+<!-- 列表查询 -->
+<select id="listByParam" resultType="XxxVO">
+    SELECT id, name, amount, count
+    FROM table_name
+    <where>...</where>
+    ORDER BY id DESC
+</select>
+
+<!-- 合计查询：只返回数值字段 -->
+<select id="getSummaryTotal" resultType="XxxVO">
+    SELECT SUM(amount) AS amount, SUM(count) AS count
+    FROM table_name
+    <where>...</where>
+</select>
+```
+
+除零处理：
+```xml
+CASE WHEN SUM(count) = 0 THEN 0 ELSE SUM(amount) / SUM(count) END AS avgAmount
+```
+
+## 禁止项
+
+```java
+// ❌ 继承 RuoYi TenantEntity
+import org.dromara.common.mybatis.core.domain.TenantEntity;
+
+// ❌ delFlag: 0=正常（leniu 是 2=正常）
+wrapper.eq(XxxEntity::getDelFlag, 0);
+
+// ❌ XML 放 resources/mapper/（必须与 Mapper 接口同目录）
+
+// ❌ MapstructUtils（用 BeanUtil.copyProperties）
+MapstructUtils.convert(source, Target.class);
+
+// ❌ Service 继承 IService / ServiceImpl
+public interface IXxxService extends IService<XxxEntity> {}
+```
+
+## XML 文件位置
+
+```
+net.xnzn.core.xxx.mapper/
+├── XxxMapper.java      # 接口
+└── XxxMapper.xml       # XML（同目录！）
+```
+
+## 参考文档
+
+- 报表 Mapper 完整示例：详见 `references/report-mapper.md`

package/src/skills/leniu-java-mybatis/references/report-mapper.md

@@ -0,0 +1,88 @@
+# 报表 Mapper 完整示例
+
+## Mapper 接口（来自 ReportAnalysisTurnoverMapper 真实代码）
+
+```java
+@Mapper
+public interface ReportXxxMapper {
+
+    // 分页列表查询（PageHelper 拦截，方法返回 List）
+    List<XxxVO> listSummary(
+        @Param("param") XxxParam param,
+        @Param("authPO") MgrUserAuthPO authPO,
+        @Param("dataPermission") ReportDataPermissionParam dataPermission
+    );
+
+    // 合计行查询（不分页，返回单个汇总 VO）
+    XxxVO getSummaryTotal(
+        @Param("param") XxxParam param,
+        @Param("authPO") MgrUserAuthPO authPO,
+        @Param("dataPermission") ReportDataPermissionParam dataPermission
+    );
+
+    // 按日/按月分组（对应 dateType 参数）
+    List<XxxVO> listSummaryByDay(
+        @Param("param") XxxParam param,
+        @Param("authPO") MgrUserAuthPO authPO,
+        @Param("dataPermission") ReportDataPermissionParam dataPermission
+    );
+    List<XxxVO> listSummaryByMonth(
+        @Param("param") XxxParam param,
+        @Param("authPO") MgrUserAuthPO authPO,
+        @Param("dataPermission") ReportDataPermissionParam dataPermission
+    );
+
+    // 汇总数据（总金额、人次等）
+    ReportTurnoverPO getTurnoverTotal(
+        @Param("param") XxxParam param,
+        @Param("authPO") MgrUserAuthPO authPO,
+        @Param("dataPermission") ReportDataPermissionParam dataPermission
+    );
+
+    // 排行榜类（不需要 authPO 时可省略）
+    List<RankVO> getXxxRank(
+        @Param("param") RankParam param,
+        @Param("dataPermission") ReportDataPermissionParam dataPermission
+    );
+}
+```
+
+## 关键规则
+
+1. `@Mapper` 注解，**不继承 BaseMapper**（报表无 CRUD）
+2. 所有参数必须加 `@Param`，顺序：`param` -> `authPO` -> `dataPermission`
+3. 分页列表返回 `List<VO>`，由 Service 层调用 `PageMethod.startPage()` 控制
+4. 合计行返回单个 PO/VO 对象
+5. COUNT 方法（`listXxx_COUNT`）配合 `CompletableFuture` 并发使用
+
+## 命名规律
+
+| 类型 | 命名 |
+|------|------|
+| 分页数据 | `listXxx()` |
+| 对应 COUNT | `listXxx_COUNT()`（下划线 + COUNT） |
+| 合计行 | `getSummaryTotal()` / `getSummaryXxxTotal()` |
+| 按维度变体 | `listXxxByDay()` / `listXxxByDay_COUNT()` |
+
+## 合计 SQL 常用函数
+
+| 函数 | 用途 |
+|------|------|
+| `SUM()` | 求和 |
+| `COUNT(*)` | 计数 |
+| `AVG()` | 平均值 |
+| `MAX()` / `MIN()` | 极值 |
+
+## 除零处理
+
+```xml
+CASE
+    WHEN SUM(count) = 0 THEN 0
+    ELSE SUM(amount) / SUM(count)
+END AS avgAmount
+
+CASE
+    WHEN SUM(staff_count) = 0 THEN 0
+    ELSE SUM(avg_salary) / COUNT(DISTINCT tenant_id)
+END AS avgSalary
+```