# pd-admin-backend

**Repository Path**: oneonly/pd-admin-backend

## Basic Information

- **Project Name**: pd-admin-backend
- **Description**: 拼豆手工体验馆门店管理系统后端服务，基于 Spring Boot 3.2 + JDK 21，提供 RESTful API，支持 PC 管理后台、顾客小程序、商家 H5 三端接入。
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-27
- **Last Updated**: 2026-06-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 拼豆门店管理系统 - 后端服务

<p align="center">
  <img src="https://img.shields.io/badge/Spring_Boot-3.2-6DB33F?logo=springboot" alt="Spring Boot 3.2" />
  <img src="https://img.shields.io/badge/JDK-21-ED8B00?logo=openjdk" alt="JDK 21" />
  <img src="https://img.shields.io/badge/MySQL-8.0-4479A1?logo=mysql" alt="MySQL 8.0" />
  <img src="https://img.shields.io/badge/MyBatis_Plus-3.5-1E90FF" alt="MyBatis Plus 3.5" />
  <img src="https://img.shields.io/badge/Spring_Security-6.2-6DB33F?logo=springsecurity" alt="Spring Security 6.2" />
  <img src="https://img.shields.io/badge/JWT-0.12-000000" alt="JWT 0.12" />
  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT" />
</p>

> 🟢 拼豆手工体验馆门店管理系统后端服务，基于 Spring Boot 3.2 + JDK 21，提供 RESTful API，支持 PC 管理后台、顾客小程序、商家 H5 三端接入。

---

## 📖 项目简介

