CPS 联盟返利系统 — 集成分析报告

CPS 联盟返利系统 --- 集成分析报告

一、项目整体架构与模块依赖关系

1.1 现有模块清单（已就绪）

模块	路径	CPS集成角色
yudao-module-member	`backend/yudao-module-member/`	会员等级、经验值、积分 --- CPS返利比例依据
yudao-module-pay	`backend/yudao-module-pay/`	钱包余额、提现转账 --- 返利入账与提现通道
yudao-module-system	`backend/yudao-module-system/`	认证权限、菜单配置 --- CPS菜单注入
yudao-module-infra	`backend/yudao-module-infra/`	定时任务、文件服务、Redis缓存 --- 订单同步与缓存
yudao-module-ai	`backend/yudao-module-ai/`	Spring AI + MCP --- AI Agent接口层
yudao-module-mall	`backend/yudao-module-mall/`	商品/促销/交易 --- 可选的商品数据源
yudao-framework	`backend/yudao-framework/`	公共组件（安全、多租户、MyBatis Plus扩展）

1.2 待创建的 CPS 模块结构

复制代码

backend/yudao-module-cps/
├── pom.xml                              # 父POM，聚合api和biz
├── yudao-module-cps-api/                # API定义层
│   ├── pom.xml
│   └── src/main/java/.../module/cps/
│       ├── api/                         # 远程服务接口（供其他模块调用）
│       │   └── CpsOrderApi.java         # CPS订单远程API
│       └── enums/                       # 枚举定义
│           ├── CpsPlatformCodeEnum.java # 平台编码枚举(taobao/jd/pdd/douyin)
│           ├── CpsOrderStatusEnum.java  # 订单状态枚举
│           ├── CpsRebateStatusEnum.java # 返利状态枚举
│           └── CpsFreezeStatusEnum.java # 冻结状态枚举
│
└── yudao-module-cps-biz/               # 业务实现层
    ├── pom.xml
    └── src/main/java/.../module/cps/
        ├── controller/
        │   ├── admin/                   # 管理后台API（15个Controller）
        │   │   ├── CpsPlatformController.java
        │   │   ├── CpsAdzoneController.java
        │   │   ├── CpsOrderController.java
        │   │   ├── CpsRebateConfigController.java
        │   │   ├── CpsRebateRecordController.java
        │   │   ├── CpsWithdrawController.java
        │   │   ├── CpsStatisticsController.java
        │   │   ├── CpsMemberRebateController.java
        │   │   ├── CpsMcpApiKeyController.java
        │   │   └── CpsMcpAccessLogController.java
        │   └── app/                     # 会员端API（13个Controller）
        │       ├── AppCpsGoodsController.java
        │       ├── AppCpsOrderController.java
        │       ├── AppCpsRebateController.java
        │       ├── AppCpsWithdrawController.java
        │       └── AppCpsSearchController.java
        ├── service/                     # 7大业务服务
        │   ├── platform/               # 平台配置管理
        │   ├── adzone/                 # 推广位管理
        │   ├── goods/                  # 商品搜索与比价
        │   ├── order/                  # 订单同步与管理
        │   ├── rebate/                 # 返利计算与结算
        │   ├── withdraw/              # 提现管理
        │   └── statistics/            # 数据统计
        ├── client/                     # CPS平台适配器（策略模式）
        │   ├── CpsPlatformClient.java  # 统一接口
        │   ├── CpsPlatformClientFactory.java
        │   ├── taobao/                # 淘宝联盟适配器
        │   ├── jingdong/              # 京东联盟适配器
        │   ├── pinduoduo/             # 拼多多联盟适配器
        │   └── douyin/                # 抖音联盟适配器
        ├── dal/                        # 数据访问层
        │   ├── dataobject/            # DO对象（对应13张表）
        │   └── mysql/                 # MyBatis Mapper
        ├── job/                        # 定时任务
        │   ├── CpsOrderSyncJob.java   # 订单同步定时任务
        │   └── CpsRebateSettleJob.java # 返利结算定时任务
        └── mcp/                        # MCP AI接口层
            ├── tool/                   # AI可调用工具
            ├── resource/              # AI只读数据源
            └── prompt/                # 预设交互模板

