CPS联盟返利系统 - 深度分析报告

一、参考项目架构分析

1.1 技术栈对比

维度	参考项目 (MSHOP/SFB)	目标项目 (AgenticCPS)
后端框架	Spring Boot 2.6.7	Spring Boot 3.5.9
ORM	MyBatis-Plus 3.5.1	MyBatis-Plus 3.5.15
前端	Vue 2.7 + Element UI	Vue 3.5 + Element Plus + TypeScript
移动端	Flutter 3.0	UniApp
安全框架	Spring Security + JWT	Spring Security 6.5.2
AI能力	无	Spring AI + MCP Protocol
定时任务	Quartz	yudao-spring-boot-starter-job (Quartz封装)
多租户	不支持	支持 (tenant_id)

1.2 参考项目模块结构

复制代码

sfb_server/
├── mshop-admin/     # 管理后台API + 定时任务（Quartz）
├── mshop-app/       # 用户端API（转链、搜索）
├── mshop-shop/      # 商城核心业务
├── mshop-store/     # 数据层 + 服务层（Domain/Service/Config/VO）
└── mshop-system/    # 系统基础服务

1.3 参考项目CPS核心实现

转链服务链路：

TkService.mixParse() -- 智能识别输入类型（URL/淘口令/关键词），路由到对应平台
DataokeService -- 大淘客聚合API封装（淘宝/京东/拼多多/唯品会）
KuService -- 好单库聚合API封装（抖音/美团/饿了么）
各平台Controller（DataokeController/DataokeJDController/DataokePDDController/DataokeDyController）

订单采集链路：

OrderTask (基类) -- 通用订单保存、用户归因、佣金计算逻辑
TbOrderCollectionTask -- 淘宝订单采集（每10分钟）
JdOrderCollectionTask -- 京东订单采集
PddOrderCollectionTask -- 拼多多订单采集
DyOrderCollectionTask -- 抖音订单采集
OrderRefundTask -- 订单失效扣款处理
FeeTodayTask / FeeMonthTask -- 佣金统计汇总

关键设计差异（需要适配改造）：

参考项目每个平台独立订单表 （mw_order_tb, mw_order_jd...），目标项目使用统一订单表（yudao_cps_order）
参考项目通过第三方聚合API（大淘客/好单库）间接对接，目标项目通过CpsPlatformClient策略模式直接适配
参考项目的返利通过Redis PID池+渠道ID绑定归因，目标项目使用external_info外部追踪参数归因
参考项目金额用BigDecimal存储，目标项目SQL设计使用decimal(10,2)（需注意AGENTS.md要求用Integer分存储的约定）

二、目标项目现状评估

2.1 已完成的工作

项目	状态	说明
数据库设计	已完成	`backend/sql/module/cps-all-in-one.sql` 定义了13张核心表
MCP配置	已完成	`application.yaml` 中已配置MCP Server
架构规范	已完成	`AGENTS.md` 和 `codegen-rules.md` 定义了代码生成规范
基础模块	已就绪	member/pay/mall/system/infra/ai 模块均已存在

2.2 尚未完成的工作

项目	状态	说明
CPS Maven模块	未创建	`backend/pom.xml` 中未包含 yudao-module-cps
CPS Java代码	未编写	无Controller/Service/Mapper/DO/VO代码
CPS前端页面	未开发	管理后台和会员端均无CPS相关页面
CPS菜单权限	未配置	无CPS菜单SQL和权限定义
平台适配器	未实现	CpsPlatformClient接口及各平台实现类未编写
MCP Tool实现	未编写	仅有配置声明，无实际Java Tool类

三、数据库表结构详细分析

3.1 13张核心表总览

