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

张

张建站

2026/6/4 20:22:12

10分钟阅读

CPS 联盟返利系统 — 集成分析报告一、项目整体架构与模块依赖关系1.1 现有模块清单已就绪模块路径CPS集成角色yudao-module-memberbackend/yudao-module-member/会员等级、经验值、积分 — CPS返利比例依据yudao-module-paybackend/yudao-module-pay/钱包余额、提现转账 — 返利入账与提现通道yudao-module-systembackend/yudao-module-system/认证权限、菜单配置 — CPS菜单注入yudao-module-infrabackend/yudao-module-infra/定时任务、文件服务、Redis缓存 — 订单同步与缓存yudao-module-aibackend/yudao-module-ai/Spring AI MCP — AI Agent接口层yudao-module-mallbackend/yudao-module-mall/商品/促销/交易 — 可选的商品数据源yudao-frameworkbackend/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/ # 管理后台API15个Controller │ │ ├── CpsPlatformController.java │ │ ├── CpsAdzoneController.java │ │ ├── CpsOrderController.java │ │ ├── CpsRebateConfigController.java │ │ ├── CpsRebateRecordController.java │ │ ├── CpsWithdrawController.java │ │ ├── CpsStatisticsController.java │ │ ├── CpsMemberRebateController.java │ │ ├── CpsMcpApiKeyController.java │ │ └── CpsMcpAccessLogController.java │ └── app/ # 会员端API13个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.8Spring Boot 3.5.9, Java 17/21ORMMyBatis Plus 3.5.1MyBatis 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平台配置CRUDA-001推广位管理CRUDA-002平台连通测试A-003枚举定义平台编码、订单状态、返利状态Phase 2: 商品搜索转链P0 核心交互平台适配器策略模式框架淘宝联盟适配器商品搜索转链京东联盟适配器商品搜索转链拼多多联盟适配器商品搜索转链商品搜索聚合服务M-001链接/口令解析服务M-002多平台比价服务M-003推广链接生成服务M-005Phase 3: 订单同步返利结算P0 核心闭环订单同步定时任务每5分钟订单归因匹配逻辑返利规则配置CRUDA-004 / A-005返利计算引擎多优先级规则匹配返利冻结/解冻机制返利结算入账调用PayWalletApi退款扣回处理Phase 4: 提现统计 MCPP0 完整闭环 AI增强提现申请与审核M-009 / A-009运营数据看板A-010MCP AI接口层5个Tools Resources Prompts前端管理页面Vue3 Element Plus2.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_idexternal_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_idX AND platform_codeY会员个人专属(全平台) - WHERE member_idX AND platform_code IS NULL等级平台 - WHERE member_level_idL AND platform_codeY等级全平台 - WHERE member_level_idL AND platform_code IS NULL平台默认 - yudao_cps_platform.default_rebate_rate全局默认 - 系统配置冻结/解冻机制Phase 7设计:返利入账后先冻结(frozen) - 等待解冻天数(yudao_cps_freeze_config) - 自动解冻(unfrozen)退款订单: 已入账返利扣回余额创建扣回记录, 未入账返利直接取消三、技术实现细节3.1 平台适配器策略模式核心接口来自AGENTS.md设计:publicinterfaceCpsPlatformClient{StringgetPlatformCode();CpsGoodsSearchResultsearchGoods(CpsGoodsSearchRequestrequest);CpsGoodsDetailgetGoodsDetail(CpsGoodsDetailRequestrequest);CpsParsedContentparseContent(Stringcontent);CpsPromotionLinkgeneratePromotionLink(CpsPromotionLinkRequestrequest);ListCpsOrderDTOqueryOrders(CpsOrderQueryRequestrequest);booleantestConnection();}工厂模式管理:ComponentpublicclassCpsPlatformClientFactory{privatefinalMapString,CpsPlatformClientclientMap;publicCpsPlatformClientFactory(ListCpsPlatformClientclients){this.clientMapclients.stream().collect(Collectors.toMap(CpsPlatformClient::getPlatformCode,c-c));}publicCpsPlatformClientgetClient(StringplatformCode){returnclientMap.get(platformCode);}publicListCpsPlatformClientgetAllClients(){returnnewArrayList(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/cps5个 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序号表名用途核心字段1yudao_cps_platformCPS平台配置platform_code, app_key, app_secret, platform_service_rate, status2yudao_cps_adzone推广位管理platform_code, adzone_id, adzone_name, adzone_type3yudao_cps_orderCPS订单(统一)platform_code, platform_order_id, member_id, commission_amount, order_status4yudao_cps_rebate_config返利配置member_level_id, platform_code, rebate_rate, max_rebate_amount, priority5yudao_cps_rebate_record返利记录member_id, order_id, rebate_amount, rebate_status6yudao_cps_rebate_account返利账户member_id, total_rebate, available_balance, frozen_balance, withdrawn_amount7yudao_cps_withdraw提现申请member_id, withdraw_no, amount, fee_amount, status8yudao_cps_statistics统计数据stat_date, platform_code, order_count, commission_amount, rebate_amount9yudao_cps_mcp_api_keyMCP API Keyapi_key, api_secret, permission_level, rate_limit10yudao_cps_mcp_access_logMCP访问日志api_key_id, tool_name, request_params, response_status11yudao_cps_transfer_record转链记录member_id, platform_code, item_id, promotion_url12yudao_cps_freeze_config冻结配置platform_code, freeze_days, auto_unfreeze13yudao_cps_freeze_record冻结记录rebate_record_id, freeze_amount, freeze_status4.2 与sfb表设计的对比sfb方案: 每个平台独立订单表mw_order_tb、mw_order_jd、mw_order_pdd…字段完全跟随各平台API返回结构存在大量平台特有字段。AgenticCPS方案: 统一CPS订单表 platform_code区分。优势:跨平台统计查询简单返利计算逻辑统一扩展新平台无需新建表平台特有字段存入extra_infoJSON字段4.3 关键设计约束金额: Integer(分)不用BigDecimal/Double时区: Asia/Shanghai软删除: deleted bit字段多租户: tenant_id字段表前缀: 已去掉cps_前缀使用yudao_cps_前缀乐观锁: rebate_account表使用version字段五、前后端接口规范5.1 管理端接口Admin API接口方法路径功能平台配置CRUDPOST/PUT/DELETE/GET/admin-api/cps/platform/*创建/更新/删除/查询CPS平台平台连通测试POST/admin-api/cps/platform/test-connection测试平台API可用性推广位CRUDPOST/PUT/DELETE/GET/admin-api/cps/adzone/*推广位管理返利配置CRUDPOST/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 KeyPOST/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))统一返回:CommonResultT分页:PageResultXxxRespVO参数校验: 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类继承BaseDOInteger存金额创建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返利比例优先级匹配算法会员等级集成调用MemberLevelApiTask 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完成后进行编译验证。