1.3 模块依赖关系图

复制代码

yudao-module-cps-biz
├── yudao-module-cps-api          (自身API层)
├── yudao-module-member-api       (会员等级查询、经验值增加)
├── yudao-module-pay-api          (钱包余额增减、转账打款)
├── yudao-module-system-api       (用户认证、权限校验)
├── yudao-module-infra-api        (定时任务注册、文件服务)
├── yudao-framework-common        (公共工具、BaseDO、分页)
├── yudao-spring-boot-starter-biz-tenant   (多租户支持)
├── yudao-spring-boot-starter-security     (安全认证)
├── yudao-spring-boot-starter-mybatis      (MyBatis Plus)
├── yudao-spring-boot-starter-redis        (Redis缓存)
└── yudao-spring-boot-starter-job          (定时任务)

1.4 与参考项目 sfb 的关键差异

维度	sfb (F:\ai\cps)	AgenticCPS
框架版本	Spring Boot 2.6.7, Java 1.8	Spring Boot 3.5.9, Java 17/21
ORM	MyBatis Plus 3.5.1	MyBatis Plus 3.5.12
平台接入方式	第三方聚合(大淘客+好单库)+官方SDK混合	策略模式统一接口+可插拔适配器
订单表设计	每平台独立表(mw_order_tb/jd/pdd)	统一CPS订单表(yudao_cps_order)
金额存储	BigDecimal/Double混用	Integer(分)统一存储
多租户	无	tenant_id字段隔离
AI能力	无	MCP协议 + Spring AI
提现	自建提现表	复用pay模块钱包+自建提现审核

二、CPS 核心功能需求拆解

2.1 功能模块总览

按优先级划分为4个阶段：

Phase 1: 基础框架 + 平台管理（P0 基础设施）

CPS模块Maven骨架搭建
13张数据库表创建
CPS平台配置CRUD（A-001）
推广位管理CRUD（A-002）
平台连通测试（A-003）
枚举定义（平台编码、订单状态、返利状态）

Phase 2: 商品搜索 + 转链（P0 核心交互）

平台适配器策略模式框架
淘宝联盟适配器（商品搜索+转链）
京东联盟适配器（商品搜索+转链）
拼多多联盟适配器（商品搜索+转链）
商品搜索聚合服务（M-001）
链接/口令解析服务（M-002）
多平台比价服务（M-003）
推广链接生成服务（M-005）

Phase 3: 订单同步 + 返利结算（P0 核心闭环）

订单同步定时任务（每5分钟）
订单归因匹配逻辑
返利规则配置CRUD（A-004 / A-005）
返利计算引擎（多优先级规则匹配）
返利冻结/解冻机制
返利结算入账（调用PayWalletApi）
退款扣回处理

Phase 4: 提现 + 统计 + MCP（P0 完整闭环 + AI增强）

提现申请与审核（M-009 / A-009）
运营数据看板（A-010）
MCP AI接口层（5个Tools + Resources + Prompts）
前端管理页面（Vue3 + Element Plus）

2.2 各核心功能详细需求

商品搜索（M-001 + M-002 + M-003）

输入类型智能识别（参考sfb剪贴板正则识别层）:

URL识别: taobao.com/tmall.com -> 淘宝, jd.com -> 京东, pinduoduo.com -> 拼多多
口令识别: ￥...￥ -> 淘口令解析
纯文本关键词 -> 并发查询所有启用平台

搜索聚合策略:

并发调用各平台适配器的 searchGoods() 方法
按当前会员等级计算预估返利金额
支持筛选（平台、优惠券、价格区间）和排序（综合/价格/销量/返利）
单平台超时不影响其他平台结果返回