序号	表名	用途	阶段
1	yudao_cps_platform	CPS平台配置（AppKey/Secret/API地址/费率）	Phase1
2	yudao_cps_adzone	推广位PID管理（通用/渠道/用户专属）	Phase1
3	yudao_cps_order	统一CPS订单表（含冻结字段）	Phase1+7
4	yudao_cps_rebate_config	返利配置（等级+平台组合返利比例）	Phase2
5	yudao_cps_rebate_record	返利记录（入账/扣回/调整）	Phase2
6	yudao_cps_rebate_account	会员返利账户（余额/冻结/已提现）	Phase4
7	yudao_cps_withdraw	提现申请（审核+转账流程）	Phase4
8	yudao_cps_statistics	统计数据（按日+平台聚合）	Phase5
9	yudao_cps_mcp_api_key	MCP API密钥管理	Phase6
10	yudao_cps_mcp_access_log	MCP访问日志	Phase6
11	yudao_cps_transfer_record	转链记录	Phase7
12	yudao_cps_freeze_config	冻结解冻配置	Phase7
13	yudao_cps_freeze_record	冻结解冻记录	Phase7

3.2 与参考项目的表结构差异

参考项目：每个平台独立订单表，字段高度耦合于平台API返回结构

mw_order_tb (淘宝): trade_parent_id, adzone_id, channel_pid, tb_paid_time, pub_share_rate...
mw_order_jd (京东): skuId, unionId, subUnionId, validCode...
mw_order_pdd (拼多多): goods_id, custom_parameters, order_verify_time...

目标项目 ：统一订单表 yudao_cps_order，通过 platform_code 区分平台

优势：统一查询、统一状态流转、简化返利计算
挑战：需要在适配器层做好各平台字段映射

3.3 金额存储方式注意

当前SQL使用 decimal(10,2)，但 AGENTS.md 规定 "Integer for money: Never use Double/BigDecimal for monetary amounts -- always use Integer (cents)"。

建议：在Java代码层面使用Integer（分），SQL层使用decimal但通过DO映射时转换为分。或统一修改SQL为bigint存储分。这是一个需要在实施前确认的关键决策点。

四、CPS模块架构设计

4.1 Maven模块结构

复制代码

yudao-module-cps/
├── yudao-module-cps-api/          # API定义层（供其他模块引用）
│   ├── pom.xml
│   └── src/main/java/.../module/cps/
│       ├── api/                   # 远程服务接口（CpsOrderApi等）
│       └── enums/                 # 枚举定义
│           ├── CpsPlatformCodeEnum.java      # 平台编码枚举
│           ├── CpsOrderStatusEnum.java       # 订单状态枚举
│           ├── CpsRebateTypeEnum.java        # 返利类型枚举
│           ├── CpsRebateStatusEnum.java      # 返利状态枚举
│           ├── CpsWithdrawStatusEnum.java    # 提现状态枚举
│           ├── CpsAdzoneTypeEnum.java        # 推广位类型枚举
│           ├── CpsFreezeStatusEnum.java      # 冻结状态枚举
│           └── CpsErrorCodeConstants.java    # 错误码常量
│
└── yudao-module-cps-biz/          # 业务实现层
    ├── pom.xml
    └── src/main/java/.../module/cps/
        ├── controller/
        │   ├── admin/             # 管理后台API（15+接口）
        │   │   ├── CpsPlatformController.java
        │   │   ├── CpsAdzoneController.java
        │   │   ├── CpsOrderController.java
        │   │   ├── CpsRebateConfigController.java
        │   │   ├── CpsRebateRecordController.java
        │   │   ├── CpsRebateAccountController.java
        │   │   ├── CpsWithdrawController.java
        │   │   ├── CpsStatisticsController.java
        │   │   ├── CpsMcpApiKeyController.java
        │   │   ├── CpsMcpAccessLogController.java
        │   │   ├── CpsTransferRecordController.java
        │   │   ├── CpsFreezeConfigController.java
        │   │   ├── CpsFreezeRecordController.java
        │   │   └── vo/            # 各Controller的请求/响应VO
        │   └── app/               # 会员端API（13+接口）
        │       ├── AppCpsGoodsController.java     # 商品搜索/比价/详情
        │       ├── AppCpsLinkController.java       # 推广链接生成
        │       ├── AppCpsOrderController.java      # 我的订单
        │       ├── AppCpsRebateController.java     # 返利汇总/明细
        │       ├── AppCpsWithdrawController.java   # 提现申请/记录
        │       ├── AppCpsSearchController.java     # 搜索历史/热词
        │       └── vo/
        ├── service/
        │   ├── platform/          # 平台配置管理服务
        │   ├── adzone/            # 推广位管理服务
        │   ├── order/             # 订单管理服务（同步/归因/状态流转）
        │   ├── rebate/            # 返利服务（配置/计算/记录/账户）
        │   ├── withdraw/          # 提现服务
        │   ├── statistics/        # 统计服务
        │   ├── goods/             # 商品搜索/比价服务
        │   ├── link/              # 转链服务
        │   ├── freeze/            # 冻结解冻服务
        │   └── mcp/               # MCP管理服务
        ├── client/                # 平台适配器层（策略模式）
        │   ├── CpsPlatformClient.java              # 适配器接口
        │   ├── CpsPlatformClientFactory.java        # 工厂类
        │   ├── dto/               # 适配器DTO（请求/响应）
        │   ├── taobao/            # 淘宝联盟适配器
        │   │   └── TaobaoPlatformClient.java
        │   ├── jingdong/          # 京东联盟适配器
        │   │   └── JingdongPlatformClient.java
        │   ├── pinduoduo/         # 拼多多联盟适配器
        │   │   └── PinduoduoPlatformClient.java
        │   └── douyin/            # 抖音联盟适配器
        │       └── DouyinPlatformClient.java
        ├── dal/                   # 数据访问层
        │   ├── dataobject/        # DO类（13个，对应13张表）
        │   └── mysql/             # Mapper接口（13个）
        ├── job/                   # 定时任务
        │   ├── CpsOrderSyncJob.java             # 订单同步任务
        │   ├── CpsRebateSettleJob.java           # 返利结算任务
        │   ├── CpsStatisticsJob.java             # 统计汇总任务
        │   ├── CpsFreezeUnfreezeJob.java         # 冻结解冻任务
        │   └── CpsOrderRefundJob.java            # 退款处理任务
        ├── mcp/                   # MCP AI接口层
        │   ├── CpsMcpTools.java                  # 5个AI Tools实现
        │   ├── CpsMcpResources.java              # 只读数据资源
        │   └── CpsMcpPrompts.java                # 预设交互模板
        └── framework/             # 框架配置
            └── CpsConfiguration.java

