# union-all-api

**Repository Path**: liujie996/union-all-api

## Basic Information

- **Project Name**: union-all-api
- **Description**: 多平台返利系统 
本项目是一个基于Spring Boot的多平台返利系统，支持淘宝联盟、京东联盟、拼多多多多客等主流电商平台的返利对接。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 9
- **Forks**: 7
- **Created**: 2024-11-25
- **Last Updated**: 2025-09-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 多平台返利系统 (Union All API)

[![Java](https://img.shields.io/badge/Java-21-orange.svg)](https://www.oracle.com/java/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.1.12-brightgreen.svg)](https://spring.io/projects/spring-boot)
[![MySQL](https://img.shields.io/badge/MySQL-5.7+-blue.svg)](https://www.mysql.com/)
[![Redis](https://img.shields.io/badge/Redis-5.0+-red.svg)](https://redis.io/)
[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

本项目是一个基于Spring Boot的企业级多平台返利系统，支持淘宝联盟、京东联盟、拼多多多多客等主流电商平台的返利对接。系统采用现代化的微服务架构设计，提供完整的返利业务解决方案。

## 🚀 系统特点

- **🛒 多平台支持**: 支持淘宝联盟、京东联盟、拼多多多多客等主流电商平台
- **📊 订单追踪**: 完整的订单生命周期管理和实时状态追踪
- **💰 智能分佣**: 灵活的多级分销体系和佣金计算规则
- **📈 数据分析**: 实时的数据统计分析和可视化报表
- **🔐 安全认证**: 基于Sa-Token的安全认证和权限管理
- **🐳 容器化部署**: 支持Docker一键部署和容器编排
- **📱 微信集成**: 完整的微信公众号和支付功能集成
- **⚡ 高性能**: Redis缓存和分布式锁保证系统高并发性能

## 🏗️ 技术架构

### 核心技术栈
- **后端框架**: Spring Boot 3.1.12 + JDK 21
- **数据库**: MySQL 5.7+ + MyBatis Plus 3.5.7
- **缓存**: Redis 5.0+ + Redisson
- **安全认证**: Sa-Token 1.37.0
- **API文档**: Knife4j 4.5.0 (Swagger)
- **工具库**: Hutool 5.8.39
- **微信SDK**: WxJava 4.6.0

### 架构设计
```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   前端应用      │    │   微信小程序    │    │   管理后台      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
         ┌─────────────────────────────────────────────────┐
         │              API Gateway                        │
         └─────────────────────────────────────────────────┘
                                 │
         ┌─────────────────────────────────────────────────┐
         │            Spring Boot Application              │
         │  ┌─────────────┐  ┌─────────────┐  ┌──────────┐ │
         │  │ 订单管理    │  │ 用户管理    │  │ 佣金管理 │ │
         │  └─────────────┘  └─────────────┘  └──────────┘ │
         │  ┌─────────────┐  ┌─────────────┐  ┌──────────┐ │
         │  │ 平台对接    │  │ 支付管理    │  │ 统计分析 │ │
         │  └─────────────┘  └─────────────┘  └──────────┘ │
         └─────────────────────────────────────────────────┘
                                 │
         ┌─────────────────────────────────────────────────┐
         │  ┌─────────────┐  ┌─────────────┐  ┌──────────┐ │
         │  │   MySQL     │  │    Redis    │  │ 第三方API│ │
         │  └─────────────┘  └─────────────┘  └──────────┘ │
         └─────────────────────────────────────────────────┘
```

## 📋 项目结构

```
union-all-api/
├── pom.xml                          # 父级Maven配置
├── README.md                        # 项目说明文档
├── LICENSE                          # 开源协议
├── images/                          # 项目截图
└── union-web/                       # 主应用模块
    ├── pom.xml                      # 模块Maven配置
    └── src/main/
        ├── java/com/union/
        │   ├── WebApplication.java  # 应用启动类
        │   ├── biz/                 # 业务逻辑层
        │   │   ├── convert/         # 对象转换器
        │   │   ├── dto/             # 数据传输对象
        │   │   ├── facade/          # 业务门面层
        │   │   ├── manager/         # 业务管理器
        │   │   ├── mapper/          # 数据访问层
        │   │   ├── model/           # 数据模型
        │   │   ├── service/         # 业务服务层
        │   │   └── vo/              # 视图对象
        │   ├── config/              # 配置类
        │   ├── controller/          # 控制器层
        │   │   ├── admin/           # 管理端接口
        │   │   └── app/             # 应用端接口
        │   ├── security/            # 安全认证
        │   ├── scheduled/           # 定时任务
        │   └── utils/               # 工具类
        └── resources/
            ├── application.yml      # 应用配置
            ├── application-dev.yml  # 开发环境配置
            ├── application-test.yml # 测试环境配置
            ├── docker/              # Docker配置
            └── lib/                 # 第三方SDK
```

## 🚀 快速开始

### 环境要求

| 软件 | 版本要求 | 说明 |
|------|----------|------|
| JDK | 21+ | 推荐使用OpenJDK或Oracle JDK |
| Maven | 3.6+ | 项目构建工具 |
| MySQL | 5.7+ | 主数据库 |
| Redis | 5.0+ | 缓存和会话存储 |
| Docker | 18.0+ | 容器化部署(可选) |
| Docker Compose | 1.29+ | 容器编排(可选) |

### 本地开发环境搭建

#### 1. 克隆项目
```bash
git clone https://github.com/your-repo/union-all-api.git
cd union-all-api
```

#### 2. 安装第三方SDK
项目依赖三个电商平台的SDK，需要手动安装到本地Maven仓库：

```bash
# 京东联盟SDK
mvn install:install-file \
  -Dfile=union-web/src/main/resources/lib/open-api-sdk-2.0-2024-09-27.jar \
  -DgroupId=open.api.sdk \
  -DartifactId=open-api-sdk \
  -Dversion=2.0 \
  -Dpackaging=jar

# 淘宝联盟SDK
mvn install:install-file \
  -Dfile=union-web/src/main/resources/lib/taobao-sdk-NEW_JAVA.jar \
  -DgroupId=tao.bao.sdk \
  -DartifactId=taobao-sdk-java-auto \
  -Dversion=1.1 \
  -Dpackaging=jar

# 拼多多多多客SDK
mvn install:install-file \
  -Dfile=union-web/src/main/resources/lib/pop-sdk-1.18.41-all.jar \
  -DgroupId=pop.sdk \
  -DartifactId=pop-sdk \
  -Dversion=1.18.41 \
  -Dpackaging=jar
```

#### 3. 数据库配置
创建MySQL数据库并配置连接信息：

```sql
-- 创建数据库
CREATE DATABASE union DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 创建用户(可选)
CREATE USER 'union'@'%' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON union.* TO 'union'@'%';
FLUSH PRIVILEGES;
```

#### 4. 修改配置文件
复制并修改配置文件：

```bash
# 复制开发环境配置
cp union-web/src/main/resources/application-dev.yml union-web/src/main/resources/application-local.yml
```

修改 `application-local.yml` 中的数据库和Redis连接信息：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/union?useUnicode=true&characterEncoding=utf8&serverTimezone=GMT%2B8
    username: your_username
    password: your_password
  data:
    redis:
      host: localhost
      port: 6379
      password: your_redis_password
```

#### 5. 编译和运行
```bash
# 编译项目
mvn clean compile

# 运行项目
mvn spring-boot:run -pl union-web

# 或者打包后运行
mvn clean package
java -jar union-web/target/union-web.jar --spring.profiles.active=local
```

#### 6. 验证部署
访问以下地址验证部署是否成功：
- 应用健康检查: http://localhost:8888/actuator/health
- API文档: http://localhost:8888/doc.html

## 🐳 Docker部署

### 方式一：Docker Compose一键部署

1. **准备部署文件**
```bash
# 创建部署目录
mkdir -p docker/deploy
cd docker/deploy
```

2. **创建docker-compose.yml**
```yaml
version: '3.8'

services:
  mysql:
    image: mysql:8.0
    container_name: union-mysql
    environment:
      MYSQL_ROOT_PASSWORD: admin123
      MYSQL_DATABASE: union
      MYSQL_USER: union
      MYSQL_PASSWORD: union123
    ports:
      - "3306:3306"
    volumes:
      - mysql_data:/var/lib/mysql
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
    command: --default-authentication-plugin=mysql_native_password
    networks:
      - union-network

  redis:
    image: redis:7-alpine
    container_name: union-redis
    command: redis-server --requirepass admin123
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    networks:
      - union-network

  union-app:
    image: union-all-api:latest
    container_name: union-app
    ports:
      - "48080:48080"
    environment:
      SPRING_PROFILES_ACTIVE: docker
      SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/union?useUnicode=true&characterEncoding=utf8&serverTimezone=GMT%2B8
      SPRING_DATASOURCE_USERNAME: union
      SPRING_DATASOURCE_PASSWORD: union123
      SPRING_DATA_REDIS_HOST: redis
      SPRING_DATA_REDIS_PASSWORD: admin123
    depends_on:
      - mysql
      - redis
    networks:
      - union-network

volumes:
  mysql_data:
  redis_data:

networks:
  union-network:
    driver: bridge
```

3. **构建和启动服务**
```bash
# 构建应用镜像
docker build -t union-all-api:latest -f ../union-web/src/main/resources/docker/Dockerfile .

# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f union-app
```

### 方式二：单独部署

```bash
# 1. 启动MySQL
docker run -d --name union-mysql \
  -e MYSQL_ROOT_PASSWORD=admin123 \
  -e MYSQL_DATABASE=union \
  -p 3306:3306 \
  mysql:8.0

# 2. 启动Redis
docker run -d --name union-redis \
  -p 6379:6379 \
  redis:7-alpine redis-server --requirepass admin123

# 3. 构建应用镜像
mvn clean package
docker build -t union-all-api:latest -f union-web/src/main/resources/docker/Dockerfile union-web/target/

# 4. 启动应用
docker run -d --name union-app \
  -p 48080:48080 \
  --link union-mysql:mysql \
  --link union-redis:redis \
  -e SPRING_PROFILES_ACTIVE=docker \
  union-all-api:latest
```

### 服务访问地址
- **应用服务**: http://localhost:48080
- **API文档**: http://localhost:48080/doc.html
- **健康检查**: http://localhost:48080/actuator/health

## 🎯 主要功能模块

### 1. 用户管理系统
- **用户注册登录**: 支持微信授权登录
- **用户信息管理**: 头像、昵称、个人信息维护
- **邀请关系**: 多级邀请关系管理和统计
- **签到系统**: 每日签到奖励机制

### 2. 订单追踪系统
- **实时订单同步**:
  - 京东联盟订单自动同步
  - 淘宝联盟订单自动同步
  - 拼多多订单自动同步
- **订单状态追踪**: 订单全生命周期状态管理
- **售后订单处理**: 退款、退货订单状态更新
- **订单佣金计算**: 智能佣金计算和分配

### 3. 佣金管理系统
- **多级分销配置**: 支持多层级分销体系
- **佣金自动结算**: 定时任务自动结算佣金
- **提现管理**:
  - 提现申请和审核流程
  - 微信支付自动打款
  - 提现记录和状态追踪
- **账户流水记录**: 详细的资金流水记录

### 4. 平台对接系统
- **京东联盟**:
  - 商品信息获取
  - 推广链接生成
  - 订单数据同步
- **淘宝联盟**:
  - 商品搜索和详情
  - 优惠券信息获取
  - 订单追踪
- **拼多多多多客**:
  - 商品推广
  - 订单同步
  - 佣金结算

### 5. 微信生态集成
- **微信公众号**:
  - 用户关注和消息推送
  - 菜单配置和自动回复
  - 二维码生成和扫码登录
- **微信支付**:
  - 提现到微信零钱
  - 支付状态回调处理
  - 资金安全保障

### 6. 数据统计分析
- **用户数据**: 用户增长、活跃度分析
- **订单数据**: 订单量、成交额统计
- **佣金数据**: 佣金收入、分销效果分析
- **平台数据**: 各平台业务数据对比



## ⚙️ 配置说明

### 应用配置

主要配置文件位于 `union-web/src/main/resources/` 目录下：

- `application.yml`: 基础配置
- `application-dev.yml`: 开发环境配置
- `application-test.yml`: 测试环境配置
- `application-prod.yml`: 生产环境配置(需要创建)

### 关键配置项

#### 1. 数据库配置
```yaml
spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/union?useUnicode=true&characterEncoding=utf8&serverTimezone=GMT%2B8
    username: your_username
    password: your_password
```

#### 2. Redis配置
```yaml
spring:
  data:
    redis:
      host: localhost
      port: 6379
      password: your_password
      timeout: 10s
```

#### 3. 微信配置
```yaml
wechat:
  mp:
    configs:
      - appId: your_app_id
        secret: your_app_secret
        token: your_token
        aesKey: your_aes_key
  pay:
    appId: your_pay_app_id
    mchId: your_mch_id
    mchKey: your_mch_key
    keyPath: classpath:pay/apiclient_cert.p12
```

#### 4. 电商平台配置
```yaml
# 京东联盟配置
jd:
  server-url: https://api.jd.com/routerjson
  app-key: your_jd_app_key
  app-secret: your_jd_app_secret

# 淘宝联盟配置
taobao:
  app-key: your_taobao_app_key
  secret: your_taobao_secret
  server-url: https://eco.taobao.com/router/rest
  adzone-id: your_adzone_id

# 拼多多配置
pdd:
  client-id: your_pdd_client_id
  client-secret: your_pdd_client_secret
  pid: your_pdd_pid
```

## 🔧 开发指南

### API接口文档

项目集成了Knife4j，启动项目后可以通过以下地址访问API文档：
- 开发环境: http://localhost:8888/doc.html
- 生产环境: http://your-domain/doc.html

### 主要接口说明

#### 用户相关接口
- `POST /app/user/login` - 用户登录
- `GET /app/user/info` - 获取用户信息
- `POST /app/user/sign` - 每日签到

#### 订单相关接口
- `POST /union/order/page` - 订单列表查询
- `GET /union/order/sync/jd` - 同步京东订单
- `GET /union/order/sync/taobao` - 同步淘宝订单
- `GET /union/order/sync/pdd` - 同步拼多多订单

#### 账户相关接口
- `GET /app/account/info` - 账户信息
- `POST /app/account/cash/apply` - 申请提现
- `POST /app/account/log/page` - 账户流水

### 定时任务

系统包含以下定时任务：

| 任务类 | 执行频率 | 功能说明 |
|--------|----------|----------|
| JdOrderSyncJob | 每小时 | 同步京东订单数据 |
| TaobaoOrderSyncJob | 每小时 | 同步淘宝订单数据 |
| PddOrderSyncJob | 每小时 | 同步拼多多订单数据 |
| UnionOrderSettleJob | 每天凌晨 | 订单佣金结算 |
| CheckSyncInterruptionsJob | 每30分钟 | 检查同步中断 |

### 事件系统

项目使用Spring Event实现业务解耦：

- `OrderSyncEvent`: 订单同步事件
- `UnionOrderUpdateEvent`: 订单更新事件
- `UnionOrderSettleEvent`: 订单结算事件
- `UnionAccountUpdateEvent`: 账户更新事件


## 📱 功能展示

### 移动端界面

<div align="center">

| 查询返利 | 提现功能 | 签到和余额 |
|:--------:|:--------:|:----------:|
| <img src="images/查询返利.jpg" alt="查询返利" width="200"> | <img src="images/提现.jpg" alt="提现" width="200"> | <img src="images/签到和余额.jpg" alt="签到和余额" width="200"> |

</div>

### 主要功能特性

- ✅ **商品搜索**: 支持关键词搜索各平台优惠商品
- ✅ **返利查询**: 实时查询商品返利金额和优惠信息
- ✅ **订单追踪**: 完整的订单状态追踪和佣金计算
- ✅ **账户管理**: 余额查询、流水记录、提现申请
- ✅ **邀请分销**: 多级邀请关系和佣金分成
- ✅ **签到奖励**: 每日签到获得奖励金额
- ✅ **微信集成**: 微信登录、支付、消息推送

## 🚀 部署上线

### 生产环境部署

1. **服务器要求**
   - CPU: 2核心以上
   - 内存: 4GB以上
   - 磁盘: 50GB以上
   - 操作系统: CentOS 7+/Ubuntu 18+

2. **环境准备**
```bash
# 安装Java 21
wget https://download.oracle.com/java/21/latest/jdk-21_linux-x64_bin.tar.gz
tar -xzf jdk-21_linux-x64_bin.tar.gz
sudo mv jdk-21.0.1 /opt/java
echo 'export JAVA_HOME=/opt/java' >> ~/.bashrc
echo 'export PATH=$JAVA_HOME/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 安装MySQL
sudo yum install mysql-server
sudo systemctl start mysqld
sudo systemctl enable mysqld

# 安装Redis
sudo yum install redis
sudo systemctl start redis
sudo systemctl enable redis
```

3. **应用部署**
```bash
# 构建生产包
mvn clean package -P prod

# 创建应用目录
sudo mkdir -p /opt/union-app
sudo cp union-web/target/union-web.jar /opt/union-app/app.jar

# 创建启动脚本
cat > /opt/union-app/start.sh << 'EOF'
#!/bin/bash
cd /opt/union-app
nohup java -jar -Xmx2g -Xms1g \
  -XX:+UseG1GC \
  -XX:MaxGCPauseMillis=200 \
  -Dspring.profiles.active=prod \
  app.jar > app.log 2>&1 &
echo $! > app.pid
EOF

chmod +x /opt/union-app/start.sh

# 启动应用
/opt/union-app/start.sh
```

4. **Nginx反向代理**
```nginx
server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:8888;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

### 监控和运维

1. **应用监控**
   - 使用Spring Boot Actuator进行健康检查
   - 集成Prometheus + Grafana监控
   - 日志收集和分析

2. **数据备份**
```bash
# MySQL备份脚本
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
mysqldump -u root -p union > /backup/union_$DATE.sql
find /backup -name "union_*.sql" -mtime +7 -delete
```

## 🤝 贡献指南

### 开发规范

1. **代码规范**
   - 遵循阿里巴巴Java开发手册
   - 使用统一的代码格式化配置
   - 编写完整的JavaDoc注释


### 参与贡献

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🆘 技术支持

### 常见问题

**Q: 启动时提示找不到SDK依赖？**
A: 请确保已经按照文档安装了三个电商平台的SDK到本地Maven仓库。

**Q: 数据库连接失败？**
A: 检查数据库配置信息，确保MySQL服务正常运行，数据库已创建。

**Q: Redis连接超时？**
A: 检查Redis服务状态和网络连接，确认密码配置正确。

**Q: 微信接口调用失败？**
A: 检查微信公众号配置信息，确保AppID、AppSecret等参数正确。

### 联系我们

如果您在使用过程中遇到问题，或者有功能建议，欢迎通过以下方式联系我们：

- 📧 邮箱: support@union-api.com
- 💬 微信: 备注来意
- 🐛 Issues: [GitHub Issues](https://github.com/your-repo/union-all-api/issues)

<div align="center">
  <img src="images/微信号.jpg" alt="微信号" width="300">
  <p><em>扫码添加微信，备注"返利系统"</em></p>
</div>

---

<div align="center">

**⭐ 如果这个项目对您有帮助，请给我们一个Star！⭐**

Made with ❤️ by Union Team

</div>