Sfoglia il codice sorgente

feat(product-recommendation): 实现商品推荐规则引擎 RecommendationRuleEngine

补齐设计文档 specs/2026-09-17-product-recommendation-rule-engine-design.md
检测差距项:新增 service/RecommendationRuleEngine(5 种规则统一计算入口)、
dto/RecommendationEngineContext、dto/RecommendedProduct,并附单元测试。

- 规则1 已购不推 / 规则2 定时复购 / 规则3 购买A推B / 规则4 购买A不推B / 规则5 系列重点推
- priority DESC,同优先级剔除类(4,1)先于注入类(3,5,2);removed 集合保证剔除优先
- 场景基础候选构建 + 默认90天已购全局剔除 + 用户排除
- 降级:规则表为空/异常不抛出,退化为基础候选
- 单元测试 23 例(5 规则命中/未命中、优先级排序、scope、time_window 边界、降级、limit、scene_codes、全局排除、toMap)

另修复 cfclub HEAD 两个预先存在的红构建硬错误(否则模块无法编译):
- TongueRecord 重复 memberId 字段与访问器
- CouponController 变量重复声明

测试:JAVA_HOME=jdk8 mvn test -Dtest=RecommendationRuleEngineTest -DskipTests=false → 23/23 通过
编译:JAVA_HOME=jdk8 mvn clean compile -DskipTests → BUILD SUCCESS
Sisyphus 2 settimane fa
parent
commit
2aa3196c2a

+ 2 - 2
cfc-backend/src/main/java/com/etotem/cfc/controller/CouponController.java

