商品推荐规则引擎 — 实现计划

基于 docs/superpowers/specs/2026-09-17-product-recommendation-rule-engine-design.md

阶段 0：数据库迁移

目标：创建 recommendation_rules 表，同步 schema.sql

步骤：

在 cfc-backend/src/main/resources/schema.sql 末尾追加 CREATE TABLE recommendation_rules (...) 定义（含索引）
在 DatabaseInitializer.java 末尾的 runMigrations() 中添加新迁移（迁移编号递增，当前最大编号搜索确认）
执行 mvn clean compile 验证无编译错误

文件：

目标：基础 CRUD 能力

步骤：

新建 entity/RecommendationRule.java（对应 recommendation_rules 表，字段见设计文档 3.1）
新建 mapper/RecommendationRuleMapper.java（使用 MyBatis-Plus，提供按 scene、rule_type、enabled 查询方法）
新建 service/RecommendationRuleService.java
- listRules(sceneCode, page, size) — 分页列表
- getRuleById(id) — 详情
- createRule(rule) — 创建，含参数校验（rule_type 1-5、priority>0、trigger/target 非空等）
- updateRule(id, rule) — 更新
- deleteRule(id) — 删除（设 enabled=0，软停用）
- batchUpdateEnabled(ids, enabled) — 批量启用/停用
新建 controller/recommendation/RecommendationRuleAdminController.java
- POST /api/admin/recommendation-rules/list
- POST /api/admin/recommendation-rules/create
- POST /api/admin/recommendation-rules/update
- POST /api/admin/recommendation-rules/delete
- POST /api/admin/recommendation-rules/batch-enable
运行 mvn clean compile 验证

目标：RecommendationRuleEngine.recommend(ctx, limit) 完成 5 种规则计算

步骤：

新建 service/RecommendationRuleEngine.java（实现 RecommendationRuleEngine 接口）
内部方法设计：
- loadRules(String sceneCode) — 加载匹配的启用规则，按 priority DESC
- queryPurchasedProducts(RecommendationContext ctx) — 查购买记录，返回 Map<Long, Date>（productId → 最早购买日期）
- buildBaseCandidates(RecommendationContext ctx) — 按场景构建候选池（保留现有维度页推荐逻辑）
- applyRules(List<RecommendationRule> rules, Set<Long> purchasedIds, List<BaseCandidate> candidates) — 应用所有规则
  - 先处理规则4（排除类，从高 priority 开始）
  - 再处理规则1（排除类）
  - 再处理规则3（推荐类）
  - 再处理规则5（推荐类 + boost）
  - 再处理规则2（定时复购类）
- sortAndTruncate(List<BaseCandidate> candidates, int limit) — 排序截断
保留 ProductRecommendationService.getDimensionRecommendations 现有逻辑作为 buildBaseCandidates 的基础实现，但不再直接调用 getPurchasedProductIds，改由引擎统一处理
在 ProductRecommendationController.getDimensionProducts 中：
- 保留 Controller 接口签名不变
- 内部改为调用 engine.recommend(ctx, limit)，将 RecommendedProduct 映射为现有 Map<String, Object> 格式返回
运行 mvn clean compile 验证

目标：规则2 配置从 recommendation_rules 读取，旧 repurchase_reminder_config 不再被代码引用

步骤：

目标：商城首页、商品详情页、下单成功页的推荐接口

步骤：

新增 POST /api/recommend/mall-home
- 入参：{ "limit": 10 }
- 内部：engine.recommend(ctx, limit) 其中 scene="mall_home"
新增 POST /api/recommend/product-detail
- 入参：{ "productId": 123, "limit": 6 }
- 内部：engine.recommend(ctx, limit) 其中 scene="product_detail", currentProductId=123
新增 POST /api/recommend/after-order
- 入参：{ "orderId": 456, "limit": 6 }
- 内部：engine.recommend(ctx, limit) 其中 scene="after_order"
修改 ProductRecommendationService.getReportRelatedProducts
- 内部改为调用 engine.recommend(ctx, limit) 其中 scene="report_related"
运行 mvn clean compile 验证

目标：cfc-web 新增「商品推荐规则」管理页面

步骤：

在 cfc-web/src/views/ 下新建 RecommendationRules.vue
- 页面标题：商品推荐规则
- 功能：列表展示 + 新建/编辑弹窗 + 启用/停用开关
- 字段：rule_type（类型下拉）、rule_name、trigger_product_id、target_product_id、priority、enabled（开关）、scene_codes（多选）
在 cfc-web/src/router/ 下新增路由 /admin/recommendation-rules
在 cfc-web/src/api/ 下封装推荐规则接口
运行 npm run build 验证编译通过

目标：规则计算正确，降级场景正常

步骤：

新增文件	说明
`cfc-backend/.../entity/RecommendationRule.java`	新实体
`cfc-backend/.../mapper/RecommendationRuleMapper.java`	Mapper
`cfc-backend/.../service/RecommendationRuleService.java`	CRUD Service
`cfc-backend/.../service/RecommendationRuleEngine.java`	引擎核心
`cfc-backend/.../controller/recommendation/RecommendationRuleAdminController.java`	管理端 Controller
`cfc-web/src/views/RecommendationRules.vue`	管理端页面
`cfc-web/src/api/recommendationRule.js`	管理端 API 封装

修改文件	说明
`cfc-backend/.../service/ProductRecommendationService.java`	改为调用引擎
`cfc-backend/.../service/RepurchaseReminderService.java`	规则2 配置改读 recommendation_rules
`cfc-backend/.../config/DatabaseInitializer.java`	新增 DDL 迁移
`cfc-backend/src/main/resources/schema.sql`	新增 recommendation_rules 表定义
`cfc-web/src/router/index.js`	新增路由
`docs/superpowers/api/API_REFERENCE.md`	同步新增接口文档