比价服务:

实付价 = 券后价 - 预估返利
排序模式：实付最低（默认）、券后价最低、返利最高

推广链接生成（M-005）

转链流程（参考sfb多层转链架构）:

确定平台和商品ID
获取会员推广位PID（专属PID > 平台默认PID）
注入归因参数: 淘宝(adzone_id+external_info), 京东(subUnionId), 拼多多(custom_parameters)
调用平台转链API
返回推广链接+口令 + 记录转链日志(yudao_cps_transfer_record)

输出格式:

淘宝: 淘口令(优先) + 推广链接
京东: 短链接 + 长链接
拼多多: 推广链接 + 小程序路径

订单同步与结算（核心闭环）

同步机制（参考sfb的OrderTask）:

定时任务: 每5分钟触发，遍历所有启用平台
增量查询: 调用各平台订单查询API（按时间范围）
新订单: 解析归因参数 -> 匹配会员 -> 入库
已有订单: 检查状态变化 -> 更新状态
异常处理: 未归因订单标记异常，支持手动绑定

返利计算引擎:

复制代码

可分配佣金 = 商品佣金 - 平台服务费(commission_amount * platform_service_rate)
会员返利 = 可分配佣金 * 返利比例

返利比例优先级匹配（6级）:

会员个人专属(精确平台) -> yudao_cps_rebate_config WHERE member_id=X AND platform_code=Y
会员个人专属(全平台) -> WHERE member_id=X AND platform_code IS NULL
等级+平台 -> WHERE member_level_id=L AND platform_code=Y
等级全平台 -> WHERE member_level_id=L AND platform_code IS NULL
平台默认 -> yudao_cps_platform.default_rebate_rate
全局默认 -> 系统配置

冻结/解冻机制（Phase 7设计）:

返利入账后先冻结(frozen) -> 等待解冻天数(yudao_cps_freeze_config) -> 自动解冻(unfrozen)
退款订单: 已入账返利扣回余额+创建扣回记录, 未入账返利直接取消

三、技术实现细节

3.1 平台适配器（策略模式）

核心接口（来自AGENTS.md设计）:

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();
}

工厂模式管理:

java 复制代码

@Component
public class CpsPlatformClientFactory {
    private final Map<String, CpsPlatformClient> clientMap;

    public CpsPlatformClientFactory(List<CpsPlatformClient> clients) {
        this.clientMap = clients.stream()
            .collect(Collectors.toMap(CpsPlatformClient::getPlatformCode, c -> c));
    }

    public CpsPlatformClient getClient(String platformCode) {
        return clientMap.get(platformCode);
    }

    public List<CpsPlatformClient> getAllClients() {
        return new ArrayList<>(clientMap.values());
    }
}

参考sfb的接入策略: sfb使用大淘客+好单库作为聚合层，AgenticCPS可以同时支持:

官方SDK直连（需企业资质的平台）
第三方聚合平台（大淘客/好单库）作为快速接入方案
适配器内部封装选择逻辑，对外统一接口

3.2 定时任务机制

技术方案: 复用 yudao-spring-boot-starter-job (Quartz)

订单同步任务 (CpsOrderSyncJob):

Cron表达式: 0 */5 * * * ?（每5分钟）
逻辑: 遍历所有启用平台 -> 调用适配器queryOrders -> 新增/更新订单 -> 触发返利计算
防重: 使用 platform_order_id + platform_code 联合唯一索引

返利结算任务 (CpsRebateSettleJob):

Cron表达式: 0 0 */1 * * ?（每小时）
逻辑: 查询已结算但未入账的订单 -> 计算返利 -> 冻结入账 -> 通知会员

冻结解冻任务 (CpsFreezeUnfreezeJob):

Cron表达式: 0 0 2 * * ?（每天凌晨2点）
逻辑: 查询到期的冻结记录 -> 解冻到可用余额

