【AgenticCPS 】CPS联盟返利系统 - 实施计划

帐篷Li2026-03-21 16:59

CPS联盟返利系统 - 实施计划

背景说明

为什么需要本项目？

CPS（Cost Per Sale，按销售付费）是电商联盟推广的核心模式。当前项目基于 ruoyi-vue-pro 框架，需要新增一个完整的 yudao-module-cps 模块，用于构建一站式多平台CPS返利查询与导购系统。该模块将aggregate淘宝联盟、京东联盟、拼多多联盟等主流CPS平台能力，为会员提供返利查询、跨平台比价、推广链接生成和返利提现等服务。

本项目要解决什么问题？

  1. 多平台聚合：统一接入多个CPS平台，提供一致的商品查询和返利查询能力
  2. 会员返利体系：基于现有会员等级体系，支持差异化的返利比例配置
  3. 多平台比价：支持跨平台搜索比价，帮助用户找到最优价格和最高返利
  4. 订单全链路追踪：实现从商品查询→链接生成→用户下单→佣金结算→返利入账的完整业务闭环
  5. MCP AI接口：提供基于MCP协议的AI Agent接口层，支持AI驱动的商品查询、比价、推荐等功能

期望 outcomes

  • 完善的项目架构设计文档
  • 清晰的模块划分和依赖关系
  • MCP AI接口的标准规范
  • 完善的README文档，包含代码简介和功能介绍

实施方案

1. 模块划分与架构设计

基于 ruoyi-vue-pro 的模块化设计，新增 yudao-module-cps 模块：

复制代码 
yudao-module-cps/
├── yudao-module-cps-api/          # CPS模块API定义（供其他模块调用）
│   ├── enums/                     # 枚举定义（平台编码、订单状态等）
│   └── api/                       # 远程服务接口
│
└── yudao-module-cps-biz/          # CPS模块业务实现
    ├── controller/
    │   ├── admin/                 # 管理后台接口
    │   │   ├── CpsPlatformController         # 平台配置管理
    │   │   ├── CpsAdzoneController           # 推广位管理
    │   │   ├── CpsOrderController            # 订单管理
    │   │   ├── CpsRebateConfigController     # 返利配置管理
    │   │   ├── CpsWithdrawController         # 提现审核管理
    │   │   └── CpsStatisticsController       # 数据统计
    │   │
    │   └── app/                   # C端会员接口
    │       ├── AppCpsGoodsController         # 商品搜索与比价
    │       ├── AppCpsLinkController          # 转链/口令生成
    │       ├── AppCpsOrderController         # 我的订单
    │       ├── AppCpsRebateController        # 我的返利
    │       └── AppCpsWithdrawController      # 提现
    │
    ├── service/
    │   ├── platform/              # CPS平台适配层
    │   │   ├── CpsPlatformClientFactory      # 平台客户端工厂
    │   │   └── CpsPlatformConfigService      # 平台配置服务
    │   ├── goods/                 # 商品查询服务
    │   │   ├── CpsGoodsSearchService         # 搜索与比价
    │   │   └── CpsGoodsParseService          # 链接/口令解析
    │   ├── link/                  # 推广链接服务
    │   │   └── CpsPromotionLinkService       # 转链与归因
    │   ├── order/                 # 订单服务
    │   │   ├── CpsOrderSyncService           # 订单同步
    │   │   └── CpsOrderService               # 订单管理
    │   ├── commission/            # 佣金结算服务
    │   │   ├── CpsCommissionCalcService      # 佣金计算
    │   │   └── CpsRebateSettleService        # 返利结算
    │   ├── rebate/                # 返利配置服务
    │   │   └── CpsRebateConfigService        # 返利规则管理
    │   └── withdraw/              # 提现服务
    │       └── CpsWithdrawService            # 提现管理
    │
    ├── client/                    # CPS平台适配器（策略模式）
    │   ├── CpsPlatformClient.java            # 统一接口定义
    │   ├── taobao/                           # 淘宝联盟适配器
    │   ├── jingdong/                         # 京东联盟适配器
    │   ├── pinduoduo/                        # 拼多多联盟适配器
    │   └── douyin/                           # 抖音联盟适配器（扩展）
    │
    ├── dal/
    │   ├── dataobject/            # 数据库实体
    │   └── mysql/                 # Mapper接口
    ├── convert/                   # DTO转换（MapStruct）
    ├── job/                       # 定时任务
    └── mcp/                       # MCP（Model Context Protocol）AI接口层
        ├── server/
        │   ├── CpsMcpServer.java             # MCP Server主入口
        │   └── CpsMcpServerConfig.java       # MCP Server配置类
        ├── transport/
        │   ├── CpsMcpHttpTransport.java      # Streamable HTTP传输层
        │   └── CpsMcpStdioTransport.java     # STDIO传输层
        ├── tool/                             # MCP Tools定义
        │   ├── CpsSearchGoodsTool.java       # 商品搜索工具
        │   ├── CpsComparePricesTool.java     # 多平台比价工具
        │   └── ...
        ├── resource/                         # MCP Resources定义
        │   ├── CpsPlatformResource.java      # 平台列表及状态
        │   ├── CpsRebateRuleResource.java    # 返利规则配置
        │   └── ...
        └── prompt/                           # MCP Prompts定义
            ├── CpsFindBestDealPrompt.java    # 找最优惠商品
            ├── CpsComparePrompt.java         # 跨平台比价
            └── ...

