scottpan/MER-2.2_2601
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
MER-2.2_2601/README.md

309 lines
14 KiB
Markdown
Raw Permalink Normal View History

Initial commit: 积分兑换电商平台多商户版 MER-2.2 Made-with: Cursor
2026-03-08 20:07:52 +08:00
# 积分兑换电商平台（多商户版本）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 # 端到端数据确认
```
---
## 已知问题与修复记录
| 问题 | 原因 | 修复方案 |
|------|------|---------|
Reference in New Issue Copy Permalink