3.3 MCP AI接口层

技术方案: Spring AI MCP Server, JSON-RPC 2.0 over Streamable HTTP

端点 : /mcp/cps

5个 Tools:

Tool名称	方法	功能
cps_search_goods	商品搜索	自然语言搜索 -> 多平台聚合结果
cps_compare_prices	跨平台比价	自动比较各平台，推荐最优
cps_generate_link	推广链接生成	生成带归因参数的购买链接
cps_query_orders	订单查询	查询用户订单状态和返利进度
cps_get_rebate_summary	返利汇总	查看余额、待结算、累计返利

Resources : 平台配置、返利规则、统计数据（只读）
Prompts: 购物助手、比价分析、订单追踪等预设模板

四、数据库表结构设计

4.1 表清单（13张，已设计在 `backend/sql/module/cps-all-in-one.sql`）

序号	表名	用途	核心字段
1	yudao_cps_platform	CPS平台配置	platform_code, app_key, app_secret, platform_service_rate, status
2	yudao_cps_adzone	推广位管理	platform_code, adzone_id, adzone_name, adzone_type
3	yudao_cps_order	CPS订单(统一)	platform_code, platform_order_id, member_id, commission_amount, order_status
4	yudao_cps_rebate_config	返利配置	member_level_id, platform_code, rebate_rate, max_rebate_amount, priority
5	yudao_cps_rebate_record	返利记录	member_id, order_id, rebate_amount, rebate_status
6	yudao_cps_rebate_account	返利账户	member_id, total_rebate, available_balance, frozen_balance, withdrawn_amount
7	yudao_cps_withdraw	提现申请	member_id, withdraw_no, amount, fee_amount, status
8	yudao_cps_statistics	统计数据	stat_date, platform_code, order_count, commission_amount, rebate_amount
9	yudao_cps_mcp_api_key	MCP API Key	api_key, api_secret, permission_level, rate_limit
10	yudao_cps_mcp_access_log	MCP访问日志	api_key_id, tool_name, request_params, response_status
11	yudao_cps_transfer_record	转链记录	member_id, platform_code, item_id, promotion_url
12	yudao_cps_freeze_config	冻结配置	platform_code, freeze_days, auto_unfreeze
13	yudao_cps_freeze_record	冻结记录	rebate_record_id, freeze_amount, freeze_status

4.2 与sfb表设计的对比

sfb方案: 每个平台独立订单表（mw_order_tb、mw_order_jd、mw_order_pdd...），字段完全跟随各平台API返回结构，存在大量平台特有字段。

AgenticCPS方案: 统一CPS订单表 + platform_code区分。优势:

跨平台统计查询简单
返利计算逻辑统一
扩展新平台无需新建表
平台特有字段存入 extra_info JSON字段

4.3 关键设计约束

金额: Integer(分)，不用BigDecimal/Double
时区: Asia/Shanghai
软删除: deleted bit字段
多租户: tenant_id字段
表前缀: 已去掉 cps_ 前缀，使用 yudao_cps_ 前缀
乐观锁: rebate_account表使用version字段

五、前后端接口规范

5.1 管理端接口（Admin API）

接口	方法	路径	功能
平台配置CRUD	POST/PUT/DELETE/GET	`/admin-api/cps/platform/*`	创建/更新/删除/查询CPS平台
平台连通测试	POST	`/admin-api/cps/platform/test-connection`	测试平台API可用性
推广位CRUD	POST/PUT/DELETE/GET	`/admin-api/cps/adzone/*`	推广位管理
返利配置CRUD	POST/PUT/DELETE/GET	`/admin-api/cps/rebate-config/*`	等级返利规则
会员返利设置	POST/PUT/GET	`/admin-api/cps/member-rebate/*`	个人专属返利
CPS订单管理	GET/POST	`/admin-api/cps/order/*`	订单查询/同步/手动绑定
返利记录	GET	`/admin-api/cps/rebate-record/page`	返利记录分页查询
提现审核	GET/POST	`/admin-api/cps/withdraw/*`	提现列表/通过/驳回
数据看板	GET	`/admin-api/cps/statistics/dashboard`	运营看板数据
平台统计	GET	`/admin-api/cps/statistics/platform`	按平台统计
趋势统计	GET	`/admin-api/cps/statistics/trend`	趋势图表数据
MCP API Key	POST/PUT/DELETE/GET	`/admin-api/cps/mcp/api-key/*`	API Key管理
MCP访问日志	GET	`/admin-api/cps/mcp/access-log/page`	日志分页查询