4.2 CpsPlatformClient 策略模式接口

java 复制代码

public interface CpsPlatformClient {
    String getPlatformCode();
    CpsGoodsSearchResult searchGoods(CpsGoodsSearchRequest request);
    CpsGoodsDetail getGoodsDetail(CpsGoodsDetailRequest request);
    CpsParsedContent parseContent(String content);
    CpsPromotionLink generatePromotionLink(CpsPromotionLinkRequest request);
    List<CpsOrderDTO> queryOrders(CpsOrderQueryRequest request);
    boolean testConnection();
}

与参考项目的适配策略：

参考项目通过大淘客/好单库聚合API间接调用，可在适配器内部复用此模式
淘宝适配器内部可封装对大淘客API的调用（DataokeService的逻辑）
也可直接对接各平台官方联盟API（淘宝联盟/京东联盟/多多进宝等）

五、模块集成方案

5.1 与Member模块的集成

集成点：

会员等级查询 -- CPS返利计算需要获取会员等级，通过 MemberLevelApi 远程调用
会员信息查询 -- 订单归因后需要会员昵称等信息，通过 MemberUserApi
经验值奖励 -- CPS订单为会员贡献经验值，通过 MemberPointApi

实现方式 ：在 yudao-module-cps-biz/pom.xml 中依赖 yudao-module-member，通过Spring Bean注入API

5.2 与Pay模块的集成

集成点：

钱包余额操作 -- 返利入账/扣回需操作会员钱包，通过 PayWalletApi
转账打款 -- 提现打款到支付宝/微信，通过 PayTransferApi

注意：PRD中提到CPS有独立的返利账户表 yudao_cps_rebate_account，与Pay模块的 PayWalletDO 是独立的。需要确认是否复用Pay钱包还是使用CPS独立账户。

建议方案：CPS使用独立返利账户管理（yudao_cps_rebate_account），提现时通过Pay模块的转账API打款。这样CPS模块对Pay模块的依赖最小化。

