ai-engineering-init 1.14.3 → 1.16.0

package/.claude/skills/leniu-marketing-scenario/references/price-rules.md

@@ -0,0 +1,286 @@
+# 计价规则详解（RulePriceEnum）
+
+## 规则执行顺序
+
+```
+限次规则 → 优惠规则 → 限额规则 → 赠送规则
+```
+
+由 `RulePriceTypeDTO` 自动分类，`RulePriceResultOrderDTO` 链式调用：
+```java
+order.calcLimitTimesRules(...)
+     .calcDiscountRules(...)
+     .calcLimitAmountRules(...)
+     .calcGiveRules(...)
+     .calcCompleted();
+```
+
+## 分类判断方法
+
+```java
+RulePriceEnum.isDiscountRule(key);    // 优惠类
+RulePriceEnum.isLimitTimesRule(key);  // 限次类
+RulePriceEnum.isLimitAmountRule(key); // 限额类
+RulePriceEnum.isGiveRule(key);        // 赠送类
+RulePriceEnum.isDishRule(key);        // 菜品类
+RulePriceEnum.isGoodsRule(key);       // 商品类
+```
+
+---
+
+## 优惠类规则
+
+### 1. 打折（RULE_DISCOUNT, key=1）
+
+按消费次数梯度打折。第 N 次消费使用第 N 个折扣率。
+
+```java
+// DTO
+public class PriceDiscountDTO {
+    private List<BigDecimal> items;       // 折扣率列表 [0.9, 0.8, 0.7]（第1次9折，第2次8折...）
+    private BigDecimal joinAmount;         // 参与计算上限金额（null=不限）
+    private BigDecimal maxAmount;          // 单次优惠/浮动上限金额
+}
+// Handler 路径
+rule.price.handler.discount.extension.impl.DefaultPriceDiscountHandlerImpl
+```
+
+### 2. 累计减免（RULE_REDUCTION_TOTAL, key=2）
+
+```java
+// DTO
+public class PriceReductionTotalDTO {
+    private BigDecimal maxAmount;    // 最大累计减免金额
+}
+// Handler 路径
+rule.price.handler.reductiontotal.extension.impl.DefaultReductionTotalHandlerImpl
+```
+
+### 3. 固定减免（RULE_REDUCTION_FIXED, key=4）
+
+按消费次数梯度减免固定金额。
+
+```java
+// DTO
+public class PriceReductionFixedDTO {
+    private List<BigDecimal> items;  // 减免金额列表 [500, 300, 100]
+}
+// Handler 路径
+rule.price.handler.reductionfixed.extension.impl.DefaultReductionFixedHandlerImpl
+```
+
+### 4. 比例扣费（RULE_DEDUCTION_RATIO, key=5）
+
+个人钱包扣 X%，补贴钱包扣 Y%，补贴上限 Z 元。
+
+```java
+// DTO
+public class PriceDeductionRatioDTO {
+    private BigDecimal personalRatio;    // 个人钱包扣费比例
+    private BigDecimal subsidyRatio;     // 补贴钱包扣费比例
+    private BigDecimal subsidyMaxAmount; // 补贴上限金额
+}
+// Handler 路径
+rule.price.handler.deductionratio.extension.impl.DefaultDeductionRatioHandlerImpl
+```
+
+### 5. 固定扣费（RULE_DEDUCTION_FIXED, key=6）
+
+按消费次数梯度固定扣费，可额外优惠。
+
+```java
+// DTO
+public class PriceDeductionFixedDTO {
+    private List<PriceDeductionFixedItemDTO> items;  // 含 amount + extraDiscount
+}
+// Handler 路径
+rule.price.handler.deductionfixed.extension.impl.DefaultPriceDeDuctionFixedHandlerImpl
+```
+
+### 6. 满减满折（RULE_DEDUCTION_FULL, key=7）
+
+满 X 元减 Y 元或打 Z 折，可限制享受次数。
+
+```java
+// DTO
+public class PriceDeductionFullDTO {
+    private List<PriceDeductionFullItemDTO> items;  // 含 fullAmount + discountType + discountValue + maxTimes
+}
+// Handler 路径
+rule.price.handler.deductionfull.extension.impl.DefaultPriceDeDuctionFullHandlerImpl
+```
+
+### 7. 额外扣费（RULE_ADD_AMOUNT, key=9）
+
+每笔消费额外扣费固定金额。
+
+```java
+// DTO
+public class PriceAddAmountDTO {
+    private BigDecimal addAmount;  // 额外扣费金额
+}
+// Handler 路径
+rule.price.handler.addamount.extension.impl.DefaultPriceAddAmountHandlerImpl
+```
+
+---
+
+## 赠送类规则
+
+### 8. 固定补贴（RULE_SUBSIDY_FIXED, key=3）
+
+每笔消费后补贴固定金额到指定钱包。
+
+```java
+// DTO
+public class PriceSubsidyFixedDTO {
+    private BigDecimal subsidyAmount;  // 补贴金额
+}
+// Handler 路径
+rule.price.handler.subsidyfixed.extension.impl.DefaultSubsidyFixedHandlerImpl
+```
+
+### 9. 满额赠送（RULE_SUM_GIVE, key=8）
+
+累计消费达到门槛金额后赠送。
+
+```java
+// DTO
+public class PriceSumGiveDTO {
+    private List<PriceSumGiveItem> items;  // 含 gateAmount + giveAmount
+}
+// Handler 路径
+rule.price.handler.sumgive.extension.impl.DefaultSumGiveHandlerImpl
+// MQ 异步处理
+config.MarketSumGiveMQListener
+```
+
+---
+
+## 限次类规则
+
+### 10. 上限次数（RULE_LIMIT_MAX_COUNT, key=51）
+
+日/周/月/餐次累计消费次数上限。
+
+```java
+// DTO
+public class PriceLimitMaxCountDTO {
+    private Integer limitType;       // 限制周期（日/周/月/季/半年/年/餐次）
+    private Integer maxCount;        // 上限次数
+    private List<Integer> mealtimeTypes; // 适用餐次
+}
+// Handler 路径
+rule.price.handler.limitmaxcount.extension.impl.DefaultLimitMaxCountHandlerImpl
+```
+
+### 11. 菜品限购（RULE_DISH_LIMIT, key=201）
+
+```java
+// DTO
+public class PriceDishLimitDTO {
+    private Integer dishIdType;     // 按菜品/按菜品类别
+    private List<Long> dishIds;     // 菜品或类别ID列表
+    private Integer limitCount;     // 限购数量
+}
+// Handler 路径
+rule.price.handler.dishlimit.extension.impl.DefaultPriceDishLimitHandlerImpl
+```
+
+### 12. 商品限购（RULE_GOODS_LIMIT, key=301）
+
+```java
+// DTO 结构同 PriceDishLimitDTO
+// Handler 路径
+rule.price.handler.goodslimit.extension.impl.DefaultPriceGoodsLimitHandlerImpl
+```
+
+---
+
+## 限额类规则
+
+### 13. 单笔上限金额（RULE_LIMIT_MAX_AMOUNT, key=101）
+
+```java
+// DTO
+public class PriceLimitMaxAmountDTO {
+    private BigDecimal maxAmount;  // 单笔上限
+}
+// Handler 路径
+rule.price.handler.limitmaxamount.extension.impl.DefaultLimitMaxAmountHandlerImpl
+```
+
+### 14. 累计上限金额（RULE_LIMIT_SUM_AMOUNT, key=102）
+
+```java
+// DTO
+public class PriceLimitSumAmountDTO {
+    private Integer limitType;          // 限制周期
+    private BigDecimal limitAmount;     // 累计上限
+    private List<Integer> mealtimeTypes;
+}
+// Handler 路径
+rule.price.handler.limitsumamount.extension.impl.DefaultPriceLimitSumAmountHandlerImpl
+```
+
+---
+
+## 菜品/商品类规则
+
+### 15-16. 菜品打折 / 菜品打折限购（key=151, 152）
+
+```java
+// PriceDishDiscountDTO / PriceDishDiscountLimitDTO
+// 按菜品或类别维度设置折扣，可限制折扣份数
+rule.price.handler.dishdiscount / dishdiscountlimit
+```
+
+### 17. 套餐优惠（RULE_DISH_PACKAGE, key=153）
+
+按菜品套餐组合计价。
+
+### 18-19. 商品打折 / 商品打折限购（key=251, 252）
+
+```java
+// PriceGoodsDiscountDTO / PriceGoodsDiscountLimitDTO
+rule.price.handler.goodsdiscount / goodsdiscountlimit
+```
+
+---
+
+## 限制周期枚举 RulePriceLimitEnum
+
+| 枚举 | key | 说明 |
+|------|-----|------|
+| LIMIT_DAY | 1 | 按日 |
+| LIMIT_WEEK | 2 | 按周 |
+| LIMIT_MONTH | 3 | 按月 |
+| LIMIT_QUARTER | 4 | 按季 |
+| LIMIT_HALF | 5 | 按半年 |
+| LIMIT_YEAR | 6 | 按年 |
+| LIMIT_MEALTIME | 7 | 按餐次 |
+
+## 菜品维度枚举 RulePriceDishIdTypeEnum
+
+| 枚举 | key | 说明 |
+|------|-----|------|
+| DISH_NAME | 1 | 按菜品/商品名称 |
+| DISH_TYPE | 2 | 按菜品/商品类别 |
+
+---
+
+## 关键工具方法（MarketUtil）
+
+```java
+// 查询历史订单（用于限次/限额/累计计算）
+MarketUtil.getOrders(order, limitType, mealtimeTypeList, sceneType);
+
+// 查询当前交易中符合规则的订单（用于批量订单场景）
+MarketUtil.getNowTrade(order, mealtimeTypeList, customDeviceList, limitType, orderResults);
+
+// 格式化设备SN（用于规则匹配）
+MarketUtil.formatDeviceSn(orderType, canteenId, stallId, deviceSn);
+
+// 统计菜品数量
+MarketUtil.countDish(details, dishIds, dishFlag);
+```