2. 与现有模块依赖关系

复制代码 
yudao-module-cps-biz
  ├── 依赖 yudao-module-member        # 复用会员体系（用户、等级、积分）
  ├── 依赖 yudao-module-pay            # 复用支付模块（钱包、提现转账）
  ├── 依赖 yudao-module-system         # 复用系统模块（权限、字典、通知）
  └── 依赖 yudao-module-infra          # 复用基础设施（定时任务、文件存储）

3. 核心功能设计

3.1 MCP AI接口模块（P3优先级）

本模块基于 MCP（Model Context Protocol） 协议标准，为CPS系统构建一套可供AI Agent直接调用的接口层。

MCP三类原语：

原语 说明 在CPS系统中的作用
Tools AI可调用的可执行函数 商品搜索、比价、转链、订单查询等操作
Resources AI可读取的数据源（只读） 平台配置、返利规则、会员画像、统计数据等
Prompts 预定义的交互模板 找最优价、比价分析、省钱策略等场景化提示

核心Tools定义：

  1. cps_search_goods（商品搜索）

    • 参数：keyword, platform_code, price_min, price_max, sort_type, member_id
    • 返回：统一商品列表（含 platformCode, title, price, finalPrice, estimateRebate 等字段）

  2. cps_compare_prices（多平台比价）

    • 参数：keyword, member_id
    • 返回：跨平台比价表格，推荐最优方案

  3. cps_generate_link（推广链接生成）

    • 参数：itemId, platformCode, memberId
    • 返回：推广链接/口令，含归因参数

  4. cps_get_order_status（订单状态查询）

    • 参数：memberId
    • 返回：用户订单列表及返利进度

  5. cps_rebate_summary（返利汇总）

    • 参数：memberId
    • 返回：可提现余额、待结算金额、累计收入

传输层支持：

传输方式 适用场景 端点 说明
Streamable HTTP 远程AI Agent接入 /mcp/cps 支持SSE流式响应，适合生产环境
STDIO 本地开发调试 标准输入输出 适合本地AI开发工具集成

配置项（application.yaml）：

yaml 复制代码 
yudao:
  cps:
    mcp:
      enabled: true                          # 是否启用MCP Server
      transport: http                        # 传输方式: http / stdio
      http:
        endpoint: /mcp/cps                   # HTTP端点路径
        sse-enabled: true                    # 是否启用SSE流式推送
      auth:
        enabled: true                        # 是否启用鉴权
        type: bearer                         # 鉴权方式: bearer / api-key
      rate-limit:
        enabled: true                        # 是否启用限流
        max-requests-per-minute: 60          # 每分钟最大请求数

