# 积分兑换电商平台（多商户版本）MER-2.2 ## 项目定位 本项目是一套以**积分兑换**为核心玩法的多商户电商平台。用户通过购物、签到、寄卖（consignment）等行为积累积分，再凭积分在平台积分商城内兑换商品或抵扣订单金额。平台同时支持多商户入驻，并通过 Kafka 实时对接各单商户源系统的订单与用户数据。 **本地位置** /Users/apple/scott2026/integral-shop --- ## 核心业务模型 ``` 用户行为（购物/签到/寄卖） │ ▼ 积分/奖金 累积 ┌─────────────────────────────┐ │ 积分账户 UserIntegralRecord │ ← 平台标准积分 │ 个人奖金 WaSelfbonus │ ← 寄卖子系统奖金 │ 余额 money │ └─────────────────────────────┘ │ 定时同步（每日 10:15 / 14:50） │ IntegralConsumeTask ▼ ┌─────────────────────────────┐ │ 积分商城 │ │ IntegralShoppingService │ ← 积分查询 / 兑换 │ IntegralCompatController │ ← 兼容单商户前端 API 路径 │ ShoppingCreditsOrder │ ← 购物积分订单 └─────────────────────────────┘ │ ▼ 商品/订单/支付（多商户体系） ``` ### 积分来源 | 来源 | 说明 | 相关服务 | |------|------|---------| | 购物返积分 | 订单完成后按比例返还 | `OrderService`、`AsyncServiceImpl` | | 每日签到 | 签到奖励积分 | `SignServiceImpl` | | 个人奖金（寄卖） | 寄卖商品产生的个人奖金定时同步为积分 | `WaSelfbonusSyncService`、`IntegralConsumeTask` | | 平台发放 | 管理员手动发放 | 管理端积分管理接口 | ### 积分消费 | 用途 | 说明 | 相关服务 | |------|------|---------| | 积分商城兑换 | 全额积分抵扣商品 | `IntegralShoppingService` | | 订单抵扣 | 下单时部分积分抵扣现金 | `ComputedOrderPriceResponse.isUseIntegral` | | 购物积分包 | 购买积分增值包 | `ManageShoppingCreditsPackageService` | --- ## 系统架构 ``` ┌─────────────────────────────────┐ │ 单商户源系统（多个） │ │ crmeb_22miao / yangtangyoupin │ │ Kafka Producer: │ │ OrderSyncProducerService │ └──────────────┬──────────────────┘ │ Kafka 消息（订单/用户） ▼ ┌────────────────────────┐ │ Kafka Broker │ │ 118.31.75.148:9092 │ └────────────┬────────────┘ │ 消费 ▼ ┌──────────────────────────────────────────────────────────────────┐ │ 积分兑换电商平台 MER-2.2_2601 │ │ │ │ ┌────────────────┐ ┌────────────────┐ ┌────────────────────┐ │ │ │ mer_plat_admin │ │ mer_mer_admin │ │ mer_uniapp │ │ │ │ 平台超管后台 │ │ 商户端后台 │ │ 移动端/小程序 │ │ │ │ (Vue2) │ │ (Vue2) │ │ (UniApp) │ │ │ └───────┬────────┘ └───────┬────────┘ └─────────┬──────────┘ │ │ └──────────────────┼──────────────────────┘ │ │ ▼ │ │ ┌────────────────┐ │ │ │ mer_java │ │ │ │ Spring Boot │ │ │ │ 5 Maven 模块 │ │ │ └───────┬────────┘ │ │ │ │ │ ┌──────────────────┼──────────────────────┐ │ │ ▼ ▼ ▼ │ │ 积分/奖金体系 订单/商品/支付 Kafka 消费暂存 │ │ UserIntegralRecord 多商户订单流转 eb_sync_order_staging │ │ WaSelfbonus 积分商城订单 eb_sync_user_staging │ │ IntegralShopping ShoppingCredits eb_sync_merchant_cfg │ └──────────────────────────────────────────────────────────────────┘ ``` --- ## 工程目录结构 ``` MER-2.2_2601/ ├── mer_java/ # Java 后端（Maven 多模块，主体） ├── mer_mer_admin/ # 商户端管理台（Vue2 SPA） ├── mer_plat_admin/ # 平台超管管理台（Vue2 SPA） └── mer_uniapp/ # 用户侧移动 App / 微信小程序（UniApp） ``` --- ## `mer_java` 后端详解 ### 模块结构 ``` mer_java/ ├── pom.xml # 父 POM（Spring Boot 2.2.6，Java 8） ├── crmeb-common/ # 公共层：实体、DTO、枚举、工具、拦截器 ├── crmeb-service/ # 业务层：所有 Service 实现 + DAO + Kafka 消费者 ├── crmeb-admin/ # 管理端可执行 App（定时任务、管理 API） ├── crmeb-front/ # 客户端可执行 App（用户 API） └── crmeb-generate/ # MyBatis-Plus 代码生成工具 ``` ### 积分相关核心类 | 类 / 文件 | 所在模块 | 职责 | |-----------|---------|------| | `IntegralCompatController` | crmeb-front | 积分商城兼容控制器，提供与单商户前端路径一致的 API（`/api/front/products`、`/api/front/integral/list`、`/api/front/order/pre/order` 等），内部委托多商户 Service 实现 | | `IntegralShoppingService` | crmeb-service | 积分商城核心服务：查询用户积分信息、积分商品列表、兑换下单 | | `UserIntegralRecordService` | crmeb-service | 用户积分变动记录的增删查，记录每一笔积分增减明细 | | `WaSelfbonusSyncService` | crmeb-service | 将寄卖子系统产生的个人奖金（`WaSelfbonusLog`）按比例换算后写入用户积分账户 | | `IntegralConsumeTask` | crmeb-admin | 定时任务：每日 10:15 / 14:50 触发奖金→积分同步，失败自动重试（最多 3 次） | | `WaSelfbonusController` | crmeb-front | 寄卖奖金查询接口：获取用户个人奖金余额、奖金流水明细 | | `ManageShoppingCreditsOrderService` | crmeb-admin | 购物积分订单管理（管理端）：查询、退款审核 | | `ManageShoppingCreditsPackageService` | crmeb-admin | 积分增值包管理：创建/编辑积分包商品 | | `SignServiceImpl` | crmeb-service | 每日签到积分发放 | | `OrderStagingProcessService` | crmeb-service | Kafka 消费者：接收单商户订单/用户事件，写入暂存表并触发积分发放流程 | ### 积分订单完整流程 ``` 用户在积分商城选品 │ ▼ POST /api/front/order/pre/order （IntegralCompatController，固定 secondType=1 积分订单） │ ▼ FrontOrderService.preOrder_V1_7 │ 返回 preOrderNo ▼ POST /api/front/order/create （填入 preOrderNo + addressId + isUseIntegral） │ ▼ FrontOrderService.createOrder ├── 计算积分抵扣金额（ComputedOrderPriceResponse） ├── 扣减用户积分（UserIntegralRecordService） └── 创建订单（多商户订单体系） │ ▼ POST /api/front/pay/payment （payChannel: yue / weixin / alipay） │ ▼ 订单完成 → AsyncServiceImpl 异步返积分 ``` ### 奖金→积分同步流程 ``` 寄卖系统（WaUsers）产生奖金变动 │ 写入 wa_selfbonus_log ▼ IntegralConsumeTask（Quartz 定时 每日 10:15 / 14:50） │ ▼ WaSelfbonusSyncService.syncSelfbonusToIntegral() ├── 读取最新 500 条 WaSelfbonusLog ├── 按换算比例计算积分增量 ├── 写入 user_integral_record └── 更新 eb_user.integral 余额 │ 失败自动重试（最多 3 次，锁超时时退避等待） ▼ 用户积分账户更新完成 ``` --- ## 前端子工程 | 子工程 | 框架 | 用途 | |--------|------|------| | `mer_plat_admin` | Vue 2.6.10 · Element UI 2.15.14 | 平台超级管理员后台：商户审核、积分配置、购物积分包管理、全局营销活动、数据统计 | | `mer_mer_admin` | Vue 2.6.12 · Element UI 2.15.6 | 入驻商户管理后台：商品管理、订单处理、积分订单查看、分润账单 | | `mer_uniapp` | UniApp · Vue | 用户侧 App 及微信小程序：积分查询、积分商城、兑换下单、寄卖奖金明细 | --- ## 技术栈 | 层次 | 技术 | |------|------| | 语言/框架 | Java 8 · Spring Boot 2.2.6 | | ORM | MyBatis-Plus 3.3.1 | | 数据库 | MySQL 8.0.33 | | 缓存 | Redis + Redisson（分布式锁，积分扣减并发控制） | | 消息队列 | Kafka `spring-kafka`（消费单商户订单/用户事件） | | 定时任务 | Quartz（积分同步、奖金结算、订单超时处理） | | 鉴权 | JWT · Spring Security | | 微信生态 | WxJava 4.7.5（miniapp · pay · open platform · 公众号） | | 支付 | Alipay SDK · 微信支付 | | 云存储 | 阿里云 OSS · 腾讯云 COS · 七牛云 · 京东云 S3 · 华为云 OBS | | IP 解析 | ip2region 2.7.0 | | 接口文档 | Knife4j 2.0.7 | --- ## 数据库核心表概览 | 表名 | 说明 | |------|------| | `eb_user` | 用户主表，含 `integral`（积分余额）、`money`（余额）字段 | | `eb_user_integral_record` | 积分变动明细流水（每笔增减均记录） | | `eb_store_order` | 多商户订单主表，`second_type=1` 标识积分订单 | | `wa_users` | 寄卖系统用户表，含 `self_bonus`（个人奖金）、`share_bonus`（分享奖金） | | `wa_selfbonus_log` | 寄卖个人奖金变动日志（IntegralConsumeTask 的数据来源） | | `eb_sync_order_staging` | Kafka 消费暂存：同步状态、重试计数、错误信息 | | `eb_sync_user_staging` | 用户同步暂存表 | | `eb_sync_merchant_config` | 源商户与目标商户 ID 映射配置 | --- ## 单商户 API 兼容层 `IntegralCompatController`（`api/front/*`）提供与单商户版本路径完全一致的接口，使移动端无需改动即可切换至多商户后端： | 单商户路径 | 多商户实现 | 说明 | |-----------|----------|------| | `GET /products` | `FrontProductService.getList` | 商品列表 | | `GET /category` | `ProductCategoryService.getMerchantCacheTree` | 分类树 | | `POST /loginV2` | `LoginService.phoneLogin` | 账号密码登录 | | `GET /integral/list` | `UserCenterService.getUserIntegralRecordList` | 积分流水 | | `GET /integral/user/account` | `IntegralShoppingService.getUserIntegralInfo` | 积分余额 | | `POST /order/pre/order` | `FrontOrderService.preOrder_V1_7`（secondType=1） | 积分预下单 | | `POST /order/create` | `FrontOrderService.createOrder` | 创建订单（含积分抵扣） | | `GET /order/list` | `FrontOrderService.list_v1_4` | 订单列表 | | `POST /pay/payment` | `PayService.payment` | 订单支付 | --- ## 运行环境 | 组件 | 地址 | |------|------| | Kafka Broker | `118.31.75.148:9092` | | 多商户 MySQL | `118.31.75.148:3306` | | shop_a Redis | `101.201.54.161:6379`（DB 2） | | shop_b Redis | `39.106.63.33:6379`（DB 2） | --- ## 快速启动 ### 1. 初始化数据库 ```bash cd ../db/ bash kafka_sync_env_setup.sh # 执行：sync_staging_tables.sql、sync_merchant_config_insert.sql # 输出：Kafka Topic 创建命令、Redis 刷新命令 ``` ### 2. 编译打包 ```bash cd mer_java/ mvn package -pl crmeb-front,crmeb-admin -am -DskipTests ``` ### 3. 启动服务 ```bash # 客户端 API（积分商城前端对接） java -jar crmeb-front/target/mer-front-2.2.jar --spring.profiles.active=prod # 管理端 API（含定时积分同步任务） java -jar crmeb-admin/target/mer-admin-2.2.jar --spring.profiles.active=prod ``` ### 4. 验证积分同步 ```bash cd ../db/ bash test_integration_producer.sh # 模拟单商户发送订单事件 bash test_integration_consumer.sh # 验证多商户消费结果 mysql -u root -p < test_verify_e2e.sql # 端到端数据确认 ``` --- ## 已知问题与修复记录 | 问题 | 原因 | 修复方案 | |------|------|---------|