@@ -56,8 +56,8 @@ public class CouponController {
     public Result<Map<String, Object>> exchange(@RequestAttribute("userId") Long userId,
                                                 @RequestBody Map<String, Object> params) {
         Long couponId = ParamUtils.getLong(params.get("couponId"));
-        Object memberId = params.get("memberId");
-        Long memberId = memberId != null ? Long.valueOf(memberId.toString()) : null;
+        Object memberIdObj = params.get("memberId");
+        Long memberId = memberIdObj != null ? Long.valueOf(memberIdObj.toString()) : null;
         PointsExchangeRecord record = pointsExchangeService.exchangeCoupon(userId, memberId, couponId);
         return Result.success(java.util.Collections.singletonMap("recordId", record.getId()));
     }

+ 50 - 0
cfc-backend/src/main/java/com/etotem/cfc/dto/RecommendationEngineContext.java

@@ -0,0 +1,50 @@
+package com.etotem.cfc.dto;
+
+import java.io.Serializable;
+import java.util.List;
+import lombok.Data;
+
+/**
+ * 推荐上下文(商品推荐规则引擎输入)。
+ *
+ * <p>字段口径见设计文档
+ * docs/superpowers/specs/2026-09-17-product-recommendation-rule-engine-design.md 第 4.1 节。
+ *
+ * <p>命名说明:设计文档中的上下文类名为 RecommendationContext,但该名称已被饮食推荐链路
+ * (MealRecommendService/MealRecommendController)占用,且字段语义完全不同(预算/口味/禁忌/候选食谱)。
+ * 为避免破坏既有调用方,规则引擎上下文独立命名为 RecommendationEngineContext,与引擎类
+ * RecommendationRuleEngine 配对使用。
+ */
+@Data
+public class RecommendationEngineContext implements Serializable {
+
+    /** 登录用户ID */
+    private Long userId;
+
+    /** 家庭ID(scope=family 时必填) */
+    private Long familyId;
+
+    /** 成员ID(scope=individual 时) */
+    private Long memberId;
+
+    /** 生效场景代码:dimension_page/mall_home/product_detail/after_order/report_related */
+    private String scene;
+
+    /** 商品详情页/下单页的当前商品ID(product_detail 场景) */
+    private Long currentProductId;
+
+    /** 用户自行排除的商品ID(如已选/不喜欢) */
+    private List<Long> excludeProductIds;
+
+    /** 返回上限,默认6 */
+    private Integer limit;
+
+    /** 购买范围:family/individual,默认 family */
+    private String scope;
+
+    /** 维度编码(dimension_page 场景:body/wisdom/mind/action/wealth) */
+    private String dimensionCode;
+
+    /** 报告分析结果(report_related 场景,用于提取弱维度,可为 null) */
+    private Object analysis;
+}

+ 73 - 0
cfc-backend/src/main/java/com/etotem/cfc/dto/RecommendedProduct.java

@@ -0,0 +1,73 @@
+package com.etotem.cfc.dto;
+
+import java.io.Serializable;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import lombok.Data;
+
+/**
+ * 推荐结果项(商品推荐规则引擎输出)。
+ *
+ * <p>字段口径见设计文档
+ * docs/superpowers/specs/2026-09-17-product-recommendation-rule-engine-design.md 第 4.1 节。
+ *
+ * <p>说明:本类为规则引擎专用结果模型,与已存在的 {@link RecommendationResult}(全站搜索推荐)
+ * 用途不同、字段不同,故独立定义,避免混用导致字段冲突。
+ */
+@Data
+public class RecommendedProduct implements Serializable {
+
+    /** 商品ID */
+    private Long productId;
+
+    /** 商品名称 */
+    private String name;
+
+    /** 封面图 */
+    private String coverImage;
+
+    /** 价格(分) */
+    private Integer price;
+
+    /** 推荐理由 */
+    private String reason;
+
+    /** 匹配分(0-1),排序用 */
+    private Double matchScore;
+
+    /** 触发该结果的规则ID */
+    private Integer ruleId;
+
+    /** 规则类型:1-已购不推,2-定时复购,3-购买A推B,4-购买A不推B,5-系列重点推 */
+    private Integer ruleType;
+
+    /** 命中规则的优先级 */
+    private Integer priority;
+
+    /** 来源标识:engine/campaign/... */
+    private String source;
+
+    /** 前端跳转地址 */
+    private String url;
+
+    /**
+     * 映射为前端兼容的 Map 结构(与现有维度页推荐返回的 item 字段保持一致),
+     * 便于接口层不改签名、直接透传引擎结果。
+     */
+    public Map<String, Object> toMap() {
+        Map<String, Object> map = new LinkedHashMap<>();
+        map.put("id", productId);
+        map.put("productId", productId);
+        map.put("name", name);
+        map.put("coverImage", coverImage);
+        map.put("price", price);
+        map.put("reason", reason);
+        map.put("matchScore", matchScore);
+        map.put("ruleId", ruleId);
+        map.put("ruleType", ruleType);
+        map.put("priority", priority);
+        map.put("source", source);
+        map.put("url", url);
+        return map;
+    }
+}

+ 0 - 4
cfc-backend/src/main/java/com/etotem/cfc/entity/TongueRecord.java

@@ -11,8 +11,6 @@ import java.util.Date;
 public class TongueRecord {
     @TableId(type = IdType.AUTO)
     private Long id;
-    @JsonProperty("childId")
-    private Long memberId;
     @TableField("child_id")
     @JsonProperty("childId")
     private Long memberId;
@@ -26,8 +24,6 @@ public class TongueRecord {
     public void setId(Long id) { this.id = id; }
     public Long getMemberId() { return memberId; }
     public void setMemberId(Long memberId) { this.memberId = memberId; }
-    public Long getMemberId() { return memberId; }
-    public void setMemberId(Long memberId) { this.memberId = memberId; }
     public String getImageUrl() { return imageUrl; }
     public void setImageUrl(String imageUrl) { this.imageUrl = imageUrl; }
     public String getOverallAssessment() { return overallAssessment; }

+ 820 - 0
cfc-backend/src/main/java/com/etotem/cfc/service/RecommendationRuleEngine.java

@@ -0,0 +1,820 @@
+package com.etotem.cfc.service;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.etotem.cfc.dto.RecommendationEngineContext;
+import com.etotem.cfc.dto.RecommendedProduct;
+import com.etotem.cfc.entity.Product;
+import com.etotem.cfc.entity.ProductDimensionMapping;
+import com.etotem.cfc.entity.ProductOrder;
+import com.etotem.cfc.entity.RecommendationRule;
+import com.etotem.cfc.mapper.ProductDimensionMappingMapper;
+import com.etotem.cfc.mapper.ProductMapper;
+import com.etotem.cfc.mapper.ProductOrderMapper;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+
+import javax.annotation.Resource;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Calendar;
+import java.util.Collections;
+import java.util.Comparator;
+import java.util.Date;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.stream.Collectors;
+
+/**
+ * 商品推荐规则引擎。
+ *
+ * <p>实现设计文档 docs/superpowers/specs/2026-09-17-product-recommendation-rule-engine-design.md 第 4 节
+ * 中的统一计算逻辑:按配置表 recommendation_rules 与 priority 降序依次应用 5 种业务规则
+ *(已购不推 / 定时复购 / 购买A推B / 购买A不推B / 系列重点推),输出 {@link RecommendedProduct} 列表。
+ *
+ * <p>设计原则:
+ * <ul>
+ *   <li>统一入口:推荐结果的计算只在此类完成,Controller/Service 不应重复写规则逻辑。</li>
+ *   <li>降级兼容:规则表为空、规则加载失败或某条规则异常时,均不抛出异常,退化为基础候选。</li>
+ *   <li>剔除优先:规则 1/4(排除类)在规则 2/3/5(注入类)之前应用,同优先级下按文档 4.1~4.5
+ *       顺序处理,更高优先级规则更先控制结果。</li>
+ * </ul>
+ */
+@Slf4j
+@Service
+public class RecommendationRuleEngine {
+
+    /** 场景代码:维度页 */
+    public static final String SCENE_DIMENSION_PAGE = "dimension_page";
+
+    /** 场景代码:商城首页 */
+    public static final String SCENE_MALL_HOME = "mall_home";
+
+    /** 场景代码:商品详情页(规则驱动) */
+    public static final String SCENE_PRODUCT_DETAIL = "product_detail";
+
+    /** 场景代码:下单成功页(规则驱动) */
+    public static final String SCENE_AFTER_ORDER = "after_order";
+
+    /** 场景代码:报告关联(弱维度商品) */
+    public static final String SCENE_REPORT_RELATED = "report_related";
+
+    /** 全局默认已购排除回溯窗口(天),90 天 */
+    public static final int DEFAULT_PURCHASED_EXCLUDE_DAYS = 90;
+
+    /** 默认复购延迟天数(规则 2),30 天 */
+    public static final int DEFAULT_DELAY_DAYS = 30;
+
+    /** 默认返回上限 */
+    public static final int DEFAULT_LIMIT = 6;
+
+    /** 规则 5(系列重点推)对目标商品的优先级加成 */
+    public static final int SERIES_PRIORITY_BOOST = 10;
+
+    /** 基础候选池商品的默认匹配分 */
+    private static final double BASE_MATCH_SCORE = 0.5;
+
+    /** 规则注入商品的默认匹配分 */
+    private static final double RULE_MATCH_SCORE = 0.8;
+
+    /** 已支付订单状态,与商城下单校验口径一致 */
+    private static final List<String> PAID_STATUSES = Collections.unmodifiableList(
+            Arrays.asList("paid", "pending_receipt", "shipped", "completed"));
+
+    /** 规则同优先级下的处理顺序:剔除类规则先于注入类规则(文档 4.1~4.5) */
+    private static final Comparator<RecommendationRule> RULE_PRIORITY_COMPARATOR = (a, b) -> {
+        int cmp = Integer.compare(priorityOf(b), priorityOf(a)); // priority DESC
+        if (cmp != 0) {
+            return cmp;
+        }
+        int orderA = ruleLoopOrder(a.getRuleType());
+        int orderB = ruleLoopOrder(b.getRuleType());
+        if (orderA != orderB) {
+            return Integer.compare(orderA, orderB);
+        }
+        return Long.compare(ruleIdOf(a), ruleIdOf(b));
+    };
+
+    @Resource
+    private RecommendationRuleService recommendationRuleService;
+
+    @Resource
+    private ProductMapper productMapper;
+
+    @Resource
+    private ProductDimensionMappingMapper dimensionMappingMapper;
+
+    @Resource
+    private ProductOrderMapper orderMapper;
+
+    /**
+     * 计算推荐(引擎核心入口)。
+     *
+     * @param ctx 推荐上下文
+     * @param limit 若覆盖默认 limit,可传;否则用 ctx.limit
+     * @return 推荐列表(已按 priority DESC / matchScore DESC 排序并截断)
+     */
+    public List<RecommendedProduct> recommend(RecommendationEngineContext ctx, Integer limit) {
+        if (ctx == null) {
+            log.warn("推荐引擎上下文为空,返回空结果");
+            return Collections.emptyList();
+        }
+
+        int finalLimit = limit != null && limit > 0 ? limit
+                : (ctx.getLimit() != null && ctx.getLimit() > 0 ? ctx.getLimit() : DEFAULT_LIMIT);
+        String scene = ctx.getScene() == null || ctx.getScene().trim().isEmpty()
+                ? SCENE_MALL_HOME : ctx.getScene().trim();
+
+        // 1. 加载规则:enabled=1 且 scene_codes 命中指定场景,按 priority DESC 排序(文档 4.2 步骤1)
+        List<RecommendationRule> rules = loadRules(scene);
+
+        // 2. 查购买记录:family/individual 两个视角(文档 4.2 步骤2)
+        PurchaseView purchases = loadPurchases(ctx);
+        Map<Long, Date> globalPurchases = globalPurchasesView(ctx, purchases);
+
+        // 3. 构建场景基础候选(进入规则前已剔除默认窗口内已购商品 + 用户排除商品,文档 4.4)
+        List<RecommendedProduct> pool = buildBaseCandidates(ctx, scene, globalPurchases);
+
+        // 4. 按 priority 从高到低应用规则(文档 4.2 步骤4)
+        applyRules(rules, purchases, pool);
+
+        // 5. 结果排序(priority DESC, matchScore DESC)并截断 limit(文档 4.2 步骤5~6)
+        return sortAndTruncate(pool, finalLimit);
+    }
+
+    /**
+     * 不传 limit 的便捷入口,使用 ctx.limit。
+     */
+    public List<RecommendedProduct> recommend(RecommendationEngineContext ctx) {
+        return recommend(ctx, null);
+    }
+
+    // -----------------------------------------------------------------------
+    // 步骤1:加载规则
+    // -----------------------------------------------------------------------
+
+    private List<RecommendationRule> loadRules(String scene) {
+        try {
+            List<RecommendationRule> all = recommendationRuleService.list(
+                    new LambdaQueryWrapper<RecommendationRule>().eq(RecommendationRule::getEnabled, 1));
+            if (all == null || all.isEmpty()) {
+                log.info("推荐规则表为空,使用基础候选(降级,文档 7.1)");
+                return Collections.emptyList();
+            }
+            return all.stream()
+                    .filter(r -> matchesScene(r, scene))
+                    .sorted(RULE_PRIORITY_COMPARATOR)
+                    .collect(Collectors.toList());
+        } catch (Exception e) {
+            log.warn("加载推荐规则失败,降级为基础候选:{}", e.getMessage());
+            return Collections.emptyList();
+        }
+    }
+
+    /**
+     * 场景匹配(文档 7.4):
+     * <ul>
+     *   <li>scene_codes 为 null / 空字符串 / 空数组,视为“所有场景生效”;</li>
+     *   <li>优先精确匹配 sceneCode;</li>
+     *   <li>否则再尝试前缀匹配(如 sceneCode 为 dimension_page,scene_codes 包含 dimension 也视为命中);</li>
+     * </ul>
+     */
+    private boolean matchesScene(RecommendationRule rule, String scene) {
+        String sceneCodes = rule.getSceneCodes();
+        if (sceneCodes == null) {
+            return true;
+        }
+        String trimmed = sceneCodes.trim();
+        if (trimmed.isEmpty() || "\"\"".equals(trimmed) || "[]".equals(trimmed)) {
+            return true;
+        }
+        if (scene == null || scene.isEmpty()) {
+            return true;
+        }
+        for (String code : parseStringArray(trimmed)) {
+            if (code.isEmpty()) {
+                continue;
+            }
+            if (code.equals(scene)) {
+                return true;
+            }
+            // 前缀匹配兜底(文档 7.4)
+            if (scene.startsWith(code)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    // -----------------------------------------------------------------------
+    // 步骤2:查购买记录
+    // -----------------------------------------------------------------------
+
+    private static class PurchaseView {
+        final Map<Long, Date> family = new HashMap<>();
+        final Map<Long, Date> individual = new HashMap<>();
+    }
+
+    private PurchaseView loadPurchases(RecommendationEngineContext ctx) {
+        PurchaseView view = new PurchaseView();
+
+        if (ctx.getFamilyId() != null) {
+            List<ProductOrder> orders = selectOrders(new LambdaQueryWrapper<ProductOrder>()
+                    .eq(ProductOrder::getFamilyId, ctx.getFamilyId())
+                    .in(ProductOrder::getStatus, PAID_STATUSES));
+            collect(view.family, orders);
+        }
+
+        // 个人购买:优先以登录用户 buyerId,为空时用成员ID(文档 4.2:scope=individual 查 buyerId(userId) 订单)
+        Long individualId = ctx.getUserId() != null ? ctx.getUserId() : ctx.getMemberId();
+        if (individualId != null) {
+            List<ProductOrder> orders = selectOrders(new LambdaQueryWrapper<ProductOrder>()
+                    .eq(ProductOrder::getBuyerId, individualId)
+                    .in(ProductOrder::getStatus, PAID_STATUSES));
+            collect(view.individual, orders);
+        }
+
+        return view;
+    }
+
+    private List<ProductOrder> selectOrders(LambdaQueryWrapper<ProductOrder> qw) {
+        try {
+            List<ProductOrder> orders = orderMapper.selectList(qw);
+            return orders == null ? Collections.emptyList() : orders;
+        } catch (Exception e) {
+            log.warn("查询已购订单失败:{}", e.getMessage());
+            return Collections.emptyList();
+        }
+    }
+
+    private void collect(Map<Long, Date> into, List<ProductOrder> orders) {
+        for (ProductOrder o : orders) {
+            if (o.getProductId() == null) {
+                continue;
+            }
+            Date at = o.getPaidAt() != null ? o.getPaidAt() : o.getCreatedAt();
+            if (at == null) {
+                continue;
+            }
+            Date prev = into.get(o.getProductId());
+            if (prev == null || at.after(prev)) {
+                into.put(o.getProductId(), at);
+            }
+        }
+    }
+
+    /**
+     * 全局已购视图(文档 4.2 步骤2 / 4.4 兜底):
+     * 按上下文 scope 取主视图(family 查家庭订单,individual 查个人订单),主视图为空时回退到另一个。
+     */
+    private Map<Long, Date> globalPurchasesView(RecommendationEngineContext ctx, PurchaseView purchases) {
+        boolean individual = ctx.getScope() != null && "individual".equalsIgnoreCase(ctx.getScope().trim());
+        Map<Long, Date> primary = individual ? purchases.individual : purchases.family;
+        Map<Long, Date> fallback = individual ? purchases.family : purchases.individual;
+        return !primary.isEmpty() ? primary : fallback;
+    }
+
+    /**
+     * 指定规则作用域的购买视图(文档 4.2 步骤2):rule.scope 为 individual 时取个人订单,
+     * 否则(含 family/非法/空)取家庭订单并回退。
+     */
+    private Map<Long, Date> purchasesForRule(RecommendationRule rule, PurchaseView purchases) {
+        boolean individual = rule.getScope() != null && "individual".equalsIgnoreCase(rule.getScope().trim());
+        Map<Long, Date> primary = individual ? purchases.individual : purchases.family;
+        Map<Long, Date> fallback = individual ? purchases.family : purchases.individual;
+        return !primary.isEmpty() ? primary : fallback;
+    }
+
+    // -----------------------------------------------------------------------
+    // 时间窗口工具
+    // -----------------------------------------------------------------------
+
+    /**
+     * days 回溯的截止时间点。days=0 表示“只计算今日购买”(文档 7.5);
+     * days<0 视为异常,取绝对值并已在日志提示。
+     */
+    private Date daysAgo(int days) {
+        Calendar cal = Calendar.getInstance();
+        if (days == 0) {
+            cal.set(Calendar.HOUR_OF_DAY, 0);
+            cal.set(Calendar.MINUTE, 0);
+            cal.set(Calendar.SECOND, 0);
+            cal.set(Calendar.MILLISECOND, 0);
+        } else if (days < 0) {
+            log.warn("规则回溯天数为负数,取绝对值处理:{}", days);
+            cal.add(Calendar.DAY_OF_YEAR, -Math.abs(days));
+        } else {
+            cal.add(Calendar.DAY_OF_YEAR, -days);
+        }
+        return cal.getTime();
+    }
+
+    /** 指定商品是否在回溯窗口内购买过(文档 4.4 time_window_days) */
+    private boolean purchasedWithin(Map<Long, Date> purchases, Long productId, int days) {
+        if (productId == null) {
+            return false;
+        }
+        Date paidAt = purchases.get(productId);
+        return paidAt != null && !paidAt.before(daysAgo(days));
+    }
+
+    /** 指定商品的购买记录是否早于等于回溯窗口结束(即购买距今至少 days 天) */
+    private boolean purchasedAtLeastDaysAgo(Map<Long, Date> purchases, Long productId, int days) {
+        if (productId == null) {
+            return false;
+        }
+        Date paidAt = purchases.get(productId);
+        return paidAt != null && !paidAt.after(daysAgo(days));
+    }
+
+    /** 回溯窗口内购买过的商品ID集合(文档 4.4 兜底) */
+    private Set<Long> productIdsWithin(Map<Long, Date> purchases, int days) {
+        Set<Long> ids = new HashSet<>();
+        Date cutoff = daysAgo(days);
+        for (Map.Entry<Long, Date> e : purchases.entrySet()) {
+            if (e.getValue() != null && !e.getValue().before(cutoff)) {
+                ids.add(e.getKey());
+            }
+        }
+        return ids;
+    }
+
+    // -----------------------------------------------------------------------
+    // 步骤3:构建场景基础候选
+    // -----------------------------------------------------------------------
+
+    private List<RecommendedProduct> buildBaseCandidates(RecommendationEngineContext ctx, String scene,
+                                                         Map<Long, Date> globalPurchases) {
+        // 全局兜底:剔除默认窗口内已购商品(文档 4.4)
+        Set<Long> excluded = productIdsWithin(globalPurchases, DEFAULT_PURCHASED_EXCLUDE_DAYS);
+        if (ctx.getExcludeProductIds() != null) {
+            excluded.addAll(ctx.getExcludeProductIds());
+        }
+
+        switch (scene) {
+            case SCENE_DIMENSION_PAGE:
+                return buildDimensionCandidates(ctx.getDimensionCode(), excluded);
+            case SCENE_REPORT_RELATED:
+                return buildReportRelatedCandidates(ctx.getAnalysis(), excluded);
+            case SCENE_MALL_HOME:
+                return buildMallHomeCandidates(excluded);
+            case SCENE_PRODUCT_DETAIL:
+            case SCENE_AFTER_ORDER:
+                // 基础候选为空,仅由规则 3/5 命中注入(文档 4.2 步骤3)
+                return new ArrayList<>();
+            default:
+                log.warn("未知推荐场景,按商城首页处理:{}", scene);
+                return buildMallHomeCandidates(excluded);
+        }
+    }
+
+    private List<RecommendedProduct> buildDimensionCandidates(String dimensionCode, Set<Long> excluded) {
+        List<RecommendedProduct> pool = new ArrayList<>();
+
+        LambdaQueryWrapper<ProductDimensionMapping> mappingQw = new LambdaQueryWrapper<ProductDimensionMapping>()
+                .eq(ProductDimensionMapping::getEnabled, 1);
+        if (dimensionCode != null && !dimensionCode.isEmpty()) {
+            mappingQw.eq(ProductDimensionMapping::getDimensionCode, dimensionCode);
+        }
+        List<ProductDimensionMapping> mappings = dimensionMappingMapper.selectList(mappingQw);
+        if (mappings == null || mappings.isEmpty()) {
+            return pool;
+        }
+
+        Map<Long, Integer> scores = new HashMap<>();
+        Map<Long, String> reasons = new HashMap<>();
+        List<Long> productIds = new ArrayList<>();
+        for (ProductDimensionMapping m : mappings) {
+            Long productId = m.getProductId();
+            if (productId == null) {
+                continue;
+            }
+            scores.put(productId, m.getMatchScore() == null ? 100 : m.getMatchScore());
+            reasons.put(productId, m.getMatchReason());
+            productIds.add(productId);
+        }
+        if (productIds.isEmpty()) {
+            return pool;
+        }
+
+        List<Product> products = productMapper.selectList(new LambdaQueryWrapper<Product>()
+                .in(Product::getId, productIds)
+                .eq(Product::getStatus, "on_shelf")
+                .and(w -> w.ne(Product::getProductType, "physical").or().isNull(Product::getStock)
+                        .or().gt(Product::getStock, 0)));
+        if (products == null) {
+            return pool;
+        }
+
+        for (Product p : products) {
+            if (excluded.contains(p.getId())) {
+                continue;
+            }
+            RecommendedProduct rp = fromProduct(p);
+            String reason = reasons.get(p.getId());
+            rp.setReason(reason != null && !reason.isEmpty() ? reason : "根据您的维度匹配为您推荐");
+            rp.setMatchScore(scores.get(p.getId()) / 100.0);
+            rp.setPriority(0);
+            rp.setSource("engine");
+            pool.add(rp);
+        }
+        return pool;
+    }
+
+    private List<RecommendedProduct> buildMallHomeCandidates(Set<Long> excluded) {
+        List<RecommendedProduct> pool = new ArrayList<>();
+
+        List<Product> products = productMapper.selectList(new LambdaQueryWrapper<Product>()
+                .eq(Product::getStatus, "on_shelf")
+                .and(w -> w.ne(Product::getProductType, "physical").or().isNull(Product::getStock)
+                        .or().gt(Product::getStock, 0))
+                .orderByAsc(Product::getSortOrder));
+        if (products == null) {
+            return pool;
+        }
+
+        for (Product p : products) {
+            if (excluded.contains(p.getId())) {
+                continue;
+            }
+            RecommendedProduct rp = fromProduct(p);
+            rp.setReason("为您推荐的好物");
+            rp.setMatchScore(BASE_MATCH_SCORE);
+            rp.setPriority(0);
+            rp.setSource("engine");
+            pool.add(rp);
+        }
+        return pool;
+    }
+
+    private List<RecommendedProduct> buildReportRelatedCandidates(Object analysis, Set<Long> excluded) {
+        List<RecommendedProduct> pool = new ArrayList<>();
+        List<String> dims = extractWeakDimensions(analysis);
+        if (dims.isEmpty()) {
+            dims = Collections.singletonList("body");
+        }
+        Set<Long> seen = new HashSet<>();
+        for (String dim : dims) {
+            for (RecommendedProduct rp : buildDimensionCandidates(dim, excluded)) {
+                if (seen.add(rp.getProductId())) {
+                    pool.add(rp);
+                }
+            }
+        }
+        return pool;
+    }
+
+    /**
+     * 从健康/认知分析结果中提取弱维度(与现有 ProductRecommendationService 逻辑保持一致,
+     * 见文档 4.2 步骤3 report_related)。
+     */
+    @SuppressWarnings("unchecked")
+    private List<String> extractWeakDimensions(Object analysis) {
+        List<String> dims = new ArrayList<>();
+        if (analysis == null) {
+            return dims;
+        }
+        try {
+            if (analysis instanceof Map) {
+                Map<String, Object> map = (Map<String, Object>) analysis;
+                Number nutrition = asNumber(map.get("nutritionScore"));
+                Number gut = asNumber(map.get("gutHealthScore"));
+                Number overall = asNumber(map.get("overallScore"));
+                if (nutrition != null && nutrition.intValue() < 60) {
+                    dims.add("body");
+                }
+                if (gut != null && gut.intValue() < 60) {
+                    dims.add("body");
+                }
+                if (overall != null && overall.intValue() < 60) {
+                    dims.add("body");
+                    dims.add("mind");
+                }
+            } else if (analysis instanceof List) {
+                for (Object o : (List<Object>) analysis) {
+                    String dim = String.valueOf(o);
+                    if ("focusScore".equals(dim) || "processingSpeedScore".equals(dim)
+                            || "memoryScore".equals(dim)) {
+                        dims.add("wisdom");
+                    } else if ("attentionScore".equals(dim)) {
+                        dims.add("mind");
+                    } else if (!"null".equals(dim)) {
+                        dims.add(dim);
+                    }
+                }
+            }
+        } catch (Exception e) {
+            log.warn("解析报告弱维度失败:{}", e.getMessage());
+        }
+        return dims.stream().distinct().collect(Collectors.toList());
+    }
+
+    private Number asNumber(Object o) {
+        return o instanceof Number ? (Number) o : null;
+    }
+
+    // -----------------------------------------------------------------------
+    // 步骤4:应用规则(按 priority 从高到低,剔除类规则先于注入类规则)
+    // -----------------------------------------------------------------------
+
+    private void applyRules(List<RecommendationRule> rules, PurchaseView purchases,
+                            List<RecommendedProduct> pool) {
+        // removed 记录已被更高优先级排除规则剔除的商品,注入类规则不再注入(剔除优先)
+        Set<Long> removed = new HashSet<>();
+        for (RecommendationRule rule : rules) {
+            try {
+                int type = rule.getRuleType() == null ? 0 : rule.getRuleType();
+                Map<Long, Date> scopePurchases = purchasesForRule(rule, purchases);
+                switch (type) {
+                    case 1:
+                        applyRule1Exclude(rule, scopePurchases, pool, removed);
+                        break;
+                    case 2:
+                        applyRule2Repurchase(rule, scopePurchases, pool, removed);
+                        break;
+                    case 3:
+                        applyRule3CrossSell(rule, scopePurchases, pool, removed);
+                        break;
+                    case 4:
+                        applyRule4Suppress(rule, scopePurchases, pool, removed);
+                        break;
+                    case 5:
+                        applyRule5Series(rule, scopePurchases, pool, removed);
+                        break;
+                    default:
+                        log.warn("推荐规则[{}]类型非法:{}", rule.getId(), rule.getRuleType());
+                }
+            } catch (Exception e) {
+                log.warn("推荐规则[{}]应用异常,已跳过:{}", rule.getId(), e.getMessage());
+            }
+        }
+    }
+
+    // ---------- 规则 1:已购不推 ----------
+    private void applyRule1Exclude(RecommendationRule rule, Map<Long, Date> purchases,
+                                   List<RecommendedProduct> pool, Set<Long> removed) {
+        if (rule.getTargetProductId() == null) {
+            return;
+        }
+        Long trigger = rule.getTriggerProductId();
+        if (trigger == null) {
+            // 未配置触发商品:全局已购兜底已在候选池构建阶段完成,规则 1 仅做特定商品覆盖(文档 4.4)
+            return;
+        }
+        int window = rule.getTimeWindowDays() != null ? rule.getTimeWindowDays()
+                : DEFAULT_PURCHASED_EXCLUDE_DAYS;
+        if (!purchasedWithin(purchases, trigger, window)) {
+            return; // 未命中,跳过(文档 4.1)
+        }
+        removeFromPool(pool, removed, rule.getTargetProductId());
+    }
+
+    // ---------- 规则 2:定时复购 ----------
+    private void applyRule2Repurchase(RecommendationRule rule, Map<Long, Date> purchases,
+                                      List<RecommendedProduct> pool, Set<Long> removed) {
+        Long trigger = rule.getTriggerProductId();
+        Long target = rule.getTargetProductId();
+        if (trigger == null || target == null) {
+            log.warn("规则[{}]缺少触发/目标商品,已跳过", rule.getId());
+            return;
+        }
+        int delay = rule.getDelayDays() != null ? rule.getDelayDays() : DEFAULT_DELAY_DAYS;
+        if (!purchasedAtLeastDaysAgo(purchases, trigger, delay)) {
+            return; // 未到复购时间
+        }
+        addToPool(pool, removed, target, "该商品您已购买,可考虑复购",
+                priorityOf(rule), rule.getId(), rule.getRuleType());
+    }
+
+    // ---------- 规则 3:购买A推B ----------
+    private void applyRule3CrossSell(RecommendationRule rule, Map<Long, Date> purchases,
+                                     List<RecommendedProduct> pool, Set<Long> removed) {
+        Long trigger = rule.getTriggerProductId();
+        Long target = rule.getTargetProductId();
+        if (trigger == null || target == null) {
+            return;
+        }
+        if (!purchases.containsKey(trigger)) {
+            return; // 未命中,跳过(文档 4.3)
+        }
+        addToPool(pool, removed, target, "根据您的购买记录推荐",
+                priorityOf(rule), rule.getId(), rule.getRuleType());
+    }
+
+    // ---------- 规则 4:购买A不推B ----------
+    private void applyRule4Suppress(RecommendationRule rule, Map<Long, Date> purchases,
+                                    List<RecommendedProduct> pool, Set<Long> removed) {
+        Long trigger = rule.getTriggerProductId();
+        Long target = rule.getTargetProductId();
+        if (trigger == null || target == null) {
+            return;
+        }
+        if (!purchases.containsKey(trigger)) {
+            return; // 未命中,跳过(文档 4.1)
+        }
+        removeFromPool(pool, removed, target);
+    }
+
+    // ---------- 规则 5:系列重点推 ----------
+    private void applyRule5Series(RecommendationRule rule, Map<Long, Date> purchases,
+                                  List<RecommendedProduct> pool, Set<Long> removed) {
+        Set<Long> triggers = parseLongArray(rule.getTriggerProductIds());
+        if (triggers.isEmpty()) {
+            log.warn("规则[{}] trigger_product_ids 为空或解析失败,已跳过", rule.getId());
+            return;
+        }
+        // 触发商品需全部购买过(文档 4.4)
+        for (Long id : triggers) {
+            if (!purchases.containsKey(id)) {
+                return;
+            }
+        }
+        addToPool(pool, removed, rule.getTargetProductId(), "系列商品重点推荐",
+                priorityOf(rule) + SERIES_PRIORITY_BOOST, rule.getId(), rule.getRuleType());
+    }
+
+    private void removeFromPool(List<RecommendedProduct> pool, Set<Long> removed, Long productId) {
+        if (productId == null) {
+            return;
+        }
+        pool.removeIf(p -> productId.equals(p.getProductId()));
+        removed.add(productId);
+    }
+
+    private void addToPool(List<RecommendedProduct> pool, Set<Long> removed, Long productId,
+                           String reason, int priority, Long ruleId, Integer ruleType) {
+        if (productId == null || removed.contains(productId)) {
+            return;
+        }
+
+        RecommendedProduct existing = null;
+        for (RecommendedProduct p : pool) {
+            if (productId.equals(p.getProductId())) {
+                existing = p;
+                break;
+            }
+        }
+
+        if (existing != null) {
+            // 该商品已在候选池中:不重复添加,仅更新推荐理由(文档 4.3)。
+            // 若条目来自基础候选(ruleId 为空),则采用本规则的属性;若已由规则注入,则取更高优先级。
+            existing.setReason(reason);
+            if (existing.getRuleId() == null) {
+                existing.setRuleId(ruleId == null ? null : ruleId.intValue());
+                existing.setRuleType(ruleType);
+                existing.setPriority(priority);
+                existing.setMatchScore(Math.max(existing.getMatchScore() == null ? 0d : existing.getMatchScore(),
+                        RULE_MATCH_SCORE));
+            } else if (priority > existing.getPriority()) {
+                existing.setPriority(priority);
+            }
+            return;
+        }
+
+        Product product = productMapper.selectById(productId);
+        if (!isRecommendable(product)) {
+            log.warn("规则目标商品不可推荐(productId={}, status={}): {}", productId,
+                    product == null ? "null" : product.getStatus(), ruleId);
+            return;
+        }
+
+        RecommendedProduct rp = fromProduct(product);
+        rp.setReason(reason);
+        rp.setMatchScore(RULE_MATCH_SCORE);
+        rp.setRuleId(ruleId == null ? null : ruleId.intValue());
+        rp.setRuleType(ruleType);
+        rp.setPriority(priority);
+        rp.setSource("engine");
+        pool.add(rp);
+    }
+
+    private boolean isRecommendable(Product product) {
+        return product != null && "on_shelf".equals(product.getStatus()) && hasSellableStock(product);
+    }
+
+    private boolean hasSellableStock(Product product) {
+        if (!"physical".equals(product.getProductType())) {
+            return true;
+        }
+        return product.getStock() == null || product.getStock() > 0;
+    }
+
+    // -----------------------------------------------------------------------
+    // 步骤5:排序与截断
+    // -----------------------------------------------------------------------
+
+    private List<RecommendedProduct> sortAndTruncate(List<RecommendedProduct> pool, int limit) {
+        if (pool == null || pool.isEmpty()) {
+            return Collections.emptyList();
+        }
+        pool.sort((a, b) -> {
+            int cmp = Integer.compare(priorityOfResult(b), priorityOfResult(a)); // priority DESC
+            if (cmp != 0) {
+                return cmp;
+            }
+            cmp = Double.compare(matchScoreOfResult(b), matchScoreOfResult(a)); // matchScore DESC
+            if (cmp != 0) {
+                return cmp;
+            }
+            return Long.compare(productIdOfResult(a), productIdOfResult(b));
+        });
+        if (pool.size() > limit) {
+            return new ArrayList<>(pool.subList(0, limit));
+        }
+        return new ArrayList<>(pool);
+    }
+
+    // -----------------------------------------------------------------------
+    // 工具方法
+    // -----------------------------------------------------------------------
+
+    private RecommendedProduct fromProduct(Product p) {
+        RecommendedProduct rp = new RecommendedProduct();
+        rp.setProductId(p.getId());
+        rp.setName(p.getName());
+        rp.setCoverImage(p.getCoverImage());
+        rp.setPrice(p.getPrice());
+        rp.setUrl("/pages/discover-detail/product-detail/product-detail?id=" + p.getId());
+        return rp;
+    }
+
+    /** JSON/逗号分隔的长整型数组解析(容错:忽略非数字项),用于 trigger_product_ids。 */
+    private Set<Long> parseLongArray(String raw) {
+        Set<Long> ids = new LinkedHashSet<>();
+        for (String s : parseStringArray(raw)) {
+            try {
+                ids.add(Long.parseLong(s));
+            } catch (NumberFormatException e) {
+                log.warn("规则配置包含无法解析的商品ID:{}", s);
+            }
+        }
+        return ids;
+    }
+
+    /**
+     * 解析 JSON 数组字符串或纯逗号分隔字符串。
+     * 支持如 "[\"dimension_page\",\"mall_home\"]"、dimension_page,mall_home 等写法。
+     */
+    private List<String> parseStringArray(String raw) {
+        List<String> result = new ArrayList<>();
+        if (raw == null) {
+            return result;
+        }
+        String cleaned = raw.trim();
+        if (cleaned.startsWith("[")) {
+            cleaned = cleaned.substring(1);
+        }
+        if (cleaned.endsWith("]")) {
+            cleaned = cleaned.substring(0, cleaned.length() - 1);
+        }
+        for (String part : cleaned.split("[,,;]")) {
+            String s = part.trim().replace("\"", "").replace("'", "");
+            if (!s.isEmpty()) {
+                result.add(s);
+            }
+        }
+        return result;
+    }
+
+    private static int priorityOf(RecommendationRule r) {
+        return r.getPriority() == null ? 0 : r.getPriority();
+    }
+
+    private static long ruleIdOf(RecommendationRule r) {
+        return r.getId() == null ? 0L : r.getId();
+    }
+
+    /** 同优先级下,剔除类规则先于注入类规则(文档 4.1~4.5):4,1,3,5,2 */
+    private static int ruleLoopOrder(Integer ruleType) {
+        int t = ruleType == null ? 0 : ruleType;
+        switch (t) {
+            case 4:
+                return 0;
+            case 1:
+                return 1;
+            case 3:
+                return 2;
+            case 5:
+                return 3;
+            case 2:
+                return 4;
+            default:
+                return 5;
+        }
+    }
+
+    private static int priorityOfResult(RecommendedProduct p) {
+        return p.getPriority() == null ? 0 : p.getPriority();
+    }
+
+    private static double matchScoreOfResult(RecommendedProduct p) {
+        return p.getMatchScore() == null ? 0d : p.getMatchScore();
+    }
+
+    private static long productIdOfResult(RecommendedProduct p) {
+        return p.getProductId() == null ? 0L : p.getProductId();
+    }
+}

+ 507 - 0
cfc-backend/src/test/java/com/etotem/cfc/service/RecommendationRuleEngineTest.java

@@ -0,0 +1,507 @@
+package com.etotem.cfc.service;
+
+import com.etotem.cfc.dto.RecommendationEngineContext;
+import com.etotem.cfc.dto.RecommendedProduct;
+import com.etotem.cfc.entity.Product;
+import com.etotem.cfc.entity.ProductOrder;
+import com.etotem.cfc.entity.RecommendationRule;
+import com.etotem.cfc.mapper.ProductDimensionMappingMapper;
+import com.etotem.cfc.mapper.ProductMapper;
+import com.etotem.cfc.mapper.ProductOrderMapper;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.test.util.ReflectionTestUtils;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Calendar;
+import java.util.Collections;
+import java.util.Date;
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.mock;
+import static org.mockito.Mockito.when;
+
+/**
+ * 商品推荐规则引擎单元测试。
+ *
+ * <p>覆盖设计文档 docs/superpowers/specs/2026-09-17-product-recommendation-rule-engine-design.md
+ * 第 8 节测试要点:5 种规则各自命中/未命中、优先级排序、scope family/individual、time_window_days 边界、降级。
+ */
+public class RecommendationRuleEngineTest {
+
+    private RecommendationRuleEngine engine;
+    private RecommendationRuleService ruleService;
+    private ProductMapper productMapper;
+    private ProductDimensionMappingMapper dimensionMappingMapper;
+    private ProductOrderMapper orderMapper;
+
+    @BeforeEach
+    public void setUp() {
+        engine = new RecommendationRuleEngine();
+        ruleService = mock(RecommendationRuleService.class);
+        productMapper = mock(ProductMapper.class);
+        dimensionMappingMapper = mock(ProductDimensionMappingMapper.class);
+        orderMapper = mock(ProductOrderMapper.class);
+        ReflectionTestUtils.setField(engine, "recommendationRuleService", ruleService);
+        ReflectionTestUtils.setField(engine, "productMapper", productMapper);
+        ReflectionTestUtils.setField(engine, "dimensionMappingMapper", dimensionMappingMapper);
+        ReflectionTestUtils.setField(engine, "orderMapper", orderMapper);
+    }
+
+    // -----------------------------------------------------------------------
+    // 辅助构造
+    // -----------------------------------------------------------------------
+
+    private void mockRules(List<RecommendationRule> rules) {
+        when(ruleService.list(any())).thenReturn(rules);
+    }
+
+    private void mockMallProducts(Product... products) {
+        when(productMapper.selectList(any())).thenReturn(new ArrayList<>(Arrays.asList(products)));
+    }
+
+    private void mockOrders(List<ProductOrder> family, List<ProductOrder> individual) {
+        when(orderMapper.selectList(any()))
+                .thenReturn(family == null ? Collections.emptyList() : family,
+                        individual == null ? Collections.emptyList() : individual);
+    }
+
+    private void mockProductById(Product product) {
+        when(productMapper.selectById(product.getId())).thenReturn(product);
+    }
+
+    private Product product(long id) {
+        Product p = new Product();
+        p.setId(id);
+        p.setName("商品" + id);
+        p.setPrice(1000);
+        p.setStatus("on_shelf");
+        p.setProductType("virtual");
+        return p;
+    }
+
+    private ProductOrder order(long productId, Date paidAt, Long familyId, Long buyerId) {
+        ProductOrder o = new ProductOrder();
+        o.setProductId(productId);
+        o.setPaidAt(paidAt);
+        o.setFamilyId(familyId);
+        o.setBuyerId(buyerId);
+        o.setStatus("paid");
+        return o;
+    }
+
+    private Date daysAgo(int days) {
+        Calendar cal = Calendar.getInstance();
+        cal.add(Calendar.DAY_OF_YEAR, -days);
+        return cal.getTime();
+    }
+
+    private RecommendationRule rule(int type, String sceneCodes, Long triggerId, Long targetId, int priority) {
+        RecommendationRule r = new RecommendationRule();
+        r.setRuleType(type);
+        r.setSceneCodes(sceneCodes);
+        r.setTriggerProductId(triggerId);
+        r.setTargetProductId(targetId);
+        r.setPriority(priority);
+        r.setEnabled(1);
+        return r;
+    }
+
+    private RecommendationEngineContext ctx(String scene, Long familyId, Long userId) {
+        RecommendationEngineContext c = new RecommendationEngineContext();
+        c.setScene(scene);
+        c.setFamilyId(familyId);
+        c.setUserId(userId);
+        return c;
+    }
+
+    private List<Long> ids(List<RecommendedProduct> list) {
+        return list.stream().map(RecommendedProduct::getProductId).collect(Collectors.toList());
+    }
+
+    // -----------------------------------------------------------------------
+    // 规则 1:已购不推(触发商品在窗口内购买 → 目标从候选池移除)
+    // -----------------------------------------------------------------------
+
+    @Test
+    public void rule1_purchasedTriggerWithinWindow_removesTarget() {
+        mockRules(Collections.singletonList(
+                rule(1, "[\"mall_home\"]", 100L, 200L, 10)));
+        // 家庭已购 trigger=100(10天前),基础候选为 200/300(均未购)
+        mockOrders(Collections.singletonList(order(100L, daysAgo(10), 1L, 1L)), Collections.emptyList());
+        mockMallProducts(product(200L), product(300L));
+
+        List<RecommendedProduct> result = engine.recommend(ctx(RecommendationRuleEngine.SCENE_MALL_HOME, 1L, 1L), 10);
+
+        assertFalse(ids(result).contains(200L), "规则1应移除目标商品200");
+        assertTrue(ids(result).contains(300L), "未命中商品300应保留");
+        assertEquals(1, result.size());
+        assertTrue(result.stream().noneMatch(p -> p.getRuleType() != null), "基础候选不应带规则类型");
+    }
+
+    @Test
+    public void rule1_triggerNotPurchased_targetRemains() {
+        mockRules(Collections.singletonList(
+                rule(1, "[\"mall_home\"]", 100L, 200L, 10)));
+        // 未购买 trigger=100
+        mockOrders(Collections.emptyList(), Collections.emptyList());
+        mockMallProducts(product(200L), product(300L));
+
+        List<RecommendedProduct> result = engine.recommend(ctx(RecommendationRuleEngine.SCENE_MALL_HOME, 1L, 1L), 10);
+
+        assertTrue(ids(result).contains(200L), "未命中时目标200应保留");
+        assertTrue(ids(result).contains(300L));
+    }
+
+    // -----------------------------------------------------------------------
+    // 规则 2:定时复购(购买距今 >= delay_days → 目标加入候选)
+    // -----------------------------------------------------------------------
+
+    @Test
+    public void rule2_repurchaseAfterDelay_addsTargetWithReason() {
+        RecommendationRule r = rule(2, "[\"mall_home\"]", 100L, 100L, 10);
+        r.setDelayDays(30);
+        mockRules(Collections.singletonList(r));
+        // 100 于 40 天前购买(>= 30天),复购目标=100
+        mockOrders(Collections.singletonList(order(100L, daysAgo(40), 1L, 1L)), Collections.emptyList());
+        mockMallProducts(product(300L));
+        mockProductById(product(100L));
+
+        List<RecommendedProduct> result = engine.recommend(ctx(RecommendationRuleEngine.SCENE_MALL_HOME, 1L, 1L), 10);
+
+        RecommendedProduct repurchase = result.stream()
+                .filter(p -> p.getProductId() == 100L).findFirst().orElse(null);
+        assertNotNull(repurchase, "规则2应加入复购目标100");
+        assertEquals("该商品您已购买,可考虑复购", repurchase.getReason());
+        assertEquals(2, repurchase.getRuleType());
+    }
+
+    @Test
+    public void rule2_beforeDelay_notAdded() {
+        RecommendationRule r = rule(2, "[\"mall_home\"]", 100L, 100L, 10);
+        r.setDelayDays(30);
+        mockRules(Collections.singletonList(r));
+        // 100 于 10 天前购买(< 30天)
+        mockOrders(Collections.singletonList(order(100L, daysAgo(10), 1L, 1L)), Collections.emptyList());
+        mockMallProducts(product(300L));
+
+        List<RecommendedProduct> result = engine.recommend(ctx(RecommendationRuleEngine.SCENE_MALL_HOME, 1L, 1L), 10);
+
+        assertFalse(ids(result).contains(100L), "未到复购时间不应加入目标100");
+    }
+
+    // -----------------------------------------------------------------------
+    // 规则 3:购买A推B(已购 A → 加入 B)
+    // -----------------------------------------------------------------------
+
+    @Test
+    public void rule3_purchaseA_addsB() {
+        mockRules(Collections.singletonList(
+                rule(3, "[\"mall_home\"]", 100L, 200L, 20)));
+        mockOrders(Collections.singletonList(order(100L, daysAgo(10), 1L, 1L)), Collections.emptyList());
+        mockMallProducts(product(300L));
+        mockProductById(product(200L));
+
+        List<RecommendedProduct> result = engine.recommend(ctx(RecommendationRuleEngine.SCENE_MALL_HOME, 1L, 1L), 10);
+
+        RecommendedProduct b = result.stream().filter(p -> p.getProductId() == 200L).findFirst().orElse(null);
+        assertNotNull(b, "规则3应加入目标200");
+        assertEquals("根据您的购买记录推荐", b.getReason());
+        assertEquals(3, b.getRuleType());
+    }
+
+    @Test
+    public void rule3_triggerNotPurchased_skip() {
+        mockRules(Collections.singletonList(
+                rule(3, "[\"mall_home\"]", 100L, 200L, 20)));
+        mockOrders(Collections.emptyList(), Collections.emptyList());
+        mockMallProducts(product(300L));
+
+        List<RecommendedProduct> result = engine.recommend(ctx(RecommendationRuleEngine.SCENE_MALL_HOME, 1L, 1L), 10);
+
+        assertFalse(ids(result).contains(200L), "未购买A不应加入B");
+    }
+
+    // -----------------------------------------------------------------------
+    // 规则 4:购买A不推B(已购 A → 目标从候选池移除)
+    // -----------------------------------------------------------------------
+
+    @Test
+    public void rule4_purchaseA_removesB() {
+        mockRules(Collections.singletonList(
+                rule(4, "[\"mall_home\"]", 100L, 200L, 10)));
+        mockOrders(Collections.singletonList(order(100L, daysAgo(10), 1L, 1L)), Collections.emptyList());
+        mockMallProducts(product(200L), product(300L));
+
+        List<RecommendedProduct> result = engine.recommend(ctx(RecommendationRuleEngine.SCENE_MALL_HOME, 1L, 1L), 10);
+
+        assertFalse(ids(result).contains(200L), "规则4应移除目标200");
+        assertTrue(ids(result).contains(300L));
+    }
+
+    // -----------------------------------------------------------------------
+    // 规则 5:系列重点推(购买全部触发商品 → 目标加入 + 优先级提升)
+    // -----------------------------------------------------------------------
+
+    @Test
+    public void rule5_purchaseAllSeries_boostTarget() {
+        RecommendationRule r = rule(5, "[\"mall_home\"]", null, 200L, 10);
+        r.setTriggerProductIds("[1,2,3]");
+        mockRules(Collections.singletonList(r));
+        mockOrders(Arrays.asList(
+                        order(1L, daysAgo(30), 1L, 1L),
+                        order(2L, daysAgo(20), 1L, 1L),
+                        order(3L, daysAgo(10), 1L, 1L)),
+                Collections.emptyList());
+        mockMallProducts(product(300L));
+        mockProductById(product(200L));
+
+        List<RecommendedProduct> result = engine.recommend(ctx(RecommendationRuleEngine.SCENE_MALL_HOME, 1L, 1L), 10);
+
+        RecommendedProduct target = result.stream().filter(p -> p.getProductId() == 200L).findFirst().orElse(null);
+        assertNotNull(target, "规则5应加入系列目标200");
+        // 优先级 = 规则优先级(10) + 系列加成(10)
+        assertEquals(20, target.getPriority());
+        assertEquals("系列商品重点推荐", target.getReason());
+        assertEquals(5, target.getRuleType());
+    }
+
+    @Test
+    public void rule5_missingOneSeries_noTrigger() {
+        RecommendationRule r = rule(5, "[\"mall_home\"]", null, 200L, 10);
+        r.setTriggerProductIds("[1,2,3]");
+        mockRules(Collections.singletonList(r));
+        // 只买了 1、2,缺 3
+        mockOrders(Arrays.asList(order(1L, daysAgo(30), 1L, 1L), order(2L, daysAgo(20), 1L, 1L)),
+                Collections.emptyList());
+        mockMallProducts(product(300L));
+
+        List<RecommendedProduct> result = engine.recommend(ctx(RecommendationRuleEngine.SCENE_MALL_HOME, 1L, 1L), 10);
+
+        assertFalse(ids(result).contains(200L), "系列未购全,不应加入目标200");
+    }
+
+    // -----------------------------------------------------------------------
+    // 优先级排序:priority DESC(同 matchScore 时按规则优先级决定先后)
+    // -----------------------------------------------------------------------
+
+    @Test
+    public void priorityOrdering_higherPriorityFirst() {
+        // 规则A priority=50 → 目标 201;规则B priority=10 → 目标 202
+        mockRules(Arrays.asList(
+                rule(3, "[\"mall_home\"]", 100L, 201L, 50),
+                rule(3, "[\"mall_home\"]", 100L, 202L, 10)));
+        mockOrders(Collections.singletonList(order(100L, daysAgo(10), 1L, 1L)), Collections.emptyList());
+        mockMallProducts(product(300L));
+        mockProductById(product(201L));
+        mockProductById(product(202L));
+
+        List<RecommendedProduct> result = engine.recommend(ctx(RecommendationRuleEngine.SCENE_MALL_HOME, 1L, 1L), 10);
+
+        assertTrue(ids(result).indexOf(201L) < ids(result).indexOf(202L),
+                "高优先级规则目标201应先于202");
+    }
+
+    // -----------------------------------------------------------------------
+    // scope family/individual
+    // -----------------------------------------------------------------------
+
+    @Test
+    public void scope_individual_usesBuyerOrders() {
+        RecommendationRule r = rule(3, "[\"mall_home\"]", 100L, 200L, 10);
+        r.setScope("individual");
+        mockRules(Collections.singletonList(r));
+        // 家庭买了 100,但用户本人未买;个人订单为空 → individual 规则不应触发
+        mockOrders(Collections.singletonList(order(100L, daysAgo(10), 1L, 1L)), Collections.emptyList());
+        mockMallProducts(product(300L));
+
+        List<RecommendedProduct> result = engine.recommend(ctx(RecommendationRuleEngine.SCENE_MALL_HOME, 1L, 1L), 10);
+
+        assertFalse(ids(result).contains(200L), "individual 规则不应因家庭购买而触发");
+    }
+
+    @Test
+    public void scope_individual_triggeredByPersonalPurchase() {
+        RecommendationRule r = rule(3, "[\"mall_home\"]", 100L, 200L, 10);
+        r.setScope("individual");
+        mockRules(Collections.singletonList(r));
+        // 用户本人买了 100
+        mockOrders(Collections.emptyList(),
+                Collections.singletonList(order(100L, daysAgo(10), 1L, 5L)));
+        mockMallProducts(product(300L));
+        mockProductById(product(200L));
+
+        List<RecommendedProduct> result = engine.recommend(ctx(RecommendationRuleEngine.SCENE_MALL_HOME, 1L, 5L), 10);
+
+        assertTrue(ids(result).contains(200L), "用户本人购买应触发 individual 规则");
+    }
+
+    // -----------------------------------------------------------------------
+    // time_window_days 边界:0=仅今日,365=宽窗口
+    // -----------------------------------------------------------------------
+
+    @Test
+    public void rule1_windowZero_oldPurchaseNotExcluded() {
+        RecommendationRule r = rule(1, "[\"mall_home\"]", 100L, 200L, 10);
+        r.setTimeWindowDays(0);
+        mockRules(Collections.singletonList(r));
+        // 100 于 5 天前购买,窗口=0(仅今日)→ 不触发
+        mockOrders(Collections.singletonList(order(100L, daysAgo(5), 1L, 1L)), Collections.emptyList());
+        mockMallProducts(product(200L), product(300L));
+
+        List<RecommendedProduct> result = engine.recommend(ctx(RecommendationRuleEngine.SCENE_MALL_HOME, 1L, 1L), 10);
+
+        assertTrue(ids(result).contains(200L), "窗口=0 时5天前购买不应触发剔除");
+    }
+
+    @Test
+    public void rule1_window365_recentPurchaseExcluded() {
+        RecommendationRule r = rule(1, "[\"mall_home\"]", 100L, 200L, 10);
+        r.setTimeWindowDays(365);
+        mockRules(Collections.singletonList(r));
+        // 100 于 10 天前购买,窗口=365 → 触发剔除 200
+        mockOrders(Collections.singletonList(order(100L, daysAgo(10), 1L, 1L)), Collections.emptyList());
+        mockMallProducts(product(200L), product(300L));
+
+        List<RecommendedProduct> result = engine.recommend(ctx(RecommendationRuleEngine.SCENE_MALL_HOME, 1L, 1L), 10);
+
+        assertFalse(ids(result).contains(200L), "窗口=365 时10天前购买应触发剔除");
+    }
+
+    // -----------------------------------------------------------------------
+    // 降级:规则表为空 → 返回基础候选(不抛异常)
+    // -----------------------------------------------------------------------
+
+    @Test
+    public void degradation_emptyRules_returnsBasePool() {
+        mockRules(Collections.emptyList());
+        mockOrders(Collections.emptyList(), Collections.emptyList());
+        mockMallProducts(product(1L), product(2L), product(3L));
+
+        List<RecommendedProduct> result = engine.recommend(ctx(RecommendationRuleEngine.SCENE_MALL_HOME, 1L, 1L), null);
+
+        assertEquals(3, result.size(), "规则表为空应退化为基础候选");
+        assertTrue(result.stream().allMatch(p -> p.getRuleId() == null));
+    }
+
+    @Test
+    public void degradation_emptyRules_globalExcludeStillApplies() {
+        mockRules(Collections.emptyList());
+        // 家庭 90 天内买过 1 → 基础候选剔除 1
+        mockOrders(Collections.singletonList(order(1L, daysAgo(10), 1L, 1L)), Collections.emptyList());
+        mockMallProducts(product(1L), product(2L), product(3L));
+
+        List<RecommendedProduct> result = engine.recommend(ctx(RecommendationRuleEngine.SCENE_MALL_HOME, 1L, 1L), 10);
+
+        assertFalse(ids(result).contains(1L), "默认90天内已购商品应被全局剔除");
+        assertTrue(ids(result).contains(2L));
+    }
+
+    // -----------------------------------------------------------------------
+    // limit 截断
+    // -----------------------------------------------------------------------
+
+    @Test
+    public void limit_truncatesToLimit() {
+        mockRules(Collections.emptyList());
+        mockOrders(Collections.emptyList(), Collections.emptyList());
+        mockMallProducts(product(1L), product(2L), product(3L), product(4L), product(5L));
+
+        List<RecommendedProduct> result = engine.recommend(ctx(RecommendationRuleEngine.SCENE_MALL_HOME, 1L, 1L), 3);
+
+        assertEquals(3, result.size(), "结果应截断到 limit=3");
+    }
+
+    // -----------------------------------------------------------------------
+    // scene_codes 匹配:空串=所有场景;前缀匹配
+    // -----------------------------------------------------------------------
+
+    @Test
+    public void sceneMatching_emptySceneCodes_appliesToAll() {
+        RecommendationRule r = rule(3, "", 100L, 200L, 10);
+        mockRules(Collections.singletonList(r));
+        mockOrders(Collections.singletonList(order(100L, daysAgo(10), 1L, 1L)), Collections.emptyList());
+        mockMallProducts(product(300L));
+        mockProductById(product(200L));
+
+        List<RecommendedProduct> result = engine.recommend(ctx(RecommendationRuleEngine.SCENE_MALL_HOME, 1L, 1L), 10);
+
+        assertTrue(ids(result).contains(200L), "空 scene_codes 应视为所有场景生效");
+    }
+
+    @Test
+    public void sceneMatching_sceneCodeNotListed_ignored() {
+        mockRules(Collections.singletonList(
+                rule(3, "[\"product_detail\"]", 100L, 200L, 10)));
+        mockOrders(Collections.singletonList(order(100L, daysAgo(10), 1L, 1L)), Collections.emptyList());
+        mockMallProducts(product(300L));
+
+        // mall_home 场景下,仅 product_detail 的规则不应生效
+        List<RecommendedProduct> result = engine.recommend(ctx(RecommendationRuleEngine.SCENE_MALL_HOME, 1L, 1L), 10);
+
+        assertFalse(ids(result).contains(200L), "scene 不匹配时规则不应生效");
+    }
+
+    // -----------------------------------------------------------------------
+    // 已购商品 90 天内不进基础候选(全局兜底)+ 用户排除
+    // -----------------------------------------------------------------------
+
+    @Test
+    public void globalExclude_within90Days_notInPool() {
+        mockRules(Collections.emptyList());
+        // 家庭 90 天内买过 2
+        mockOrders(Collections.singletonList(order(2L, daysAgo(50), 1L, 1L)), Collections.emptyList());
+        mockMallProducts(product(1L), product(2L), product(3L));
+
+        List<RecommendedProduct> result = engine.recommend(ctx(RecommendationRuleEngine.SCENE_MALL_HOME, 1L, 1L), 10);
+
+        assertFalse(ids(result).contains(2L), "90天内已购2不应进候选");
+    }
+
+    @Test
+    public void userExcludeProductIds_notInPool() {
+        mockRules(Collections.emptyList());
+        mockOrders(Collections.emptyList(), Collections.emptyList());
+        mockMallProducts(product(1L), product(2L), product(3L));
+        RecommendationEngineContext c = ctx(RecommendationRuleEngine.SCENE_MALL_HOME, 1L, 1L);
+        c.setExcludeProductIds(Collections.singletonList(2L));
+
+        List<RecommendedProduct> result = engine.recommend(c, 10);
+
+        assertFalse(ids(result).contains(2L), "用户排除商品2不应进候选");
+    }
+
+    // -----------------------------------------------------------------------
+    // 规则 3/5 目标商品存在校验:不存在的目标商品跳过(文档 7.3)
+    // -----------------------------------------------------------------------
+
+    @Test
+    public void rule3_targetProductMissing_skipped() {
+        mockRules(Collections.singletonList(
+                rule(3, "[\"mall_home\"]", 100L, 999L, 10)));
+        mockOrders(Collections.singletonList(order(100L, daysAgo(10), 1L, 1L)), Collections.emptyList());
+        mockMallProducts(product(300L));
+        when(productMapper.selectById(999L)).thenReturn(null);
+
+        List<RecommendedProduct> result = engine.recommend(ctx(RecommendationRuleEngine.SCENE_MALL_HOME, 1L, 1L), 10);
+
+        assertFalse(ids(result).contains(999L), "目标商品不存在时应跳过");
+    }
+
+    @Test
+    public void result_toMap_includesEngineFields() {
+        RecommendedProduct p = new RecommendedProduct();
+        p.setProductId(1L);
+        p.setRuleType(3);
+        p.setSource("engine");
+        Map<String, Object> map = p.toMap();
+        assertEquals(1L, map.get("productId"));
+        assertEquals(3, map.get("ruleType"));
+        assertEquals("engine", map.get("source"));
+    }
+}

+ 3 - 3
docs/superpowers/specs/2026-09-17-product-recommendation-rule-engine-design.md

@@ -312,10 +312,10 @@ CREATE INDEX idx_rules_priority ON recommendation_rules(priority);
 
 - [ ] 新表 `recommendation_rules` 建表 + schema.sql 同步
 - [ ] `RecommendationRuleMapper` + `RecommendationRuleService` 实现
-- [ ] `RecommendationRuleEngine.recommend()` 完整实现(5种规则流程)
+- [x] `RecommendationRuleEngine.recommend()` 完整实现(5种规则流程)
 - [ ] `RepurchaseReminderService` 规则2 配置读取改造
 - [ ] `ProductRecommendationService` 改为调用 engine
 - [ ] 管理端 CRUD 页面 + API
-- [ ] 单元测试:5种规则各自命中/未命中 + priority 排序 + scope family/individual
-- [ ] 集成测试:mvn clean compile 通过
+- [x] 单元测试:5种规则各自命中/未命中 + priority 排序 + scope family/individual
+- [x] 集成测试:mvn clean compile 通过
 - [ ] 文档同步:`docs/superpowers/specs/2026-09-17-product-recommendation-rule-engine-design.md`