# EDEN-MACE

**Repository Path**: codingdb/distribution_management

## Basic Information

- **Project Name**: EDEN-MACE
- **Description**: 微服务下的分销管理利器，更加灵活的管理佣金，涵盖并且总结了目前流行的分销模式，让分销更加简单,后期开发立足于产业互联网，致力于打通产业内部之间的联系，有问题可以加qq  3174667330，欢迎大家star,你的鼓励是开发的动力
- **Primary Language**: Java
- **License**: MulanPSL-1.0
- **Default Branch**: feature/V1.0
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1261
- **Forks**: 676
- **Created**: 2018-04-04
- **Last Updated**: 2026-08-20

## Categories & Tags

**Categories**: erp

**Tags**: None

## README

# 分销管理系统 · dist-admin

> 基于 **Spring Boot 3 + Java 21 + Vue 3** 的现代化前后端分离分销管理系统。以**分销为核心**：多级分润引擎、账户体系、会员关系树、开放 API，配套 DB 驱动的运营管理后台。

本系统由旧版 `EDEN-MACE`（Spring Boot 1.5 + Shiro + 双库）现代化重构而来：**分销核心业务逻辑完全不变**，仅对表结构与 ORM 映射重新设计，guns 的人员/角色/菜单/权限整合为统一 RBAC 体系，Shiro 鉴权替换为 Sa-Token。

---

## 登录与总览

![登录页](docs/screenshots/01-login.png)

![统计看板](docs/screenshots/02-dashboard.png)

后台采用 DB 驱动菜单 + 角色权限：登录后按角色聚合 `sys_menu` 动态渲染侧边栏，前端路由按菜单 `url` 动态注册，按钮级操作由权限码（`@SaCheckPermission` / `v-permission`）控制。

---

## 核心特性

| 特性 | 说明 |
|---|---|
| 🎯 **多级分润引擎** | 沿平台链 `disPlatFullIndex` 与会员链 `disFullIndex` 逐级分润，行为与旧系统逐行对齐，黄金用例验证金额不变 |
| ❄️ **分润状态机** | 订单 → `FROZEN`（冻结）→ `SETTLED`（确认收货 / T+N 入账）→ `REFUNDED`（退款冲正），按订单聚合、幂等推进 |
| 💰 **三态账户体系** | 每个账户 total / frozen / available 三态 × 交易/等级/邀请三套，金额原语 `addMoney`/`frozenAmount`/`reduceMoney`/`returnMoney`/`addFrozenMoney`，每次变动写流水 |
| ⚙️ **会员/平台商双套配置** | 分润、段位积分、垂直升级按 `identity_type`（0 会员 / 1 平台商）成对配置，配置走草稿/发布模型 |
| 🔐 **统一 RBAC** | `sys_user` / `sys_role` / `sys_menu` / `sys_role_menu`，Sa-Token 会话 + 权限码，多角色支持 |
| 🌳 **会员关系可视化** | 按 `dis_full_index` 展开上下级代理关系图 |
| 📡 **第三方开放 API** | `/api/v1/*` 自有 JWT 契约，供商城/外部系统对接 |

---

## 功能模块

### 📁 会员信息

会员管理、账单查询（账户余额）、代理关系图。

![会员管理](docs/screenshots/03-member.png)

![账单查询](docs/screenshots/04-account.png)

![代理关系图](docs/screenshots/13-agent-tree.png)

### 📁 分销配置

会员/平台商分润设置、段位积分设置、垂直升级配置、提现费率设置、分销字典管理。

![会员分润设置](docs/screenshots/05-profit-param.png)

![平台商分润设置](docs/screenshots/12-profit-param-agent.png)

![段位积分设置（双 Tab）](docs/screenshots/06-rank-param.png)

![垂直升级配置（双 Tab）](docs/screenshots/07-upgrade-param.png)

![提现费率设置](docs/screenshots/08-withdraw-param.png)

![分销字典管理](docs/screenshots/09-dict.png)

### 📁 交易中心

分润记录、提现记录（只读查询面，与提现审批写操作分离）。

![分润记录](docs/screenshots/10-profit-record.png)

![提现记录](docs/screenshots/11-withdraw-record.png)

### 📁 系统管理

用户、角色（含权限分配）、菜单、平台商管理。

![角色管理](docs/screenshots/14-role.png)

![菜单管理](docs/screenshots/15-menu.png)

![平台商管理](docs/screenshots/16-dept.png)

![用户管理](docs/screenshots/17-user.png)

---

## 技术栈

### 后端 `dist-admin-api`

