# 商品推荐规则引擎设计文档

## 1. 概述

统一商品推荐的 5 种业务规则，引入统一规则引擎，由配置表 `recommendation_rules` 驱动。现有实现（已购90天排除 + 定时复购提醒）并入新引擎，所有场景（维度页/商城首页/商品详情/下单成功/报告关联）统一走一套计算逻辑，配置在后台管理端。

## 2. 核心目标

1. **统一入口**：所有推荐场景通过同一个引擎计算，输入输出一致
2. **配置驱动**：规则均由 `recommendation_rules` 表配置，运营可在 Web 管理端增删改，无需改代码
3. **降级兼容**：规则表为空时退化为现有硬编码行为，保证不出现空结果
4. **最小侵入**：现有接口/服务改造仅改调用引擎，核心业务逻辑不改
5. **覆盖全场景**：5 种规则全覆盖，且易扩展新规则

## 3. 数据模型

### 3.1 新表 `recommendation_rules`

| 字段 | 类型 | 主键 | 说明 |
|------|------|------|------|
| `id` | BIGINT | PK | 主键，AUTO_INCREMENT |
| `rule_type` | TINYINT | — | 规则类型 1-5 |
| `rule_name` | VARCHAR(100) | — | 运营可读名称 |
| `trigger_product_id` | BIGINT | — | 单商品触发（规则1/2/3/4） |
| `trigger_product_ids` | VARCHAR(1000) | — | 多商品触发 JSON 数组（规则5，如 `"[1,2,3]"`） |
| `target_product_id` | BIGINT | — | 目标商品ID（被推荐/排除/重点推） |
| `priority` | INT | — | 优先级分，越大越先处理 |
| `enabled` | TINYINT | — | 启用 1/0 |
| `time_window_days` | INT | — | 购买回溯窗口（天），默认 null=不限 |
| `delay_days` | INT | — | 复购延迟天数（规则2） |
| `scope` | VARCHAR(20) | — | `family`/`individual` |
| `scene_codes` | VARCHAR(500) | — | 生效场景 JSON 数组，如 `"[\"dimension_page\",\"product_detail\"]"` |
| `created_at` | DATETIME | — | 创建时间 |
| `updated_at` | DATETIME | — | 更新时间 |

### 3.2 Index 建议

- `idx_rules_enabled`(`enabled`, `rule_type`)
- `idx_rules_scene`(`scene_codes`, `enabled`)
- `idx_rules_priority`(`priority`, `enabled`)

### 3.3 MyBatis-Plus Mapper 注解示例（仅示意）

```java
@Mapper
public interface RecommendationRuleMapper {
    @Select("SELECT * FROM recommendation_rules WHERE enabled = 1 AND FIND_IN_SET(?, scene_codes)")
    List<RecommendationRule> selectByScene(String sceneCode);

    @Select("SELECT * FROM recommendation_rules WHERE enabled = 1 AND rule_type = ? ORDER BY priority DESC")
    List<RecommendationRule> selectByRuleType(Integer ruleType);

    @Select("SELECT * FROM recommendation_rules WHERE enabled = 1 AND rule_type = ? AND FIND_IN_SET(?, trigger_product_ids)")
    List<RecommendationRule> selectByProductIds(Integer ruleType, String productIdsJson);
}
```

## 4. 引擎设计

### 4.1 入口接口

```java
/**
 * 推荐上下文
 */
public class RecommendationContext {
    private Long userId;          // 登录用户ID
    private Long familyId;        // 家庭ID（scene 为 family 时必填）
    private Long memberId;        // 成员ID（scope=individual 时）
    private String scene;         // 生效场景代码：dimension_page, mall_home, product_detail, after_order, report_related
    private Long currentProductId; // 商品详情页/下单页的当前商品ID
    private List<Long> excludeProductIds; // 用户自行排除的商品ID（如已选/不喜欢）
    private Integer limit;        // 返回上限，默认6
}
```