`pd-admin-backend` 是 [拼豆门店管理系统](https://gitee.com/yourname/pd-shop-root) 的后端服务，基于 Spring Boot 3.2 构建。采用经典三层架构（Controller → Service → Mapper），提供统一的 RESTful API，支持 JWT 无状态认证和基于角色的权限控制。

---

##  :foggy: 截图
![输入图片说明](img/%E9%A6%96%E9%A1%B5.png)
![输入图片说明](img/%E6%A1%8C%E5%8F%B0%E7%AE%A1%E7%90%86.png)

## 🏗️ 架构设计

```
┌──────────────────────────────────────────────────┐
│                  前端层（三端）                   │
│  🖥️ PC 管理后台    📱 顾客小程序    📲 商家 H5    │
├──────────────────────────────────────────────────┤
│              🔐 Spring Security + JWT            │
│           │  /api/admin/*  │  /api/merchant/*     │
│           │    BOSS/STAFF   │    BOSS/STAFF       │
│           └────────┬───────┘                      │
│                    │                              │
│              🎯 Controller 层（13 个）            │
│                    │                              │
│              ⚙️ Service 层（11 个）               │
│                    │                              │
│              🗄️ Mapper 层（20 个）                │
│                    │                              │
│              🐬 MySQL 8.0                         │
└──────────────────────────────────────────────────┘
```

---

## ✨ 功能特性

### 🔐 认证鉴权

| 功能 | 说明 |
|------|------|
| 🔑 JWT 登录 | 店员账号密码登录，返回 JWT Token |
| 🛡️ 角色鉴权 | BOSS/STAFF 两级角色，接口级权限控制 |
| ⏰ Token 刷新 | 24 小时有效期，可配置 |

### 🏪 店铺管理（`/api/admin/*`）

| 功能 | 说明 |
|------|------|
| 🏪 店铺配置 | 店铺基础信息、营业时间、联系方式 |
| 👥 店员管理 | 店员增删改查、修改密码、角色分配 |
| 💰 计价方案 | 小时单价、全天套餐、包段计费 |
| 🪑 桌台管理 | 桌台状态、开台/清台、计时计费 |
| 📦 商品管理 | 分类/色号维护、商品上下架 |
| 🏭 采购入库 | 采购单创建、确认入库 |
| 📋 库存盘点 | 盘点单创建、盈亏调整 |
| ⚠️ 库存预警 | 低库存阈值、预警查询 |

### 💰 收银端（`/api/merchant/*`）

| 功能 | 说明 |
|------|------|
| 🧾 订单结算 | 混合计费（桌台费+商品费）、支付、退款 |
| 👤 会员管理 | 会员注册、储值充值、积分管理、消费流水 |
| 🎟️ 优惠券 | 优惠券发放、领用、核销 |
| 🎫 团购核销 | 美团/抖音/小红书券码核销、记录查询 |

---

## 🛠 技术栈

| 类别 | 技术 | 版本 | 说明 |
|------|------|------|------|
| 基础框架 | Spring Boot | 3.2.5 | 主框架 |
| JDK | Java | 21 | LTS 长期支持 |
| 安全认证 | Spring Security + JWT | 6.2 + 0.12.6 | 无状态会话，角色鉴权 |
| ORM | MyBatis-Plus | 3.5.9 | 内置逻辑删除、分页、自动填充 |
| 数据库 | MySQL | 8.0+ | 主数据库 |
| 连接池 | HikariCP | — | Spring Boot 默认 |
| API 文档 | Knife4j | 4.5.0 | 增强 Swagger UI，中文界面 |
| 工具库 | Hutool | 5.8.44 | 日期、加密、集合等工具 |
| Excel | EasyExcel | 4.0.0 | 报表导出 |
| JSON | Jackson | — | Spring Boot 默认序列化 |

---

## 📁 项目结构

```
pd-admin-backend/
├── pom.xml                                  # Maven 依赖管理
├── README.md
└── src/main/
    ├── resources/
    │   └── application.yml                  # 应用配置
    └── java/com/pdshop/
        ├── PdShopApplication.java           # 🚀 启动类
        ├── config/                          # ⚙️ 配置类
        │   ├── CorsConfig.java              # 跨域配置
        │   ├── JacksonConfig.java           # JSON 序列化
        │   ├── MyBatisPlusConfig.java       # 分页插件
        │   └── SecurityConfig.java          # Spring Security
        ├── common/                          # 📦 通用模块
        │   ├── Result.java                  # 统一响应体
        │   ├── PageResult.java              # 分页响应体
        │   ├── ResultCode.java              # 错误码枚举
        │   ├── BizException.java            # 业务异常
        │   ├── GlobalExceptionHandler.java  # 全局异常处理
        │   └── enums/                       # 业务枚举（9 个）
        ├── security/                        # 🔐 认证鉴权
        │   ├── JwtTokenProvider.java        # JWT 生成/校验
        │   ├── JwtAuthenticationFilter.java # 请求拦截器
        │   ├── LoginUser.java               # 登录用户模型
        │   └── SecurityUtils.java           # 安全上下文工具
        ├── entity/                          # 🗂️ 实体类（20 个）
        ├── mapper/                          # 🗄️ Mapper 接口（20 个）
        ├── dto/                             # 📥 请求参数（15 个）
        ├── vo/                              # 📤 响应对象（7 个）
        ├── service/                         # ⚙️ 业务层（11 个）
        ├── controller/                      # 🎯 控制层（13 个）
        └── util/                            # 🛠️ 工具类
            ├── OrderNoUtils.java            # 订单号生成
            └── PriceCalculator.java         # 计费计算器
```

---

## 🚀 快速开始

### 环境要求

| 工具 | 版本 |
|------|------|
| JDK | 21+ |
| MySQL | 8.0+ |
| Maven | 3.8+ |

### 1️⃣ 创建数据库

```sql
CREATE DATABASE IF NOT EXISTS pd_shop_db
    DEFAULT CHARACTER SET utf8mb4
    DEFAULT COLLATE utf8mb4_general_ci;
```

### 2️⃣ 执行建表 SQL

```bash
mysql -u root -p pd_shop_db < ../docs/02-设计/sql_schema.sql
```

### 3️⃣ 配置数据库连接

编辑 `src/main/resources/application.yml`，或通过环境变量覆盖：

```bash
# 环境变量方式（推荐）
set MYSQL_PASSWORD=你的密码
```

### 4️⃣ 启动项目

```bash
cd code/pd-admin-backend
mvn clean compile spring-boot:run
```

启动成功后会显示：

```
Started PdShopApplication in X.XXX seconds
```

### 5️⃣ 访问 API 文档

浏览器打开：**http://localhost:8080/doc.html**

---

## 🔌 核心 API

### 认证方式

所有管理端和收银端接口需在请求头中携带 Token：

```
Authorization: Bearer <token>
```

> 💡 在 Knife4j 中：先调用登录接口 → 复制返回的 Token → 点击右上角 **Authorize** → 填入 `Bearer <token>`

### 公共接口（`/api/common/**`）

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/common/login` | POST | 店员登录，返回 JWT Token |

### 管理端接口（`/api/admin/**`）— 老板/店员

| 模块 | Controller | 说明 |
|------|------|------|
| 👥 店员管理 | `StaffController` | 增删改查、修改密码 |
| 🏪 店铺配置 | `ShopConfigController` | 店铺信息维护 |
| 🪑 桌台管理 | `TableController` | 开台、清台、计时 |
| 💰 计价方案 | `PricingController` | 小时单价、全天套餐 |
| 📦 商品管理 | `ProductController` | 色号、库存、预警 |
| 🏭 采购入库 | `PurchaseController` | 采购单、确认入库 |
| 📋 库存盘点 | `StockController` | 盘点单、盈亏调整 |

### 收银端接口（`/api/merchant/**`）— 老板/店员

| 模块 | Controller | 说明 |
|------|------|------|
| 🧾 订单结算 | `OrderController` | 混合计费、支付、退款 |
| 👤 会员管理 | `MemberController` | 储值、积分、流水 |
| 🎟️ 优惠券 | `CouponController` | 发放、使用 |
| 🎫 团购核销 | `VoucherController` | 美团/抖音/小红书 |

---

## 🔐 角色权限

| 角色 | 角色码 | 权限范围 |
|------|------|------|
| 👑 老板 | `BOSS` | 全部管理端 + 收银端 |
| 👔 店员 | `STAFF` | 全部管理端 + 收银端 |
| 👤 会员 | `MEMBER` | 小程序端（预留） |

---

## 🗄️ 数据库设计

核心业务表 20 张，统一规范：

| 规范 | 说明 |
|------|------|
| 🔑 主键 | `id` BIGINT 自增 |
| ⏱️ 审计字段 | `create_time`、`update_time`（自动填充） |
| 🗑️ 逻辑删除 | `is_deleted`（0=正常，1=已删除） |
| 💵 金额字段 | `decimal(10,2)` |

### 核心表清单

| 模块 | 表名 | 说明 |
|------|------|------|
| 🏪 基础配置 | `shop_config` | 店铺配置表 |
| 👥 权限管理 | `staff`, `role`, `permission` | 店员账号权限表 |
| 👤 会员营销 | `member`, `member_recharge`, `coupon`, `member_coupon` | 会员及优惠券管理 |
| 🪑 桌台管理 | `table`, `pricing_scheme` | 桌台状态与计价方案 |
| 📦 库存物料 | `product`, `product_category`, `inventory`, `purchase`, `stock_take` | 拼豆商品及库存管理 |
| 🧾 交易订单 | `order`, `order_item` | 订单主表及明细表 |
| 🎫 团购核销 | `group_buy_voucher` | 团购券核销表 |

> 📚 详细设计文档见：`docs/02-设计/database_design.md`

---

## ⚙️ 配置说明

| 配置项 | 默认值 | 说明 |
|------|------|------|
| `server.port` | 8080 | 服务端口 |
| `spring.datasource.url` | `jdbc:mysql://localhost:3306/pd_shop_db` | 数据库连接 |
| `spring.datasource.password` | `${MYSQL_PASSWORD:xy123456}` | 优先取环境变量 |
| `jwt.expiration` | 86400000（24h） | Token 有效期（毫秒） |
| `knife4j.enable` | true | 生产环境建议设为 false |

---

## 📐 开发规范

### 统一返回格式

```json
{
  "code": 200,
  "message": "success",
  "data": {},
  "timestamp": 1719436800000
}
```

| 规范 | 说明 |
|------|------|
| 📦 统一响应 | `Result<T>`（含 `code`、`message`、`data`） |
| 📄 分页响应 | `PageResult<T>`（含 `total`、`list`） |
| ❌ 异常处理 | 业务异常使用 `BizException`，由全局异常处理器统一捕获 |
| 🗂️ 实体规范 | 统一继承 MyBatis-Plus 逻辑删除、自动填充 |
| 🔢 编号生成 | 订单号、流水号由 `OrderNoUtils` 统一生成 |

---

## 🗺️ 路线图

- [x] Spring Boot 3.2 基础框架搭建
- [x] JWT 无状态认证 + 角色鉴权
- [x] 店铺配置与店员管理
- [x] 桌台开台/清台/计时计费
- [x] 商品分类、色号、库存管理
- [x] 采购入库、库存盘点
- [x] 订单结算（混合计费）
- [x] 会员储值、积分、优惠券
- [x] 团购券核销
- [x] Knife4j API 文档
- [x] 统一异常处理与响应格式
- [ ] 微信小程序登录对接
- [ ] 微信支付集成
- [ ] 操作日志 AOP 记录
- [ ] 接口限流
- [ ] Docker 镜像构建

---

## 🤝 贡献指南

1. Fork 本仓库
2. 创建功能分支 `git checkout -b feature/AmazingFeature`
3. 提交代码 `git commit -m 'feat: add some amazing feature'`
4. 推送分支 `git push origin feature/AmazingFeature`
5. 创建 Pull Request

---

## 📄 许可证

MIT License © 2024 拼豆手工体验馆

---

## 🔗 相关项目

| 项目 | 说明 | 地址 |
|------|------|------|
| 拼豆门店管理系统 | 完整项目仓库 | [Gitee](https://gitee.com/yourname/pd-shop-root) |
| pd-admin-web | PC 后台管理端 | `code/pd-admin-web` |
| pd-admin-mini-program | 顾客微信小程序 | `code/pd-admin-mini-program` |
| pd-admin-h5 | 商家移动端 H5 | `code/pd-admin-h5` |

---

<p align="center">
  ⭐ 如果这个项目对你有帮助，请给个 Star 支持一下！
</p>