14 KiB
14 KiB
积分兑换电商平台（多商户版本）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. 初始化数据库
cd ../db/
bash kafka_sync_env_setup.sh
# 执行：sync_staging_tables.sql、sync_merchant_config_insert.sql
# 输出：Kafka Topic 创建命令、Redis 刷新命令
2. 编译打包
cd mer_java/
mvn package -pl crmeb-front,crmeb-admin -am -DskipTests
3. 启动服务
# 客户端 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. 验证积分同步
cd ../db/
bash test_integration_producer.sh # 模拟单商户发送订单事件
bash test_integration_consumer.sh # 验证多商户消费结果
mysql -u root -p < test_verify_e2e.sql # 端到端数据确认
已知问题与修复记录
| 问题 | 原因 | 修复方案 |
|---|