309 lines
14 KiB
Markdown
309 lines
14 KiB
Markdown
# 积分兑换电商平台（多商户版本）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 # 端到端数据确认
|
||
```
|
||
|
||
---
|
||
|
||
## 已知问题与修复记录
|
||
|
||
| 问题 | 原因 | 修复方案 |
|
||
|------|------|---------|
|
||
|