5.2 会员端接口（App API）

接口	方法	路径	功能
商品搜索	POST	`/app-api/cps/goods/search`	关键词/链接/口令搜索
多平台比价	POST	`/app-api/cps/goods/compare`	跨平台比价
商品详情	GET	`/app-api/cps/goods/detail`	含返利信息
生成推广链接	POST	`/app-api/cps/link/generate`	转链
我的订单列表	GET	`/app-api/cps/order/page`	分页查询
订单详情	GET	`/app-api/cps/order/get`	单笔订单
返利汇总	GET	`/app-api/cps/rebate/summary`	余额/待结算/累计
返利明细	GET	`/app-api/cps/rebate/page`	分页查询
发起提现	POST	`/app-api/cps/withdraw/create`	提现申请
提现记录	GET	`/app-api/cps/withdraw/page`	分页查询
搜索历史	GET	`/app-api/cps/search/history`	最近搜索
热门搜索	GET	`/app-api/cps/search/hot`	热词

5.3 接口规范要求

RESTful风格，路径小写中划线
权限注解: @PreAuthorize("@ss.hasPermission('cps:platform:query')")
统一返回: CommonResult<T>
分页: PageResult<XxxRespVO>
参数校验: JSR 303 (@NotNull, @NotEmpty等)

六、业务流程梳理

6.1 完整业务链路（商品查询 -> 返利入账）

复制代码

[会员输入内容]
       |
       v
[智能识别输入类型] -- URL/口令/关键词
       |
       v
[平台路由] -- 单平台或多平台并发查询
       |
       v
[适配器调用] -- CpsPlatformClient.searchGoods()
       |
       v
[聚合结果] -- 计算预估返利(当前会员等级) + 排序
       |
       v
[会员选择商品] -> [生成推广链接]
       |                    |
       |       CpsPlatformClient.generatePromotionLink()
       |                    |
       v                    v
[记录转链日志]      [返回链接/口令给会员]
                           |
                           v
                   [会员复制链接到电商APP下单]
                           |
                           v
               [定时任务: 每5分钟同步订单]
                           |
                           v
               [订单归因] -- 解析custom_parameters/subUnionId
                           |
                    匹配会员ID
                           |
                           v
               [订单入库] -- yudao_cps_order
                           |
                           v
               [订单状态追踪] -- 已付款->已收货->已结算
                           |
                           v
               [平台确认结算] -- order_status=已结算
                           |
                           v
               [返利计算] -- 6级优先级匹配返利比例
                           |
                  可分配佣金 x 返利比例 = 返利金额
                           |
                           v
               [返利冻结入账] -- yudao_cps_rebate_record + freeze_record
                           |
                           v
               [冻结期满自动解冻] -- 定时任务检查
                           |
                           v
               [余额可提现] -- yudao_cps_rebate_account.available_balance
                           |
                           v
               [会员申请提现] -- yudao_cps_withdraw
                           |
                    +-----------+
                    |           |
               自动审核     人工审核
               (<=500元)   (>500元)
                    |           |
                    v           v
               [调用PayTransferApi打款]
                           |
                           v
                   [提现到账通知会员]

6.2 退款扣回流程

复制代码

[平台订单状态变为"已退款"]
       |
       v