```java
/**
 * 推荐结果项
 */
public class RecommendedProduct {
    private Long productId;
    private String name;
    private String coverImage;
    private Integer price; // 分
    private String reason; // 推荐理由
    private Double matchScore; // 匹配分
    private Integer ruleId; // 触发该结果的规则ID
    private Integer ruleType; // 规则类型 1-5
    private Integer priority; // 该规则优先级
    private String source; // 来源标识：engine/campaign/...
}
```

```java
/**
 * 引擎核心方法
 */
public interface RecommendationRuleEngine {
    /**
     * 计算推荐
     * @param ctx 推荐上下文
     * @param limit 若覆盖默认limit，可传；否则用 ctx.limit
     * @return 推荐列表
     */
    List<RecommendedProduct> recommend(RecommendationContext ctx, Integer limit);
}
```

### 4.2 处理流程（按 priority 降序遍历规则）

```
1. 加载规则
   - 根据 scene 匹配 `scene_codes`（精确匹配 JSON 中的字符串）
   - enabled=1，按 priority DESC 排序

2. 查购买记录
   - scope=family：查 family_members 关联的订单（ProductOrder 中 familyId 匹配）
   - scope=individual：查 buyerId(userId) 的订单
   - 状态过滤：status in ("已支付", "completed")
   - 时间窗口：time_window_days 为 null 或 返回的时间差 <= time_window_days
     若为 null，默认使用全局配置 default_purchased_exclude_days（默认 90）

3. 构建候选池（场景基础候选）
   - dimension_page → 维度匹配商品（已有 ProductRecommendationService 逻辑）
   - mall_home      → 全量上架在售商品（product status=on_shelf, stock>0）
   - product_detail → 从规则3/5 中命中的 targetProductId
   - after_order    → 从规则3/5 中命中的 targetProductId
   - report_related → 报告提取的弱维度商品（已有 extractDimensionNeedsFromHealth/FromCognitive）

4. 应用规则（按 priority 从高到低遍历已加载的规则）

   4.1 规则4（购买A不推B）
       - 条件：已购买 trigger_product_id
       - 动作：从候选池移除 target_product_id
       - 若未命中则跳过

   4.2 规则1（已购不推）
       - 条件：已购买 trigger_product_id（或全局默认已购窗口内任意商品）
       - 动作：从候选池移除 target_product_id
       - 若未命中则跳过（已购默认由 step2/3 在全局层面完成，规则1只作特定覆盖）

   4.3 规则3（购买A推B）
       - 条件：已购买 trigger_product_id
       - 动作：将 target_product_id 加入候选池 + reason="根据您的购买记录推荐"
       - 若候选池已有该productId，则不重复添加，仅更新 reason

   4.4 规则5（系列重点推）
       - 条件：已购买 trigger_product_ids 中的 ALL 个商品
       - 动作：将 target_product_id 加入候选池 + priority 加 10（提升排序位置）

   4.5 规则2（定时复购）
       - 条件：已购买 trigger_product_id 且（当前日期 - 购买日期） >= delay_days
       - 动作：将 target_product_id 加入候选池 + reason="该商品您已购买，可考虑复购"
       - 建议 delay_days 默认值：30

5. 结果排序 & 截断
   - 按 (priority DESC, matchScore DESC) 排序
   - 截断 limit（默认6）

6. 返回结果
   - List<RecommendedProduct>，每项含 productId, name, coverImage, price, reason, matchScore, ruleId, ruleType, priority, source
```

### 4.3 规则语义表

| 规则 | rule_type | 触发 | 动作 | 关键字段 |
|------|-----------|------|------|---------|
| 1 已购不推 | 1 | 购买 trigger_product（或全局已购窗口内任意） | 从候选排除 target_product | trigger_product_id, target_product_id, time_window_days |
| 2 定时复购 | 2 | 购买 trigger_product 且距今>=delay_days | target_product 加入候选（复购） | delay_days, target_product_id |
| 3 购买A推B | 3 | 购买 trigger_product(A) | target_product(B) 加入候选 | trigger_product_id, target_product_id |
| 4 购买A不推B | 4 | 购买 trigger_product(A) | 从候选排除 target_product(B) | trigger_product_id, target_product_id |
| 5 系列重点推 | 5 | 购买 trigger_product_ids 全部 | target_product 加入候选 + boost | trigger_product_ids, target_product_id |

