leniu-dev 2.0.0

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

@@ -0,0 +1,285 @@
+---
+name: leniu-marketing-recharge-rule-customizer
+description: |
+  leniu-tengyun-core 项目营销充值（recharge）规则定制指南。当需要定制营销充值规则时使用，支持新增充值规则类型、重写规则逻辑、扩展 DTO 字段。
+
+  触发场景：
+  - 新增营销充值规则类型（满赠、按次赠送、限额、管理费等）
+  - 重写现有充值规则逻辑（@Primary 模式）
+  - 扩展充值规则 DTO 字段（向后兼容）
+  - 定制充值规则计算行为（handle 方法实现）
+  - 注册充值规则枚举（RuleRechargeEnum）
+
+  适用项目：
+  - 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
+
+  触发词：营销充值、充值规则、RuleRechargeHandler、RuleRechargeEnum、满赠规则、充值赠送、管理费规则
+---
+
+# leniu-tengyun-core 营销充值规则定制
+
+## 概述
+
+leniu-tengyun-core 项目的营销充值（recharge）规则功能采用扩展点设计，支持灵活的规则定制。
+
+营销充值规则是营销系统的核心组件，负责计算充值的优惠金额、限制充值行为、收取管理费等功能。
+
+## 何时使用此 Skill
+
+- 需要新增一个充值规则类型
+- 需要修改现有规则的计算逻辑
+- 需要为规则添加新的配置字段
+- 需要针对特定项目定制规则行为
+- 参考现有规则实现新的定制需求
+
+## 规则定制工作流
+
+### 步骤1：确定定制模式
+
+根据需求选择合适的定制模式：
+
+**模式A：新增规则**
+- 适用场景：创建全新的规则类型
+- 需要创建：DTO、扩展接口、默认实现
+
+**模式B：重写规则（@Primary）**
+- 适用场景：完全替换现有规则行为
+- 需要创建：定制实现类（使用@Primary注解）
+- 可选：扩展DTO字段
+
+**模式C：重写规则（Ordered）**
+- 适用场景：多个实现共存
+- 需要创建：定制实现类（实现Ordered接口）
+
+### 步骤2：理解规则结构
+
+了解：
+- 规则接口层次（RuleRechargeHandler → Extension → Implementation）
+- 规则DTO结构
+- 规则计算入参（RuleRechargeResultDTO、MarketRuleVO）
+- 规则计算流程
+- 常用工具类
+
+### 步骤3：参考实际案例
+
+查看实际案例，了解如何实现具体的定制需求。
+
+### 步骤4：实现规则定制
+
+#### 新增规则的实现步骤
+
+1. **创建规则DTO**
+   - 位置：`net.xnzn.core.marketing.v2.rule.recharge.handler.[ruletype].dto`
+   - 包含规则配置字段
+   - 实现 `toString()` 方法返回可读描述
+
+2. **创建扩展接口**
+   - 位置：`net.xnzn.core.marketing.v2.rule.recharge.handler.[ruletype].extension`
+   - 继承 `RuleRechargeHandler`
+   - 实现 `getRuleType()` 和 `checkRuleInfo()` 方法
+
+3. **创建默认实现**
+   - 位置：`net.xnzn.core.marketing.v2.rule.recharge.handler.[ruletype].extension.impl`
+   - 实现扩展接口
+   - 添加 `@Service` 注解
+   - 实现 `handle()` 方法
+
+4. **注册规则枚举**
+   - 在 `RuleRechargeEnum` 中添加新的规则类型
+
+#### 重写规则的实现步骤（@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 RuleRechargeHandler {
+    @Override
+    default Integer getRuleType() {
+        return RuleRechargeEnum.[RULE_TYPE_ENUM].getKey();
+    }
+
+    @Override
+    default void checkRuleInfo(String ruleInfo) {
+        [RuleType]DTO rule = JSON.parseObject(ruleInfo, [RuleType]DTO.class);
+        // 添加必要的校验逻辑
+    }
+}
+
+// 3. 默认实现
+@Slf4j
+@Service
+public class Default[RuleType]HandlerImpl implements [RuleType]HandlerExtension {
+
+    @Override
+    public void handle(RuleRechargeResultDTO resultDTO, MarketRuleVO rule) {
+        // 1. 解析规则配置
+        [RuleType]DTO ruleInfo = JSON.parseObject(rule.getRuleInfo(), [RuleType]DTO.class);
+
+        // 2. 实现规则计算逻辑
+        // ...
+
+        // 3. 更新充值金额或抛出异常
+        resultDTO.setActualAmount(resultDTO.getActualAmount().add(giftAmount));
+    }
+}
+```
+
+### 重写规则模板（@Primary）
+
+```java
+@Slf4j
+@Service
+@Primary  // 标记为主要实现
+public class Custom[RuleType]HandlerImpl extends Default[RuleType]HandlerImpl
+        implements [RuleType]HandlerExtension {
+
+    @Override
+    public void handle(RuleRechargeResultDTO resultDTO, MarketRuleVO rule) {
+        // 解析规则配置（可能包含扩展字段）
+        [RuleType]DTO ruleInfo = JSON.parseObject(rule.getRuleInfo(), [RuleType]DTO.class);
+
+        // 实现定制逻辑
+        // 可以调用父类方法：super.handle(resultDTO, rule);
+        // 或完全自定义实现
+    }
+}
+```
+
+## 常见规则类型
+
+### 优惠类规则
+- 满赠规则：`RechargeFullGiftHandlerExtension`
+- 按次数赠送：`RechargeTimesGiftHandlerExtension`
+
+### 限制类规则
+- 限额-单次金额：`RechargeMaxAmountHandlerExtension`
+- 限额-累计金额：`RechargeSumAmountHandlerExtension`
+
+### 其他费用规则
+- 管理费：`RechargeCostHandlerExtension`
+
+## 最佳实践
+
+### 包名规范
+- 覆盖核心类：使用核心工程的包名（`net.xnzn.core.marketing.v2.rule.recharge.handler.[ruletype]`）
+- 定制实现：使用项目特定包名（如 `net.xnzn.yunshitang.marketing.handler`）
+
+### 类名规范
+- 扩展接口：`[RuleType]HandlerExtension`
+- 默认实现：`Default[RuleType]HandlerImpl`
+- 定制实现：`Custom[RuleType]HandlerImpl` 或描述性名称
+
+### 注解使用
+- 所有实现类必须添加 `@Service` 注解
+- 重写规则使用 `@Primary` 注解（推荐）
+- 日志记录使用 `@Slf4j` 注解
+
+### 向后兼容
+- 扩展DTO字段时，新字段应支持null值
+- 新字段为null时应保持原有行为
+- 在toString方法中包含所有字段
+
+## 快速开始示例
+
+假设需要为满赠规则（`RechargeFullGiftHandlerExtension`）添加钱包类型选择功能：
+
+1. **扩展DTO**：在 `RechargeGiftFullDTO` 中添加 `walletTypes` 字段
+2. **创建定制实现**：创建 `CustomRechargeFullGiftHandlerImpl`，位于 `net.xnzn.yunshitang.marketing.handler`，使用 `@Primary` 注解
+3. **实现逻辑**：在 `handle()` 方法中使用 `walletTypes` 字段过滤钱包充值
+4. **向后兼容**：`walletTypes` 为null时适用所有钱包
+
+```java
+// 1. 扩展DTO（在核心工程包名下覆盖）
+// 位置：net.xnzn.core.marketing.v2.rule.recharge.handler.fullgift.dto.RechargeGiftFullDTO
+@Data
+@ApiModel("充值满赠规则详情")
+public class RechargeGiftFullDTO {
+    @ApiModelProperty("满足金额门槛（分）")
+    private BigDecimal fullAmount;
+
+    @ApiModelProperty("赠送金额（分）")
+    private BigDecimal giftAmount;
+
+    // 扩展字段：适用钱包类型，null时表示所有钱包
+    @ApiModelProperty("适用钱包类型列表（null=所有钱包）")
+    private List<Integer> walletTypes;
+
+    @Override
+    public String toString() {
+        return "fullAmount=" + fullAmount + ", giftAmount=" + giftAmount
+            + ", walletTypes=" + walletTypes;
+    }
+}
+
+// 2. 定制实现（在yunshitang项目包下）
+// 位置：net.xnzn.yunshitang.marketing.handler
+@Slf4j
+@Service
+@Primary
+public class CustomRechargeFullGiftHandlerImpl
+        implements RechargeFullGiftHandlerExtension {
+
+    @Override
+    public void handle(RuleRechargeResultDTO resultDTO, MarketRuleVO rule) {
+        RechargeGiftFullDTO ruleInfo = JSON.parseObject(
+            rule.getRuleInfo(), RechargeGiftFullDTO.class);
+
+        // 钱包类型过滤（向后兼容：null时不过滤）
+        if (CollUtil.isNotEmpty(ruleInfo.getWalletTypes())
+                && !ruleInfo.getWalletTypes().contains(resultDTO.getWalletType())) {
+            return; // 不在适用钱包范围内，跳过
+        }
+
+        // 满赠逻辑
+        if (resultDTO.getRechargeAmount().compareTo(ruleInfo.getFullAmount()) >= 0) {
+            resultDTO.setActualAmount(
+                resultDTO.getActualAmount().add(ruleInfo.getGiftAmount()));
+            log.info("满赠规则生效，赠送金额：{}", ruleInfo.getGiftAmount());
+        }
+    }
+}
+```
+
+## 参考文档
+
+详见：[leniu-tengyun-core 源码](/Users/xujiajun/Developer/gongsi_proj/core/leniu-tengyun-core)

package/src/skills/leniu-mealtime/SKILL.md

@@ -0,0 +1,215 @@
+---
+name: leniu-mealtime
+description: |
+  leniu-tengyun-core 项目餐次处理规范。当编写涉及餐次（早餐/午餐/下午茶/晚餐/夜宵）的报表或查询代码时使用。
+
+  触发场景：
+  - 在 Param 查询参数类中添加餐次筛选字段（mealtimeTypes）
+  - 在 VO 返回类中定义餐次字段和 MealtimeTypeConverter 转换器
+  - 编写 MyBatis XML 中的餐次 IN 查询条件
+  - 处理餐次枚举转换（AllocMealtimeTypeEnum）
+  - 区分正餐（早/午/晚）与非正餐（下午茶/夜宵）
+
+  适用项目：
+  - 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
+
+  触发词：餐次、mealtime、mealtimeType、早餐、午餐、晚餐、下午茶、夜宵、AllocMealtimeTypeEnum
+---
+
+# leniu-tengyun-core 餐次处理规范
+
+## 餐次枚举定义
+
+### AllocMealtimeTypeEnum
+
+餐次类型枚举 `AllocMealtimeTypeEnum` 定义了5种餐次：
+
+| 枚举值 | key | 显示名称 | 说明 |
+|--------|-----|----------|------|
+| MEALTIME_BREAKFAST | 1 | 早餐 | 早餐 |
+| MEALTIME_LUNCH | 2 | 午餐 | 午餐 |
+| MEALTIME_AFTERNOON_TEA | 3 | 下午茶 | 下午茶 |
+| MEALTIME_DINNER | 4 | 晚餐 | 晚餐 |
+| MEALTIME_MIDNIGHT_SNACK | 5 | 夜宵 | 夜宵 |
+
+### 常用方法
+
+```java
+// 根据key获取枚举
+AllocMealtimeTypeEnum typeEnum = AllocMealtimeTypeEnum.getTypeEnum(1);
+
+// 根据key获取显示名称
+String desc = AllocMealtimeTypeEnum.getValueByKey(1); // 返回 "早餐"
+
+// 获取所有餐次key列表
+List<Integer> allTypes = AllocMealtimeTypeEnum.allTypeList(); // [1, 2, 3, 4, 5]
+
+// 获取正餐类型列表
+List<Integer> normalTypes = AllocMealtimeTypeEnum.normalTypeList(); // [1, 2, 4]
+```
+
+### 餐次分类
+
+- **正餐**：早餐(1)、午餐(2)、晚餐(4)
+- **非正餐**：下午茶(3)、夜宵(5)
+
+## 查询参数中的餐次处理
+
+### Param类定义
+
+在报表查询Param类中添加餐次筛选字段：
+
+```java
+@ApiModelProperty(value = "餐次集合")
+private List<Integer> mealtimeTypes;
+```
+
+### 完整示例
+
+```java
+@Data
+@AllArgsConstructor
+@NoArgsConstructor
+@EqualsAndHashCode(callSuper = true)
+@ApiModel(value = "XXX查询入参")
+public class XxxParam extends ReportBaseParam {
+
+    @ApiModelProperty(value = "餐次集合")
+    private List<Integer> mealtimeTypes;
+
+    // 其他查询字段...
+}
+```
+
+## 返回VO中的餐次处理
+
+### VO字段定义
+
+在报表返回VO类中定义餐次字段：
+
+```java
+@Data
+@Accessors(chain = true)
+@ApiModel(value = "XXX报表")
+public class XxxVO {
+
+    @ExcelProperty(value = "餐次", order = 5, converter = MealtimeTypeConverter.class)
+    @ApiModelProperty(value = "餐次")
+    private Integer mealtimeType;
+
+    // 其他字段...
+}
+```
+
+### 必要的导入
+
+```java
+import com.alibaba.excel.annotation.ExcelProperty;
+import net.xnzn.core.common.export.converter.MealtimeTypeConverter;
+```
+
+### 字段说明
+
+- `mealtimeType`: 存储餐次的整数key值（1-5）
+- `@ExcelProperty`: 配置EasyExcel导出，使用`MealtimeTypeConverter`进行转换
+- `converter = MealtimeTypeConverter.class`: 自动将整数转换为可读的餐次名称
+
+## MyBatis XML中的餐次查询
+
+### 基本IN查询
+
+```xml
+<!-- 餐次筛选 -->
+<if test="mealtimeTypes != null and mealtimeTypes.size() > 0">
+    AND mealtime_type IN
+    <foreach collection="mealtimeTypes" item="type" open="(" separator="," close=")">
+        #{type}
+    </foreach>
+</if>
+```
+
+### 正餐筛选
+
+```xml
+<!-- 仅查询正餐（早餐、午餐、晚餐） -->
+AND mealtime_type IN (1, 2, 4)
+```
+
+### 完整示例
+
+```xml
+<select id="pageXxx" resultType="net.xnzn.core.xxx.vo.XxxVO">
+    SELECT
+        id,
+        order_date,
+        mealtime_type,
+        cust_name,
+        real_amount
+    FROM order_table
+    WHERE del_flag = 2
+    <if test="startDate != null">
+        AND order_date >= #{startDate}
+    </if>
+    <if test="endDate != null">
+        AND order_date &lt;= #{endDate}
+    </if>
+    <if test="mealtimeTypes != null and mealtimeTypes.size() > 0">
+        AND mealtime_type IN
+        <foreach collection="mealtimeTypes" item="type" open="(" separator="," close=")">
+            #{type}
+        </foreach>
+    </if>
+    <if test="canteenId != null">
+        AND canteen_id = #{canteenId}
+    </if>
+    ORDER BY order_date DESC
+</select>
+```
+
+## 常见使用场景
+
+### 场景1：查询指定餐次的订单
+
+```java
+// Param定义
+@ApiModelProperty(value = "餐次集合")
+private List<Integer> mealtimeTypes;
+
+// Service调用
+List<Integer> mealtimeTypes = Arrays.asList(1, 2); // 查询早餐和午餐
+param.setMealtimeTypes(mealtimeTypes);
+```
+
+### 场景2：仅查询正餐
+
+```java
+// 方式1：直接在XML中硬编码
+AND mealtime_type IN (1, 2, 4)
+
+// 方式2：使用枚举工具类
+param.setMealtimeTypes(AllocMealtimeTypeEnum.normalTypeList());
+```
+
+### 场景3：导出时餐次列显示中文名称
+
+```java
+// VO定义
+@ExcelProperty(value = "餐次", order = 5, converter = MealtimeTypeConverter.class)
+@ApiModelProperty(value = "餐次")
+private Integer mealtimeType;
+
+// 导出时自动转换：1 -> "早餐"，2 -> "午餐" 等
+```
+
+## 注意事项
+
+1. **字段命名**：统一使用 `mealtimeType` (驼峰) 或 `mealtime_type` (下划线)
+2. **类型**：数据库和Java代码中均使用 `Integer` 类型
+3. **转换器**：导出时必须使用 `MealtimeTypeConverter` 进行转换
+4. **国际化的影响**：显示名称根据项目配置可能使用中文或国际化key
+5. **正餐判断**：需要区分正餐时使用 `AllocMealtimeTypeEnum.normalTypeList()` 方法
+
+## 参考文档
+
+详见：[leniu-tengyun-core 源码](/Users/xujiajun/Developer/gongsi_proj/core/leniu-tengyun-core)