package/.claude/skills/leniu-marketing-scenario/references/recharge-rules.md

@@ -0,0 +1,188 @@
+# 充值规则详解（RuleRechargeEnum）
+
+## 规则执行顺序
+
+```
+限额规则 → 赠送规则 → 管理费规则
+```
+
+由 `RuleRechargeTypeDTO` 自动分类，`RuleRechargeResultDTO` 链式调用：
+```java
+recharge.calcLimitAmountRules(ruleRechargeType.getLimitAmountRules(), recordDTO, this::handle)
+        .calcDiscountRules(ruleRechargeType.getDiscountRules(), recordDTO, this::handle)
+        .calcOtherFeeRules(ruleRechargeType.getOtherFeeRules(), recordDTO, this::handle);
+```
+
+## 分类判断方法
+
+```java
+RuleRechargeEnum.isDiscountRule(key);     // 赠送类（满赠/按次赠送）
+RuleRechargeEnum.isLimitAmountRule(key);  // 限额类
+RuleRechargeEnum.isOtherFeeRule(key);     // 其他费用类（管理费）
+```
+
+---
+
+## 赠送类规则
+
+### 1. 满赠（RULE_FULL_GIFT, key=1）
+
+充值金额达到门槛后赠送。支持多档梯度。
+
+```java
+// DTO
+public class RechargeGiftFullDTO {
+    private List<RechargeGiftFullItemDTO> items;
+}
+public class RechargeGiftFullItemDTO {
+    private BigDecimal fullAmount;    // 满足门槛金额
+    private BigDecimal giftAmount;    // 赠送金额
+}
+
+// Handler 路径
+rule.recharge.handler.fullgift.extension.impl.DefaultRechargeFullGiftHandlerImpl
+```
+
+### 2. 按次数赠送（RULE_TIMES_GIFT, key=2）
+
+按充值次数梯度赠送不同金额。
+
+```java
+// DTO
+public class RechargeTimesGiftDTO {
+    private List<RechargeTimesGiftItemDTO> items;
+}
+public class RechargeTimesGiftItemDTO {
+    private Integer times;           // 第 N 次充值
+    private BigDecimal giftAmount;   // 赠送金额
+}
+
+// Handler 路径
+rule.recharge.handler.timesgift.extension.impl.DefaultRechargeTimesGiftHandlerImpl
+```
+
+---
+
+## 限额类规则
+
+### 3. 单笔上限金额（RULE_MAX_AMOUNT, key=51）
+
+单次充值金额不得超过上限。
+
+```java
+// DTO
+public class RechargeMaxAmountDTO {
+    private BigDecimal maxAmount;    // 单笔上限
+}
+
+// Handler 路径
+rule.recharge.handler.maxamount.extension.impl.DefaultRechargeMaxAmountHandlerImpl
+```
+
+### 4. 累计上限金额（RULE_SUM_AMOUNT, key=52）
+
+一定周期内累计充值不得超过上限。
+
+```java
+// DTO
+public class RechargeSumAmountDTO {
+    private Integer limitType;          // 限制周期（同 RulePriceLimitEnum）
+    private BigDecimal limitAmount;     // 累计上限
+}
+
+// Handler 路径
+rule.recharge.handler.sumamount.extension.impl.DefaultRechargeSumAmountHandlerImpl
+```
+
+---
+
+## 费用类规则
+
+### 5. 管理费（RULE_MANAGE_COST, key=101）
+
+充值时按比例或固定金额收取管理费。
+
+```java
+// DTO
+public class RechargeCostDTO {
+    private List<RechargeCostItemDTO> items;
+}
+public class RechargeCostItemDTO {
+    private Integer costType;         // 1=固定金额, 2=比例
+    private BigDecimal costValue;     // 金额或比例值
+}
+
+// Handler 路径
+rule.recharge.handler.managecost.extension.impl.DefaultRechargeCostHandlerImpl
+```
+
+---
+
+## 充值规则 Handler 接口
+
+```java
+public interface RuleRechargeHandler {
+    void handle(RuleRechargeResultDTO resultDTO, MarketRuleVO ruleInfo);
+    Integer getRuleType();
+    default void checkRuleInfo(String ruleInfo) {}
+}
+```
+
+### RuleRechargeResultDTO 关键字段
+
+| 字段 | 说明 |
+|------|------|
+| rechargeAmount | 充值金额 |
+| actualAmount | 实际到账金额（含赠送） |
+| giftAmount | 赠送金额 |
+| costAmount | 管理费金额 |
+| walletDetails | 钱包明细 |
+| ruleRecord | 规则计算记录 |
+
+### RuleRechargeComputeDTO 关键字段
+
+| 字段 | 说明 |
+|------|------|
+| custId | 人员ID |
+| rechargeAmount | 充值金额 |
+| walletType | 钱包类型 |
+| tryFlag | 试算标志（1=试算，不记录） |
+
+---
+
+## 充值规则定制示例
+
+### 为满赠规则添加钱包类型过滤
+
+```java
+// 1. 扩展 DTO（核心包名下覆盖）
+@Data
+public class RechargeGiftFullDTO {
+    private List<RechargeGiftFullItemDTO> items;
+    // 扩展字段
+    @ApiModelProperty("适用钱包类型（null=所有钱包）")
+    private List<Integer> walletTypes;
+}
+
+// 2. 定制实现（定制项目包名）
+@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;
+        }
+
+        // 满赠逻辑...
+    }
+}
+```