leniu-tengyun-core 合计行(Total Line)规范

项目特征

特征	说明
包名前缀	net.xnzn.core.*
JDK 版本	21
双库切换	默认商户库，Executors.doInSystem() 切换系统库
分页工具	PageMethod.startPage()
结果封装	ReportBaseTotalVO<T>
分页封装	PageVO.of()

核心原则

合计行SQL只返回需要合计的数值字段，不返回非数值字段（如日期、名称、ID等）。

Service层实现

带合计行的分页查询

import net.xnzn.core.common.page.PageMethod;
import net.xnzn.core.common.page.PageVO;
import net.xnzn.core.common.vo.ReportBaseTotalVO;
import cn.hutool.core.collection.CollUtil;

// ⚠️ 系统默认在商户库执行，业务查询无需 Executors.readInSystem()
// Executors.readInSystem() 仅用于需要访问系统库的场景（如全局配置、商户管理）

public ReportBaseTotalVO<XxxVO> pageWithTotal(XxxPageParam param) {
    ReportBaseTotalVO<XxxVO> result = new ReportBaseTotalVO<>();

    // 1. 导出时不查询合计行(避免不必要的性能开销)
    if (CollUtil.isEmpty(param.getExportCols())) {
        XxxVO totalLine = mapper.getSummaryTotal(param);
        result.setTotalLine(totalLine);
    }

    // 2. 开启分页
    PageMethod.startPage(param.getPage());

    // 3. 查询数据
    List<XxxVO> list = mapper.getSummaryList(param);

    // 4. 封装分页结果
    result.setResultPage(PageVO.of(list));
    return result;
}

单独的合计行查询方法

public XxxVO getSummaryTotal(XxxPageParam param) {
    // 默认在商户库执行，无需 Executors 包装
    return mapper.getSummaryTotal(param);
}

Mapper XML规范

错误示例：返回非数值字段

<!-- ❌ 不要这样做 -->
<select id="getSummaryTotal" resultType="XxxVO">
    SELECT
        '合计' AS dateMonth,        <!-- ❌ 不要返回字符串 -->
        NULL AS schoolId,            <!-- ❌ 不要返回ID -->
        NULL AS schoolName,          <!-- ❌ 不要返回名称 -->
        SUM(staffCount) AS staffCount,
        SUM(amount) AS amount
    FROM xxx_table
</select>

正确示例：只返回数值字段

<!-- ✅ 正确做法 -->
<select id="getSummaryTotal" resultType="XxxVO">
    SELECT
        SUM(staff_count) AS staffCount,
        SUM(basic_salary) AS basicSalary,
        SUM(overtime_salary) AS overtimeSalary,
        SUM(personal_actual_amount) AS personalActualAmount,
        CASE
            WHEN SUM(staff_count) = 0 THEN 0
            ELSE SUM(avg_salary) / COUNT(DISTINCT tenant_id)
        END AS avgSalary
    FROM xxx_table
    <where>
        del_flag = 2
        <if test="startDate != null">
            AND crtime >= #{startDate}
        </if>
        <if test="endDate != null">
            AND crtime &lt;= #{endDate}
        </if>
    </where>
</select>

常见合计字段类型

字段类型	示例	合计方式
数量	staff_count, order_count	SUM()
金额	amount, salary	SUM()
百分比	discount_rate	AVG() 或 SUM() / COUNT()
计数	COUNT(DISTINCT id)	直接使用

特殊处理：平均值

<!-- 简单平均值 -->
SELECT AVG(amount) AS avgAmount

<!-- 加权平均值 -->
SELECT
    CASE
        WHEN SUM(count) = 0 THEN 0
        ELSE SUM(amount * count) / SUM(count)
    END AS weightedAvgAmount

<!-- 按维度平均 -->
SELECT
    CASE
        WHEN COUNT(DISTINCT tenant_id) = 0 THEN 0
        ELSE SUM(total_amount) / COUNT(DISTINCT tenant_id)
    END AS avgByTenant

Controller层实现

@PostMapping("/page")
@ApiOperation("分页查询（带合计）")
@RequiresAuthentication
public ReportBaseTotalVO<XxxVO> page(@RequestBody LeRequest<XxxParam> request) {
    XxxParam param = request.getContent();
    return xxxService.pageWithTotal(param);
}

@GetMapping("/total")
@ApiOperation("单独查询合计行")
@RequiresAuthentication
public XxxVO getTotal(XxxParam param) {
    return xxxService.getSummaryTotal(param);
}

导出时合计行处理

public void exportExcel(XxxParam param, HttpServletResponse response) {
    // 导出时需要查询合计行
    XxxVO totalLine = mapper.getSummaryTotal(param);

    // 分页查询所有数据（不分页）
    param.getPage().setSize(Integer.MAX_VALUE);
    List<XxxVO> list = mapper.getSummaryList(param);

    // 将合计行添加到列表末尾
    list.add(totalLine);

    // 导出
    exportService.export(list, response);
}

注意事项

• 合计SQL只返回数值字段，不返回字符串、ID、名称等
• 业务查询默认在商户库执行，无需 Executors 包装；仅访问系统库数据时才使用 Executors.doInSystem()
• 导出时通过 exportCols 判断是否需要合计行
• 金额字段类型与 Entity 保持一致：订单模块用 BigDecimal，钱包模块用 Long（详见 leniu-java-amount-handling）