| 维度 | 选型 |
|---|---|
| 语言 / 框架 | Java 21 · Spring Boot 3.2.5 |
| 持久层 | MyBatis-Plus 3.5.7（ASSIGN_ID 雪花主键、`@TableLogic` 逻辑删除、`@Version` 乐观锁） |
| 鉴权 | Sa-Token 1.37（替代旧 Shiro；MD5 1024 次迭代密码哈希，兼容旧账号） |
| 缓存 / 锁 | Redisson 3.27（生产）· 开发态可降级本地锁 · Spring Data Redis |
| 工具 | Hutool（JWT 等）· Lombok |
| 开发数据库 | H2 内嵌（MySQL 兼容模式，启动自动建表 + 灌种子数据） |
| 生产数据库 | MySQL 8 + Redis |

### 前端 `dist-admin-web`

| 维度 | 选型 |
|---|---|
| 框架 | Vue 3.4 · Vite 5 |
| UI | Element Plus 2.7（Ant Design 风格主题） |
| 状态 / 路由 | Pinia · Vue Router 4（动态路由注册） |
| 请求 | axios（开发态 vite proxy → 后端 8081） |

---

## 快速开始（零依赖开发态）

> 开发态默认 `profile=dev`：H2 内存库 + Sa-Token 内存会话，**无需安装 MySQL / Redis**，启动即自动建表并灌入种子数据。

### 1. 启动后端（端口 8081）

```bash
cd dist-admin-api
mvn spring-boot:run
```

启动成功标志：`Started DistAdminApiApplication ... on port(s): 8081`

### 2. 启动前端（端口 5173）

```bash
cd dist-admin-web
npm install      # 首次
npm run dev
```

浏览器打开 **http://localhost:5173**。

### 3. 一键启停（连本地 MySQL）

```bash
./start.sh     # 后端 prod + 前端 dev
./stop.sh
```

### 4. 默认账号

| 账号 | 密码 | 角色 |
|---|---|---|
| `admin` | `123456` | 超级管理员 |

> 种子数据还包含演示平台 `P1`、会员 `U1 / U2 / U3`、对应账户、分润配置、演示交易与分润记录等，便于联调。

---

## 接口概览

| 前缀 | 说明 | 代表端点 |
|---|---|---|
| `/auth` | 后台登录鉴权 | `POST /auth/login` · `GET /auth/info`（返回菜单树 + 权限码） |
| `/admin/dist/*` | 后台分销管理 | `dist-member` · `dist-profit-param` · `dist-account` · `dist-withdraw` · `dist-profit-record` · `dist-rank-param` · `dist-upgrade-param` · `dist-withdraw-param` · `dist-dict` · `dist-statistics` |
| `/admin/system/*` | RBAC 管理 | `menu` · `role` · `dept` |
| `/api/v1/*` | 第三方开放契约（自有 JWT） | `getUserInfo` · `memberAdd` · `trade` · `upgrade` · `withdraw` · `subordinate` · `settle` · `refund` · `getSign` |

分润状态机：订单 → `FROZEN`（冻结）→ `SETTLED`（确认收货 / T+N 入账）→ `REFUNDED`（退款冲正）。

---

## 项目结构

```
distribution_management/
├── dist-admin-api/        # 后端：分销核心 + RBAC + 开放 API
│   └── src/main/java/com/dist/admin/
│       ├── config/        # SaToken · Redisson · MybatisPlus · Web
│       ├── common/        # Result · ResultCode · 全局异常 · 枚举
│       ├── system/        # RBAC：auth · user · role · menu · dept · dict
│       └── dist/          # ❤️ 分销业务（逻辑冻结）
│           ├── api/       # 开放 API /api/v1/*
│           ├── controller/# 后台分销管理 REST
│           ├── service/   # 分润引擎 / 账户 / 会员
│           └── amount/    # 金额原语
├── dist-admin-web/        # 前端：管理后台 SPA（Vue3 + Element Plus）
├── docs/                  # 编码规范 + 系统截图（screenshots/）
└── README.md              # ← 本文件
```

---

## 生产部署

切换至生产配置（MySQL + Redis）：

1. 环境变量覆盖连接：`MYSQL_HOST` / `MYSQL_DATABASE` / `MYSQL_USERNAME` / `MYSQL_PASSWORD` / `REDIS_HOST` / `REDIS_PASSWORD`
2. 使用 `dist-admin-api/src/main/resources/db/schema.sql`（MySQL 权威建表）初始化数据库
3. Sa-Token 会话持久化到 Redis：在 `dist-admin-api/pom.xml` 加回 `sa-token-redis-jackson`
4. 启动时覆盖 profile：

```bash
java -jar dist-admin-api-*.jar --spring.profiles.active=prod
```

---

## License

见 [LICENSE](./LICENSE)。