leniu-marketing-recharge-rule-customizer

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：实现规则定制

新增规则的实现步骤

创建规则DTO

位置：net.xnzn.core.marketing.v2.rule.recharge.handler.[ruletype].dto
包含规则配置字段
实现 toString() 方法返回可读描述

创建扩展接口

位置：net.xnzn.core.marketing.v2.rule.recharge.handler.[ruletype].extension
继承 RuleRechargeHandler
实现 getRuleType() 和 checkRuleInfo() 方法

创建默认实现

位置：net.xnzn.core.marketing.v2.rule.recharge.handler.[ruletype].extension.impl
实现扩展接口
添加 @Service 注解
实现 handle() 方法

注册规则枚举

在 RuleRechargeEnum 中添加新的规则类型

重写规则的实现步骤（@Primary模式）

（可选）扩展DTO字段

在定制项目中覆盖核心DTO类
添加新字段并保持向后兼容

创建定制实现

位置：定制项目包（如 net.xnzn.yunshitang.marketing.handler ）
继承默认实现类（可选，用于复用逻辑）
实现扩展接口
添加 @Service 和 @Primary 注解
重写 handle() 方法

实现定制逻辑

解析规则配置（包含新字段）
实现自定义计算逻辑
更新充值金额或抛出限制异常

步骤5：测试规则

测试向后兼容性（新字段为null的场景）
测试新功能（新字段有值的场景）
测试边界条件
测试与其他规则的组合使用

代码模板

新增规则模板

// 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）

@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 ）添加钱包类型选择功能：

扩展DTO：在 RechargeGiftFullDTO 中添加 walletTypes 字段
创建定制实现：创建 CustomRechargeFullGiftHandlerImpl ，位于 net.xnzn.yunshitang.marketing.handler ，使用 @Primary 注解
实现逻辑：在 handle() 方法中使用 walletTypes 字段过滤钱包充值
向后兼容：walletTypes 为null时适用所有钱包

// 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&#x3C;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())
            &#x26;&#x26; !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 源码

leniu-marketing-recharge-rule-customizer

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

loki-log-query

scheduled-jobs

brainstorm

openspec-ff-change