### 4.4 全局默认已购排除

- 系统级配置 `default_purchased_exclude_days`（默认 90 天），存入 application.yml 或系统参数表
- 引擎在 step2 查购买记录阶段，scope=family 时查 family 成员订单，scope=individual 时查 buyerId 订单
- 无论规则1是否配置，所有候选商品在进入 step4 前都已过滤掉回溯窗口内的已购商品（作为兜底）
- 规则1 仅作“特定商品覆盖”：如 trigger_product_id=123，time_window_days=180，则仅将商品123 的购买记录从候选排除（放宽或收窄默认 90 天）

## 5. 现有实现迁移

| 现有代码/组件 | 迁移动作 |
|--------------|----------|
| `ProductRecommendationService.getDimensionRecommendations` | 改为调用 `engine.recommend(ctx.scene="dimension_page")`，ctx.limit=6 |
| `getPurchasedProductIds(familyId, 90)` 硬编码 90 天 | 移除该方法，改为在引擎内读 `default_purchased_exclude_days` |
| `RepurchaseReminderService.scanAndCreateReminders` @Scheduled | **保留**（不做改动，但内部配置读取改为从规则表读；rule_type=2 的 config 从 recommendation_rules 读，旧 `repurchase_reminder_config` 表数据迁移），外部定时任务仍可继续生成 reminder 记录 |
| `repurchase_reminder_config` 表 | **保留**（点击/购买追踪表），不做结构变更，仅在新引擎规则2 中通过 rule_type 匹配 |
| `ContentRecommendService.getPurchasedProductIds` | 复用引擎的全局已购排除能力 |
| API Controller（维度页推荐） | 不改接口签名，内部改调用 engine.recommend，返回结果自动映射为 Map<String,Object> 格式 |
| 新增 API 接口（可选） | 若前端需要更多场景，可在 `POST /api/recommend/*` 下新增，内部同样调用 engine.recommend |

## 6. 管理端（cfc-web）

### 6.1 页面：商品推荐规则

- **列表**：分页 + rule_type / enabled / priority 筛选 + 排序
- **新建/编辑**：
  - rule_type：1-5 下拉
  - rule_name：文本
  - trigger_product_id / trigger_product_ids：商品选择器（支持搜索、多选）
  - target_product_id：目标商品选择器
  - priority：数字输入（整数，默认 10）
  - enabled：开关
  - time_window_days：整数（天，默认 90）
  - delay_days：整数（天，默认 30，仅规则2）
  - scope：single/family 单选
  - scene_codes：多行文本/标签选择器（可选：dimension_page, mall_home, product_detail, after_order, report_related）

### 6.2 管理端 API

- `GET /api/admin/recommendation-rules` - 分页列表
- `POST /api/admin/recommendation-rules` - 新建
- `PUT /api/admin/recommendation-rules/{id}` - 编辑
- `DELETE /api/admin/recommendation-rules/{id}` - 物理删除（慎用，建议设 enabled=0 停用）
- `POST /api/admin/recommendation-rules/batch-enable` - 批量启用/停用

## 7. 容错与降级

1. **规则表为空时**：引擎不抛出异常，直接进入“场景基础候选”阶段（即现有行为），全局已购排除默认 90 天，返回已有候选列表。

2. **规则配置冲突**：同一规则 type 存在多条启用记录时，按 priority 降序处理，较早的生效。运营若需调整顺序，在管理端修改 priority 即可。

3. **trigger_product_id 不存在**：引擎检查 trigger_product_id 是否存在于 products 表中，不存在则跳过该规则，记录 warn 日志。

