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