leniu-dev 2.0.0

package/src/skills/leniu-java-total-line/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: leniu-java-total-line
+description: |
+  leniu-tengyun-core / leniu-yunshitang 项目合计行查询规范。当实现报表分页查询需要合计行功能时使用此skill。
+
+  触发场景：
+  - 实现报表分页查询合计行（Service层合计查询）
+  - 编写Mapper XML合计SQL（只返回数值字段）
+  - Controller层合计行数据组装
+  - 合计查询开关控制
+
+  适用项目：
+  - 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
+
+  触发词：合计行、totalLine、报表合计、SUM合计、ReportBaseTotalVO、合计查询
+---
+
+# leniu-tengyun-core 合计行(Total Line)规范
+
+## 项目特征
+
+| 特征 | 说明 |
+|------|------|
+| **包名前缀** | `net.xnzn.core.*` |
+| **JDK 版本** | 21 |
+| **双库切换** | 默认商户库，`Executors.doInSystem()` 切换系统库 |
+| **分页工具** | `PageMethod.startPage()` |
+| **结果封装** | `ReportBaseTotalVO<T>` |
+| **分页封装** | `PageVO.of()` |
+
+## 核心原则
+
+**合计行SQL只返回需要合计的数值字段**，不返回非数值字段（如日期、名称、ID等）。
+
+## Service层实现
+
+### 带合计行的分页查询
+
+```java
+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;
+}
+```
+
+### 单独的合计行查询方法
+
+```java
+public XxxVO getSummaryTotal(XxxPageParam param) {
+    // 默认在商户库执行，无需 Executors 包装
+    return mapper.getSummaryTotal(param);
+}
+```
+
+## Mapper XML规范
+
+### 错误示例：返回非数值字段
+
+```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>
+```
+
+### 正确示例：只返回数值字段
+
+```xml
+<!-- ✅ 正确做法 -->
+<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)` | 直接使用 |
+
+## 特殊处理：平均值
+
+```xml
+<!-- 简单平均值 -->
+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层实现
+
+```java
+@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);
+}
+```
+
+## 导出时合计行处理
+
+```java
+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）

package/src/skills/leniu-marketing-price-rule-customizer/SKILL.md

