RatingRecommend

卡牌评级小程序 推荐服务

架构概览

本服务是卡牌评级小程序的「评级时效推荐 + 卡片行情详情 + 数仓规则同步 + AI 业务助手」中台，采用 DDD 五模块分层。下面先用一张关系图展示三类请求（小程序推荐/详情、内部规则同步、AI 会话）从入口到落库/落 Redis 的调用流转，再用映射表、依赖树与要点说明逐层拆解真实组件。

                          ┌───────────────────────────────────────────┐
                          │   小程序端 / 内部同步端 (mango-application)   │
                          │  RecommendController   CardController        │
                          │  RuleSyncController     AiChatController(SSE) │
                          └───────────────────────────────────────────┘
                                              │  @PostMapping + @ApiLog(AOP)
                                              ▼
        ┌────────────────────────── 领域服务层 (mango-domain) ──────────────────────────┐
        │  RecommendServiceImpl   CardDetailServiceImpl   RuleSyncServiceImpl   AiChatService │
        │        │                      │                      │                    │        │
        │        ▼ 内存纯算法            │                      │                    ▼        │
        │  RuleMatcher(L0~L3降级)        │                      │           AgentLoopExecutor  │
        │  OrderGrouper(按时效分单)      │                      │           ClaudeChatProvider │
        │  EfficiencyPriceProvider       │                      │           ToolRegistry       │
        │  LoginUserProvider             │                      │           (工具: 物流查询)   │
        └────────┬──────────────────────┴──────────┬───────────┴──────────┬───────────────────┘
                 │ Manager 聚合                     │ Manager 聚合          │
                 ▼                                  ▼                       ▼
        ┌─────────────── Manager 层 (mango-manager) ───────────────┐   ┌──── 横切 / 外部依赖 ────┐
        │ RatingRecommendRuleManager  CardPopManager               │   │ Feign:                  │
        │ CardValueHistoryManager     ActiveBatchManager           │   │  rating-app-preorder    │
        │ UserAddressManager                                       │   │  rating-app-order       │
        └────────────────────────┬─────────────────────────────────┘   │  order-service          │
                                  │ @Mapper 单表 SQL                     │  pay-service            │
                                  ▼                                      │ Redis: 会话/字典缓存    │
        ┌────────── Mapper/XML 层 (mango-infrastructure) ──────────┐   │ Redisson: 分布式锁工具  │
        │ RatingRecommendRuleMapper  CardPopMapper                 │   │ Shiro: 认证/在线会话    │
        │ CardValueHistoryMapper     ActiveBatchMapper  ...        │   └─────────────────────────┘
        └────────────────────────┬─────────────────────────────────┘
                                  ▼
                          ┌───────────────┐
                          │  PostgreSQL    │
                          │ t_rating_*     │
                          └───────────────┘

  说明：推荐服务本身不写业务订单库，预订单落库通过 Feign 远程交由 rating-app（PreOrderApiClient）。

详细映射关系表

接口分区	核心 Controller	领域 Service	核心实体(PO) 与表	使用场景
小程序-评级时效推荐 /api/recommend/efficiency	RecommendController	RecommendServiceImpl	RatingRecommendRulePO → t_rating_recommend_rule	批量卡片按规则匹配推荐时效、按时效分单报价、Feign 生成预订单
小程序-卡片详情趋势 /api/recommend/card/detail	CardController	CardDetailServiceImpl	CardPopPO → t_rating_card_pop；CardValueHistoryPO → t_rating_card_value_history	查卡片身份/POP 榜/行情/价格趋势曲线
内部-数仓规则同步 /api/recommend/rule/sync	RuleSyncController(Token 鉴权)	RuleSyncServiceImpl	RatingRecommendRulePO、ActiveBatchPO → t_rating_recommend_active_batch	数仓全量推送规则/POP/价格历史，单事务全量替换 + 切生效批次
小程序-AI 业务助手 /api/ai/chat/stream	AiChatController(SSE 流式)	AiChatService	会话上下文存 Redis(SessionContextStore)	多轮对话 + 工具调用（订单物流查询），Claude 流式打字机输出

服务依赖关系

RecommendServiceImpl
├── RatingRecommendRuleManager      # 批量捞候选规则(按 series+cardSet / series+role)
├── ActiveBatchManager              # 读当前生效批次号
├── RuleMatcher (纯算法)            # 分类前提过滤 + L0~L3 降级 + 多候选取舍
├── OrderGrouper (纯算法)           # 按推荐时效精确分单
├── EfficiencyPriceProvider ──► order-service  # 拉时效字典(名称+单价)
├── LoginUserProvider               # 取当前登录用户
└── PreOrderApiClient ──► rating-app-preorder  # Feign 远程落库预订单