4. **scene_codes 匹配失败**：
   - 引擎首先尝试精确匹配 `FIND_IN_SET(sceneCode, scene_codes)`
   - 若未匹配，再尝试前缀匹配（如 sceneCode 为 "dimension_page"，scene_codes 包含 "dimension" 也视为匹配）
   - 作为最后兜底，若 scene_codes 为空字符串 `""`，视为“所有场景生效”

5. **时间窗口边界**：
   - time_window_days=0 表示“只计算今日购买”
   - time_window_days<0 视为异常，引擎取绝对值但标记日志警告

## 8. 测试要点

1. **规则单独生效**：
   - 规则1：已购特定商品（180天）从候选排除
   - 规则2：30天后出现复购推荐
   - 规则3：购买A后推B
   - 规则4：购买A后不推B
   - 规则5：购买A+B+C系列后重点推X

2. **优先级排序**：
   - 验证 priority 从高到低的处理顺序
   - 验证同 priority 时，matchScore DESC

3. **scope family/individual**：
   - family：查 familyId 关联订单
   - individual：查 buyerId(userId) 订单

4. **time_window_days 边界**：0、90、365 各自行为

5. **降级测试**：
   - 删除所有规则记录，验证系统仍能返回推荐（退化为全局已购排除 + 基础候选）
   - 验证旧定时任务仍正常工作

6. **编译验证**：`mvn clean compile`

## 9. 变更清单

### 9.1 数据库

```sql
-- 新建表（迁移编号自行在 DatabaseInitializer 末尾递增）
CREATE TABLE recommendation_rules (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    rule_type TINYINT NOT NULL COMMENT '1-5',
    rule_name VARCHAR(100) COMMENT '运营名称',
    trigger_product_id BIGINT COMMENT '触发商品ID',
    trigger_product_ids VARCHAR(1000) COMMENT '触发商品ID JSON 数组',
    target_product_id BIGINT COMMENT '目标商品ID',
    priority INT DEFAULT 10 COMMENT '优先级，越大越优',
    enabled TINYINT DEFAULT 1 COMMENT '启用 1/0',
    time_window_days INT COMMENT '回溯窗口(天)',
    delay_days INT COMMENT '复购延迟天数',
    scope VARCHAR(20) COMMENT 'family/individual',
    scene_codes VARCHAR(500) COMMENT '生效场景 JSON 数组',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

-- 建议索引
CREATE INDEX idx_rules_enabled ON recommendation_rules(enabled);
CREATE INDEX idx_rules_scene ON recommendation_rules(scene_codes);
CREATE INDEX idx_rules_priority ON recommendation_rules(priority);
```

### 9.2 Java 代码变更

- 新增 `entity/RecommendationRule.java`
- 新增 `mapper/RecommendationRuleMapper.java`
- 新增 `service/RecommendationRuleService.java`（CRUD + 规则校验）
- 新增 `service/RecommendationRuleEngine.java`（核心计算逻辑）
- 新增 `controller/recommendation/RecommendationRuleAdminController.java`（管理端 API）
- 修改 `service/ProductRecommendationService.java` → 改为调用 engine.recommend
- 修改 `service/RepurchaseReminderService.java` → rule_type=2 配置读取改为从 recommendation_rules
- 删除/废弃 `repurchase_reminder_config` 业务逻辑（保留表结构）

### 9.3 API 变更（后端）

- 维度页推荐：`POST /api/recommend/dimension-products` 不变，内部实现改调用 engine
- 新增（如需要）：`POST /api/recommend/mall-home`、`POST /api/recommend/product-detail`、`POST /api/recommend/after-order`、`POST /api/recommend/report-related`

### 9.4 Web管理端

- 新增页面：`/admin/recommendation-rules`（Vue 2 + Element UI，遵循项目现有设计规范）
- 权限：role=admin 或 role=teacher

## 10. 完成标准

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