5.3 与System模块的集成

集成点：

菜单权限 -- CPS管理后台菜单注册到system菜单表
数据字典 -- CPS相关枚举值注册到字典表（平台类型、订单状态等）
操作日志 -- CPS关键操作记录审计日志

5.4 与AI模块的集成

集成点：

MCP Server -- CPS的MCP Tools通过Spring AI的@Tool注解暴露
AI Agent -- 可通过AI模块的聊天接口调用CPS MCP Tools

六、核心业务流程详解

6.1 商品搜索流程

复制代码

用户输入 → AppCpsGoodsController.search()
    → CpsGoodsService.search()
        → 智能识别输入类型(URL/口令/关键词)
        → CpsPlatformClientFactory.getClient(platformCode)
        → client.searchGoods() / client.parseContent()
        → 聚合结果 + 计算预估返利(基于会员等级)
    → 返回统一格式商品列表

参考项目对应 ：TkService.mixParse() + DataokeService + KuService

6.2 推广链接生成流程

复制代码

用户选择商品 → AppCpsLinkController.generate()
    → CpsLinkService.generateLink()
        → 获取推广位(会员专属 > 渠道 > 默认)
        → 注入归因参数(external_info = memberId)
        → CpsPlatformClient.generatePromotionLink()
        → 保存转链记录(yudao_cps_transfer_record)
    → 返回推广链接/淘口令

参考项目对应 ：DataokeController.goodsParse() + DataokeService 转链逻辑

6.3 订单同步流程

复制代码

定时任务(每5分钟) → CpsOrderSyncJob.execute()
    → 遍历所有启用平台
    → CpsPlatformClient.queryOrders(增量时间范围)
    → 对每笔订单:
        → 新订单: 解析归因参数 → 匹配会员 → 入库(yudao_cps_order)
        → 已有订单: 检查状态变化 → 更新状态
        → 状态变为"已结算": 触发返利结算
        → 状态变为"已退款": 触发返利扣回

参考项目对应 ：OrderTask.saveTb()/saveJd()/savePdd() + 各平台 *OrderCollectionTask

6.4 返利计算流程

复制代码

订单结算 → CpsRebateService.settleRebate(order)
    → 计算可分配佣金 = 佣金 - 平台服务费
    → 查询返利比例(6级优先级):
        1. 会员个人配置(精确平台)
        2. 会员个人配置(全平台)
        3. 等级+平台组合
        4. 等级全平台
        5. 平台默认
        6. 全局默认
    → 返利金额 = 可分配佣金 x 返利比例
    → 创建返利记录(yudao_cps_rebate_record)
    → 创建冻结记录(yudao_cps_freeze_record)
    → 更新返利账户冻结余额(yudao_cps_rebate_account)
    → 通知会员

参考项目对应 ：OrderTask 中的佣金计算逻辑 + FeeTodayTask/FeeMonthTask

6.5 冻结解冻流程

复制代码

定时任务 → CpsFreezeUnfreezeJob.execute()
    → 查询到期的冻结记录(unfreeze_time <= NOW)
    → 更新冻结记录状态为"已解冻"
    → 更新订单冻结状态
    → 返利账户: 冻结余额减少, 可用余额增加
    → 通知会员返利到账

6.6 提现流程

复制代码

会员申请 → AppCpsWithdrawController.create()
    → CpsWithdrawService.createWithdraw()
        → 校验: 余额/最低金额/次数限制/黑名单
        → 扣减可用余额(乐观锁)
        → 创建提现记录(yudao_cps_withdraw)
        → 金额 <= 阈值? 自动审核 : 人工审核
    → 审核通过 → 调用Pay模块转账API → 更新打款状态

七、集成难点与风险评估

7.1 高风险项

风险	说明	建议
金额存储方式	SQL用decimal，AGENTS.md要求Integer(分)	统一为Integer(分)，修改SQL
平台API对接	各平台联盟API文档和签名机制不同	优先通过聚合API(大淘客)，降低对接成本
订单归因准确率	归因参数丢失或被篡改	多重归因策略 + 手动绑定兜底
并发安全	返利账户余额操作需保证原子性	乐观锁(version字段) + 分布式锁(Redisson)