[检查返利是否已入账]
       |
  +----+----+
  |         |
已入账    未入账
  |         |
  v         v
扣减钱包余额  取消待结算记录
  |
  v
创建扣回记录(负数返利)
  |
  v
通知会员

七、集成难点与风险

7.1 技术难点

难点	描述	建议方案
多平台API差异	各平台SDK版本、认证方式、返回结构差异大	策略模式+统一DTO抽象，适配器内部处理差异
订单归因准确性	不同平台归因机制不同（PID/subUnionId/custom_params）	每个适配器实现归因解析，统一member_id映射
并发搜索超时控制	多平台并发查询需控制超时，避免慢平台拖累	CompletableFuture + 超时策略，先到先展示
返利计算精度	金额以分存储，避免浮点误差	Integer统一存储，最后一步转元展示
钱包余额一致性	返利入账、扣回、提现需保证余额一致	乐观锁(version字段) + 事务控制
平台SDK兼容性	sfb使用system-scope JAR(Java 8)，AgenticCPS用Java 17+	需要重新获取兼容Java 17+的SDK版本

7.2 集成风险

风险	影响	缓解措施
平台API限流	搜索/转链被限流影响用户体验	Redis缓存热门搜索结果，限流降级策略
平台API变更	SDK版本更新导致接口不兼容	适配器隔离，变更只需修改单个适配器
订单丢失	定时任务执行失败导致订单未同步	补偿机制+手动同步+告警监控
多租户数据泄露	CPS数据跨租户访问	所有查询强制tenant_id过滤

八、建议实施步骤

Task 1: 模块骨架搭建（预计1-2天）

创建 yudao-module-cps 及其子模块(api/biz)的Maven结构
配置POM依赖关系
在 yudao-server/pom.xml 中引入CPS模块
在 backend/pom.xml 中注册CPS模块
执行 cps-all-in-one.sql 创建13张数据库表

Task 2: 枚举与DO层（预计1天）

定义CPS相关枚举（CpsPlatformCodeEnum, CpsOrderStatusEnum等）
创建13个DO类（继承BaseDO，Integer存金额）
创建13个MyBatis Mapper接口

Task 3: 平台管理CRUD（预计1-2天）

CpsPlatformService + Controller（平台配置增删改查）
CpsAdzoneService + Controller（推广位增删改查）
平台连通测试接口
管理端前端页面

Task 4: 平台适配器框架（预计2-3天）

CpsPlatformClient接口定义
CpsPlatformClientFactory工厂类
淘宝适配器实现（优先，生态最成熟）
至少一个其他平台的适配器

Task 5: 商品搜索与转链（预计2-3天）

CpsGoodsService（搜索聚合、内容解析、比价）
推广链接生成服务
转链记录服务
App端搜索/比价/转链接口

Task 6: 返利配置与规则引擎（预计1-2天）

CpsRebateConfigService（返利配置CRUD）
返利比例优先级匹配算法
会员等级集成（调用MemberLevelApi）

Task 7: 订单同步与返利结算（预计3-4天）

CpsOrderSyncJob定时任务
订单归因匹配逻辑
返利计算引擎
返利冻结/解冻机制
PayWalletApi集成（余额增减）
退款扣回处理

Task 8: 提现与统计（预计2-3天）

CpsWithdrawService（提现申请/审核/打款）
CpsStatisticsService（数据看板/平台统计/趋势）
管理端前端页面

Task 9: MCP AI接口层（预计2-3天）

MCP Server配置
5个Tools实现
Resources和Prompts配置
MCP API Key管理
访问日志记录

Task 10: 前端页面开发（预计3-5天）

管理后台CPS菜单和页面（Vue3 + Element Plus）
会员端页面（如需要）

总估时: 18-26天，建议按Task顺序分步实施，每个Task完成后进行编译验证。

CPS 联盟返利系统 — 集成分析报告