卡牌评级小程序 推荐服务 ## 架构概览 本服务是卡牌评级小程序的「评级时效推荐 + 卡片行情详情 + 数仓规则同步 + 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 负责认证与在线会话管理。