@@ -0,0 +1,301 @@
+---
+name: leniu-marketing-price-rule-customizer
+description: |
+  leniu-tengyun-core 项目营销计费（price）规则定制指南。当需要定制营销计费规则时使用，支持新增规则类型、重写规则逻辑、扩展 DTO 字段。
+
+  触发场景：
+  - 新增营销计费规则类型（折扣、满减、限额、补贴等）
+  - 重写现有计费规则逻辑（@Primary 模式）
+  - 扩展规则 DTO 字段（向后兼容）
+  - 定制规则计算行为（handle 方法实现）
+  - 注册规则枚举（RulePriceEnum）
+
+  适用项目：
+  - 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
+
+  触发词：营销计费、计价规则、RulePriceHandler、RulePriceEnum、折扣规则、满减规则、限额规则、补贴规则
+---
+
+# leniu-tengyun-core 营销计费规则定制
+
+## 概述
+
+leniu-tengyun-core 项目的营销计费（price）规则功能采用扩展点设计，支持灵活的规则定制。
+
+营销计费规则是营销系统的核心组件，负责计算订单的优惠金额、限制消费行为、提供补贴等功能。
+
+## 何时使用此 Skill
+
+- 需要新增一个计价规则类型
+- 需要修改现有规则的计算逻辑
+- 需要为规则添加新的配置字段
+- 需要针对特定项目定制规则行为
+- 参考现有规则实现新的定制需求
+
+## 规则定制工作流
+
+### 步骤1：确定定制模式
+
+根据需求选择合适的定制模式：
+
+**模式A：新增规则**
+- 适用场景：创建全新的规则类型
+- 需要创建：DTO、扩展接口、默认实现
+
+**模式B：重写规则（@Primary）**
+- 适用场景：完全替换现有规则行为
+- 需要创建：定制实现类（使用@Primary注解）
+- 可选：扩展DTO字段
+
+**模式C：重写规则（Ordered）**
+- 适用场景：多个实现共存
+- 需要创建：定制实现类（实现Ordered接口）
+
+### 步骤2：理解规则结构
+
+了解：
+- 规则接口层次（RulePriceHandler → Extension → Implementation）
+- 规则DTO结构
+- 规则计算入参（RulePriceResultOrderDTO、MarketRuleVO、orderResults）
+- 规则计算流程
+- 常用工具类（MarketUtil、MarketRuleRangeService）
+
+### 步骤3：参考实际案例
+
+查看实际案例，了解如何实现具体的定制需求：
+- **案例1**：支持自定义场景类型选择（@Primary + DTO扩展）
+- **案例2**：移除订单类型过滤（直接修改）
+
+### 步骤4：实现规则定制
+
+#### 新增规则的实现步骤
+
+1. **创建规则DTO**
+   - 位置：`net.xnzn.core.marketing.v2.rule.price.handler.[ruletype].dto`
+   - 包含规则配置字段
+   - 实现 `toString()` 方法返回可读描述
+
+2. **创建扩展接口**
+   - 位置：`net.xnzn.core.marketing.v2.rule.price.handler.[ruletype].extension`
+   - 继承 `RulePriceHandler`
+   - 实现 `getRuleType()` 和 `checkRuleInfo()` 方法
+
+3. **创建默认实现**
+   - 位置：`net.xnzn.core.marketing.v2.rule.price.handler.[ruletype].extension.impl`
+   - 实现扩展接口
+   - 添加 `@Service` 注解
+   - 实现 `handle()` 方法
+
+4. **注册规则枚举**
+   - 在 `RulePriceEnum` 中添加新的规则类型
+
+#### 重写规则的实现步骤（@Primary模式）
+
+1. **（可选）扩展DTO字段**
+   - 在定制项目中覆盖核心DTO类
+   - 添加新字段并保持向后兼容
+
+2. **创建定制实现**
+   - 位置：定制项目包（如 `net.xnzn.yunshitang.marketing.handler`）
+   - 继承默认实现类（可选，用于复用逻辑）
+   - 实现扩展接口
+   - 添加 `@Service` 和 `@Primary` 注解
+   - 重写 `handle()` 方法
+
+3. **实现定制逻辑**
+   - 解析规则配置（包含新字段）
+   - 实现自定义计算逻辑
+   - 更新订单优惠金额或抛出限制异常
+
+### 步骤5：测试规则
+
+1. 测试向后兼容性（新字段为null的场景）
+2. 测试新功能（新字段有值的场景）
+3. 测试边界条件
+4. 测试与其他规则的组合使用
+
+## 代码模板
+
+### 新增规则模板
+
+```java
+// 1. DTO
+@Data
+@ApiModel("计价规则详情-[规则名称]")
+public class [RuleType]DTO {
+    @ApiModelProperty("[字段说明]")
+    private [Type] fieldName;
+
+    @Override
+    public String toString() {
+        return "字段：" + fieldName;
+    }
+}
+
+// 2. 扩展接口
+public interface [RuleType]HandlerExtension extends RulePriceHandler {
+    @Override
+    default Integer getRuleType() {
+        return RulePriceEnum.[RULE_TYPE_ENUM].getKey();
+    }
+
+    @Override
+    default String checkRuleInfo(String ruleInfo) {
+        [RuleType]DTO rule = JSON.parseObject(ruleInfo, [RuleType]DTO.class);
+        return rule.toString();
+    }
+}
+
+// 3. 默认实现
+@Slf4j
+@Service
+public class Default[RuleType]HandlerImpl implements [RuleType]HandlerExtension {
+
+    @Autowired
+    private MarketRuleRangeService rangeService;
+
+    @Override
+    public void handle(RulePriceResultOrderDTO order, MarketRuleVO rule,
+                      List<RulePriceResultOrderDTO> orderResults) {
+        // 1. 解析规则配置
+        [RuleType]DTO ruleInfo = JSON.parseObject(rule.getRuleInfo(), [RuleType]DTO.class);
+
+        // 2. 查询规则适用范围
+        List<MarketRuleRange> rangeList = rangeService.listRuleRangeLatest(rule.getRuleId());
+
+        // 3. 实现规则计算逻辑
+        // ...
+
+        // 4. 更新订单优惠金额或抛出异常
+        order.setDiscountsAmount(order.getDiscountsAmount().add(discountAmount));
+    }
+}
+```
+
+### 重写规则模板（@Primary）
+
+```java
+@Slf4j
+@Service
+@Primary  // 标记为主要实现
+public class Custom[RuleType]HandlerImpl extends Default[RuleType]HandlerImpl
+        implements [RuleType]HandlerExtension {
+
+    @Autowired
+    private MarketRuleRangeService rangeService;
+
+    @Override
+    public void handle(RulePriceResultOrderDTO order, MarketRuleVO rule,
+                      List<RulePriceResultOrderDTO> orderResults) {
+        // 解析规则配置（可能包含扩展字段）
+        [RuleType]DTO ruleInfo = JSON.parseObject(rule.getRuleInfo(), [RuleType]DTO.class);
+
+        // 实现定制逻辑
+        // 可以调用父类方法：super.handle(order, rule, orderResults);
+        // 或完全自定义实现
+    }
+}
+```
+
+## 常见规则类型
+
+### 优惠类规则
+- 折扣规则：`PriceDiscountHandlerExtension`
+- 菜品折扣：`PriceDishDiscountHandlerExtension`
+- 商品折扣：`PriceGoodsDiscountHandlerExtension`
+- 满减规则：`PriceReductionFixedHandlerExtension`
+
+### 限制类规则
+- 限额-单次金额：`PriceLimitMaxAmountHandlerExtension`
+- 限额-累计次数：`PriceLimitMaxCountHandlerExtension`
+- 限额-累计金额：`PriceLimitSumAmountHandlerExtension`
+
+### 补贴类规则
+- 固定补贴：`PriceSubsidyFixedHandlerExtension`
+- 累计赠送：`PriceSumGiveHandlerExtension`
+
+## 最佳实践
+
+### 包名规范
+- 覆盖核心类：使用核心工程的包名（`net.xnzn.core.marketing.v2.rule.price.handler.[ruletype]`）
+- 定制实现：使用项目特定包名（如 `net.xnzn.yunshitang.marketing.handler`）
+
+### 类名规范
+- 扩展接口：`[RuleType]HandlerExtension`
+- 默认实现：`Default[RuleType]HandlerImpl`
+- 定制实现：`Custom[RuleType]HandlerImpl` 或描述性名称
+
+### 注解使用
+- 所有实现类必须添加 `@Service` 注解
+- 重写规则使用 `@Primary` 注解（推荐）
+- 日志记录使用 `@Slf4j` 注解
+
+### 向后兼容
+- 扩展DTO字段时，新字段应支持null值
+- 新字段为null时应保持原有行为
+- 在toString方法中包含所有字段
+
+## 快速开始示例
+
+假设需要为限额累计金额规则（`PriceLimitSumAmountHandlerExtension`）添加场景类型选择功能：
+
+1. **扩展DTO**：在 `PriceLimitSumAmountDTO` 中添加 `sceneTypes` 字段
+2. **创建定制实现**：创建 `CrossScenePriceLimitSumAmountHandlerImpl`，位于 `net.xnzn.yunshitang.marketing.handler`，使用 `@Primary` 注解
+3. **实现逻辑**：在 `handle()` 方法中使用 `sceneTypes` 字段过滤订单
+4. **向后兼容**：`sceneTypes` 为null时查询所有场景
+
+```java
+// 1. 扩展DTO（在核心工程包名下覆盖）
+// 位置：net.xnzn.core.marketing.v2.rule.price.handler.limitsum.dto.PriceLimitSumAmountDTO
+@Data
+@ApiModel("限额-累计金额规则详情")
+public class PriceLimitSumAmountDTO {
+    @ApiModelProperty("累计金额限额（分）")
+    private BigDecimal limitAmount;
+
+    // 扩展字段：场景类型列表，null时表示所有场景
+    @ApiModelProperty("适用场景类型（null=所有）")
+    private List<Integer> sceneTypes;
+
+    @Override
+    public String toString() {
+        return "limitAmount=" + limitAmount + ", sceneTypes=" + sceneTypes;
+    }
+}
+
+// 2. 定制实现（在yunshitang项目包下）
+// 位置：net.xnzn.yunshitang.marketing.handler
+@Slf4j
+@Service
+@Primary
+public class CrossScenePriceLimitSumAmountHandlerImpl
+        implements PriceLimitSumAmountHandlerExtension {
+
+    @Autowired
+    private MarketRuleRangeService rangeService;
+
+    @Override
+    public void handle(RulePriceResultOrderDTO order, MarketRuleVO rule,
+                      List<RulePriceResultOrderDTO> orderResults) {
+        PriceLimitSumAmountDTO ruleInfo = JSON.parseObject(
+            rule.getRuleInfo(), PriceLimitSumAmountDTO.class);
+
+        // 场景过滤（向后兼容：null时不过滤）
+        if (CollUtil.isNotEmpty(ruleInfo.getSceneTypes())
+                && !ruleInfo.getSceneTypes().contains(order.getSceneType())) {
+            return; // 不在适用场景内，跳过
+        }
+
+        // 原有累计金额限额逻辑...
+        BigDecimal sumAmount = calcSumAmount(order, orderResults);
+        if (sumAmount.compareTo(ruleInfo.getLimitAmount()) >= 0) {
+            throw new LeException("已超出累计消费限额");
+        }
+    }
+}
+```
+
+## 参考文档
+
+详见：[leniu-tengyun-core 源码](/Users/xujiajun/Developer/gongsi_proj/core/leniu-tengyun-core)