4. 数据库设计（核心表）

复制代码 
yudao_cps_platform          # CPS平台配置表
yudao_cps_adzone            # 推广位（PID）管理表
yudao_cps_order             # CPS订单表
yudao_cps_rebate_config     # 返利配置表
yudao_cps_rebate_record     # 返利记录表
yudao_cps_withdraw          # 提现申请表
yudao_cps_statistics        # 统计数据表
yudao_cps_mcp_api_key       # MCP API Key管理表
yudao_cps_mcp_access_log    # MCP访问日志表

5. 接口规范

5.1 会员端接口（约13个）
复制代码 
POST   /app-api/cps/goods/search          # 商品搜索
POST   /app-api/cps/goods/compare         # 多平台比价
GET    /app-api/cps/goods/detail          # 商品详情
GET    /app-api/cps/goods/recommend       # 商品推荐
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.2 管理端接口（约15个）
复制代码 
 admin-api/cps/platform/*               # 平台配置管理
 admin-api/cps/adzone/*                 # 推广位管理
 admin-api/cps/order/*                  # 订单管理
 admin-api/cps/rebate-config/*          # 返利配置
 admin-api/cps/withdraw/*               # 提现审核
 admin-api/cps/statistics/*             # 数据统计
 admin-api/cps/mcp/*                    # MCP管理

6. 技术要求

6.1 性能要求
指标 要求
单平台搜索 < 2秒（P99）
多平台比价 < 5秒（P99）
转链生成 < 1秒
订单同步延迟 < 30分钟
返利入账延迟 平台结算后 24小时内
6.2 数据安全
  • CPS平台密钥 AES-256 加密存储
  • 会员数据隔离（只能查看自己的数据）
  • 敏感操作记录审计日志
  • 提现金额二次校验

验证方式

单元测试

  • CPS平台适配器单元测试（每个平台至少10个测试用例）
  • 返利计算逻辑测试（覆盖5种不同优先级场景）
  • 订单同步与归因测试
  • MCP Tools功能测试

集成测试

  • 淘宝联盟全流程测试
  • 京东联盟全流程测试
  • 拼多多联盟全流程测试
  • 多平台比价性能测试

性能测试

  • 并发搜索测试（500并发，响应时间<5秒）
  • 订单同步压力测试（1000+订单无异常）
  • MCP接口压测（100 QPS，成功率>99%）

验收标准

P0功能验收（必须上线）
  1. ✅ 淘宝联盟接入 - 搜索/转链/订单同步正常，返利计算准确
  2. ✅ 京东联盟接入 - 搜索/转链/订单同步正常，返利计算准确
  3. ✅ 拼多多联盟接入 - 搜索/转链/订单同步正常，返利计算准确
  4. ✅ 多平台比价 - 并发查询3个平台，5秒内返回结果
  5. ✅ 返利比例配置 - 多维度配置生效，优先级逻辑正确
  6. ✅ 订单同步 - 5分钟内同步新订单，归因成功率 > 95%
  7. ✅ 返利结算 - 平台结算后24小时内入账，金额精确到分
  8. ✅ 提现功能 - 提现申请/审核/打款流程通畅
  9. ✅ 数据看板 - 核心指标展示正确
  10. ✅ 异常处理 - 单平台故障不影响其他平台

文件修改计划

README文档更新

在 README.md 中新增 CPS联盟返利系统 章节，包含：

  1. CPS系统简介：一站式多平台CPS返利查询与导购系统
  2. 核心功能 ：
    • 多平台CPS联盟接入（淘宝/京东/拼多多）
    • 商品搜索与比价
    • 会员返利体系
    • 提现管理
    • MCP AI接口
  3. 技术架构：采用策略模式实现平台可扩展
  4. 接口概览：会员端13个接口，管理端15个接口
  5. 演示截图：搜索页面、比价页面、返利页面、数据看板
  6. 使用说明：如何接入CPS平台、配置返利规则

文档位置

  • README.md：新增CPS联盟返利系统章节
  • docs/CPS系统需求文档.md：详细功能需求
  • docs/CPS系统PRD文档.md：产品需求文档

实施顺序

Phase 1: 基础框架搭建（第1周）✅ 已完成

  1. 创建 yudao-module-cps 模块结构
  2. 定义数据库表结构
  3. 实现CPS平台适配器接口
  4. 搭建MCP Server基础框架

Phase 2: 核心功能开发（第2-3周）✅ 已完成

  1. 实现淘宝联盟适配器
  2. 实现京东联盟适配器
  3. 实现拼多多联盟适配器
  4. 实现商品搜索与比价功能
  5. 实现推广链接生成功能

Phase 3: 订单与结算（第4周）✅ 已完成

  1. 实现订单同步定时任务
  2. 实现订单归因匹配
  3. 实现返利计算引擎
  4. 实现返利入账逻辑

Phase 4: 会员与提现（第5周）✅ 已完成

  1. 实现会员返利账户管理
  2. 实现提现申请与审核
  3. 实现钱包集成
  4. 实现提现转账对接

Phase 5: 数据统计（第6周）✅ 已完成

  1. 实现运营数据看板
  2. 实现平台统计
  3. 实现会员统计
  4. 实现收益报表

Phase 6: MCP AI接口（第7周）✅ 已完成

  1. 实现MCP Server
  2. 实现5个MCP Tools
  3. 实现3个MCP Resources
  4. 实现2个MCP Prompts
  5. 集成AI Agent测试

Phase 7: 文档与优化（第8周）🚀 进行中

  1. 完善README文档
  2. 编写接口文档
  3. 性能优化
  4. 单元测试

备注

  • 本项目复用 ruoyi-vue-pro 现有模块，无需重复造轮子
  • 采用策略模式实现平台适配器，确保可扩展性
  • MCP AI接口模块为P3优先级，可后续迭代
  • 所有代码需遵循《阿里巴巴 Java 开发手册》规范
  • 核心逻辑必须包含单元测试
相关推荐
罗罗攀1 小时前
PyTorch学习笔记|张量的广播和科学运算
人工智能·pytorch·笔记·python·学习
倦王1 小时前
Dify2：提示词工程与运用
人工智能
PhotonixBay2 小时前
共聚焦显微镜的结构组成与应用
人工智能·算法·机器学习
CDA数据分析师干货分享2 小时前
汉江师范学院数据科学与大数据技术专业大二学生：CDA一级学习经验
大数据·经验分享·学习·数据分析·cda证书·cda数据分析师
大傻^2 小时前
Spring AI Alibaba Function Calling：外部工具集成与业务函数注册
java·人工智能·后端·spring·springai·springaialibaba
SuniaWang2 小时前
《Spring AI + 大模型全栈实战》学习手册系列 · 专题四：《Ollama 模型管理与调优：让 AI 模型在低配服务器上流畅运行》
人工智能·学习·spring
Fly Wine2 小时前
IPsec 最简单场景总部和网关之间建立，并且流量不会全部经过总部
网络
anscos_yumi2 小时前
Altair OptiStruct：重构结构研发逻辑，引领工业仿真与优化新纪元
人工智能·科技·软件工程
市象2 小时前
小红书盯上“AI版郑州帮”
人工智能·网络安全·传媒
热门推荐
01GitHub 镜像站点02Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南03小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）04Labelme从安装到标注：零基础完整指南05OpenClaw 使用和管理 MCP 完全指南06班级宠物园部署指南07AI 编程三剑客：Spec-Kit、OpenSpec、Superpowers 深度对比与实战指南08UV安装并设置国内源09OpenClaw Control UI安全上下文访问配置10“wsl --install -d Ubuntu-22.04”下载慢，中国地区离线安装 Ubuntu 22.04 WSL方法（亲测2025年5月6日）