7.2 中风险项

风险	说明	建议
CPS与Pay钱包的关系	独立账户 vs 复用Pay钱包	建议使用独立CPS账户，提现时对接Pay
MCP Server实现	Spring AI MCP Server较新	参考Spring AI官方示例
多租户隔离	CPS数据需要租户隔离	所有CPS表需要加 tenant_id 字段

7.3 低风险项

风险	说明	建议
前端页面开发	管理后台CRUD页面	使用代码生成器自动生成
定时任务配置	复用yudao-spring-boot-starter-job	标准实现，风险低

八、建议实施步骤（分7个Phase）

Phase 1: 基础框架搭建（预计2-3天）

Task 1.1: 创建 yudao-module-cps Maven模块（api + biz）
Task 1.2: 配置pom.xml依赖、注册到yudao-server
Task 1.3: 导入CPS数据库表（修正金额字段为Integer/分）
Task 1.4: 生成CPS平台配置和推广位的CRUD代码（DO/Mapper/Service/Controller/VO）
Task 1.5: 定义CPS枚举类和错误码
Task 1.6: 生成前端管理页面（平台配置、推广位管理）
Task 1.7: 配置CPS菜单和权限SQL

Phase 2: 核心功能开发（预计3-5天）

Task 2.1: 实现CpsPlatformClient接口和工厂类
Task 2.2: 实现淘宝联盟适配器（商品搜索/转链/订单查询）
Task 2.3: 实现京东联盟适配器
Task 2.4: 实现拼多多联盟适配器
Task 2.5: 实现抖音联盟适配器
Task 2.6: 实现商品搜索/比价服务和会员端API
Task 2.7: 实现推广链接生成服务和会员端API
Task 2.8: 实现返利配置CRUD（管理后台）

Phase 3: 订单与结算（预计3-5天）

Task 3.1: 实现订单同步定时任务（CpsOrderSyncJob）
Task 3.2: 实现订单归因匹配逻辑
Task 3.3: 实现返利计算引擎（6级优先级）
Task 3.4: 实现返利记录CRUD
Task 3.5: 实现订单管理（管理后台 + 会员端）
Task 3.6: 实现手动订单同步和异常订单处理

Phase 4: 会员与提现（预计2-3天）

Task 4.1: 实现会员返利账户管理
Task 4.2: 实现返利入账和扣回逻辑（含乐观锁）
Task 4.3: 实现提现申请流程
Task 4.4: 实现提现审核和打款对接
Task 4.5: 实现会员端返利汇总/明细API

Phase 5: 数据统计（预计1-2天）

Task 5.1: 实现统计数据汇总定时任务
Task 5.2: 实现运营数据看板API
Task 5.3: 实现平台统计和趋势图表API
Task 5.4: 开发前端统计页面（图表+看板）

Phase 6: MCP AI接口（预计2-3天）

Task 6.1: 实现5个MCP Tools（搜索/比价/转链/订单/返利）
Task 6.2: 实现MCP Resources（平台配置/统计数据）
Task 6.3: 实现MCP API Key管理和访问日志
Task 6.4: 测试AI Agent通过MCP调用CPS功能

Phase 7: 优化与完善（预计2-3天）

Task 7.1: 实现转链记录管理
Task 7.2: 实现冻结解冻配置和定时任务
Task 7.3: 实现风控规则（频率限制/黑名单）
Task 7.4: 性能优化（缓存/索引/并发查询）
Task 7.5: 单元测试和集成测试
Task 7.6: 文档完善

九、关键决策待确认

在开始实施前，需要确认以下关键决策：

金额存储方式 ：SQL表使用 decimal(10,2) 还是改为 bigint（分），Java层使用 Integer 还是 BigDecimal？
平台对接方式：直接对接各平台联盟官方API，还是通过聚合API（如大淘客）间接对接？
CPS账户 vs Pay钱包：使用独立CPS返利账户，还是复用Pay模块的钱包系统？
多租户支持 ：当前SQL表缺少 tenant_id 字段，是否需要补充？
各Phase实施优先级：是否按上述顺序实施，还是有调整需求？