CardDetailServiceImpl
├── RatingRecommendRuleManager      # 卡片身份+行情
├── CardPopManager                  # POP 榜明细
├── CardValueHistoryManager         # 价格趋势
└── ActiveBatchManager              # 生效批次隔离

RuleSyncServiceImpl
├── RatingRecommendRuleManager / CardPopManager / CardValueHistoryManager
└── ActiveBatchManager              # 防回灌校验 + 切换生效批次指针

AiChatService
├── SessionContextStore ──► Redis   # 多轮会话上下文
├── AgentLoopExecutor ──► ClaudeChatProvider(anthropic)  # Agent 循环 + 模型调用
└── ToolRegistry └── OrderLogisticsQueryTool ──► rating-app-order  # 工具回调 Feign

关键架构说明

1. DDD 分层职责

• mango-application: 启动类 RatingRecommendApplication（端口 8094），四个 app.controller，接口统一 @PostMapping；@ApiLog AOP 记录操作日志。
• mango-domain: 领域服务实现、推荐纯算法（RuleMatcher/OrderGrouper）、Feign 客户端与其封装（PreOrderApiClient/OrderApiClient）、AI Agent 相关组件。
• mango-manager: XxxManager 聚合 Mapper，仅注入 Mapper 接口，做单表查询/批量写的简单封装。
• mango-infrastructure: @Mapper 接口 + XML 单表 SQL、MybatisPlusConfig（PostgreSQL 分页）。
• mango-common: PO、DTO/Request/Response、枚举、RecommendProperties/AiAssistantProperties 配置、RedisUtils/RedissonLockUtil 工具、Shiro 认证等共享内核。

2. 评级时效推荐核心流程（业务主线）

• 批量捞规则: 按 cardType 分派收窄键——宝可梦卡(cardType=1)用 (series, role)、其它用 (series, cardSet)，一次批量查询消除 N+1。
• 降级匹配: RuleMatcher 先做分类前提过滤（cardType/sportEvent/ipName/team/rule 入参有值才约束），再按 L0 → L1 → EXACT → L2 → L3 逐层降级，多候选按「生效时间→推荐时效→id」取最优；全部落空按 cardType 兜底默认档。
• 分单与报价: OrderGrouper 按推荐时效精确分组为多个订单建议；EfficiencyPriceProvider 从 order-service 拉时效字典回填名称+单价，缺价降级为「待计算」。
• 不落业务库: 推荐服务自身不写订单库，组装 PreOrderSaveDTO 后经 PreOrderApiClient Feign 远程交由 rating-app 落库并返回 preOrderNo。

3. 数仓规则同步与批次隔离

• 单事务全量替换: @Transactional 内完成「防回灌校验(新批次号必须大于生效批次) → cardId 去重 → 删本批次残留+批量插 → 价格历史增量 UPSERT → 切生效批次指针 → 清理更早批次(保留新批次+原生效批次供回滚)」。
• 空批次保护: 拒绝空 cards 批次，避免全表清空导致推荐全走兜底。
• 读写隔离: 所有查询以 ActiveBatchManager.selectActiveBatchNo() 的生效批次号为隔离维度，切指针即原子生效。
• 内部鉴权: 同步接口用 X-Sync-Token 头做 Token 校验，防外部乱调写脏数据。

4. AI 业务助手（Agent 工具调用）

• SSE 流式: AiChatController 用 SseEmitter + 专用线程池 aiChatExecutor 打字机式回写。
• Agent 循环: AgentLoopExecutor 驱动「模型输出 → 工具调用(tool_use) → 工具结果(tool_result) → 再问模型」的多轮循环，模型侧为 ClaudeChatProvider（anthropic）。
• 工具与身份透传: ToolRegistry 注册工具（如 OrderLogisticsQueryTool），工具经 Feign 调 rating-app 时透传 X-USER-BASE64 原始用户头做身份隔离。
• 上下文管理: SessionContextStore 将精简后的多轮上下文（剔除工具中间态）存入 Redis，带 TTL。

5. 外部依赖与横切能力

• Feign 外部服务: rating-app-preorder（预订单落库）、rating-app-order（订单/物流工具）、order-service（时效字典）、pay-service（支付），统一经 TraceIdFeignInterceptor 透传链路 ID。
• Redis: 承载 AI 会话上下文与缓存（GenericJackson2JsonRedisSerializer）。
• Redisson / Shiro: RedissonLockUtil 提供分布式锁模板；Shiro 负责认证与在线会话管理。