源码专题-java0160-基于 Spring Boot快递管理系统

快递管理系统项目说明文档

> **中文名称**：基于 SpringBoot 的快递配送综合管理平台

> **数据库**：MySQL 5.7 / `springbootgbu3f`

> **上下文根**：`/springbootgbu3f`　默认端口：`8080`

一、项目简介

本项目是一套 **面向"用户 + 快递员 + 管理员"三端协同** 的快递业务信息化平台。围绕快递运作的完整链路——**寄件下单 → 快递入库 → 配送派送 → 取件核销**——为不同角色提供了独立的功能视图，并在管理端沉淀了统计分析、审核支付、系统配置等基础能力。项目采用前后端分离架构，后端基于 Spring Boot 提供 RESTful API，前端使用 Vue 2 + Element UI 构建响应式管理后台。

二、技术栈总览

后端技术栈

| 分类 | 技术 / 组件 | 版本 | 作用 |

| **持久层** | MyBatis-Plus | 2.3 | 无侵入的增强 MyBatis，简化 CRUD |

| **持久层** | mybatis-spring-boot-starter | 2.1.1 | MyBatis 与 Boot 整合 |

| **数据库** | MySQL Connector-J | 8.x | JDBC 驱动 |

| **数据库** | MSSQL / sqljdbc4 | 6.2 / 4.0 | 备用 SQL Server 驱动 |

| **安全** | Apache Shiro | 1.3.2 | 权限框架（辅助） |

| **认证** | 自研 Token 机制 | — | 基于拦截器 + Token 表的会话方案 |

| **工具** | Hutool-all | 4.0.12 | 全能 Java 工具类库 |

| **工具** | Apache Commons Lang3 / IO | 3.0 / 2.5 | 字符串、文件工具 |

| **序列化** | Protobuf-java | 3.10.0 | 高性能二进制序列化 |

| **语言** | Java | 1.8 | — |

前端技术栈

| 分类 | 技术 / 组件 | 版本 | 作用 |

| **路由** | Vue Router | 3.1.5 | 单页应用路由 |

| **图表** | ECharts + vue-echarts | 5.4 / 6.2 | 数据可视化 |

| **HTTP** | Axios | 0.19 | 请求库 |

| **地图** | vue-amap | 0.5 | 高德地图组件（地址定位） |

| **富文本** | vue-quill-editor | 3.0 | 富文本编辑器 |

| **打印** | print-js | 1.5 | 前端打印工具 |

| **导出** | vue-json-excel | 0.3 | JSON 一键转 Excel |

| **加密** | js-md5 | 0.7 | 前端 MD5 加密 |

| **样式** | SASS / SCSS | 1.32 | CSS 预处理器 |

| **包管理** | pnpm | — | 高效的包管理器

三、系统角色与核心功能

系统内共设计 **三种真实角色 + 一个系统级 Token 服务**，通过统一的 Token 拦截器进行接口鉴权，登录时根据角色写入 Session 中的 `tableName / role / username / userId`，用于数据的行级隔离过滤。

角色一：系统管理员（Admin / users 表）

> 定位：**系统的最高操作者**，负责全局资源管理和运营决策。

账号安全：登录（Token 生成）、注册（用户名唯一性校验）、退出（Session 失效）、密码重置（默认恢复123456）
用户与员工管理：对普通用户、快递员的完整增删改查、分页检索、字段模糊过滤
业务全域可见：可查看所有寄件信息、快递信息、取件信息、配送信息
业务审核：通过/sh/{tableName} 通用接口，对寄件订单的sfsh 审核状态进行"通过 / 驳回 / 待审核"的更新
数据统计中心：借助/cal、/group、/value、/value/.../{timeStatType} 一系列通用统计接口，实现按列求和、分组统计、按值统计、按时间维度（天/月/年）统计等分析能力
系统配置：管理config 表中的键值对，包括轮播图、人脸识别文件（faceFile）等
通用能力：文件上传下载、联动下拉选项、按列值反查记录、提醒计数（数字/日期类型两种模式）

角色二：普通用户（Yonghu / yonghu 表）

> 定位：**寄件的发起方（客户）**，需要一站式完成下单、跟进、支付。

账号安全：用户注册（账号唯一性校验）、登录（生成角色为用户 的 Token）、退出、忘记密码重置
发起寄件：填写寄件人、收件人、物品名称/图片、重量，系统按起步价 + 单价×重量计算费用，订单默认审核状态为"待审核"、支付状态为"未支付"
订单跟踪：查看仅属于自己账号（yonghuzhanghao 隔离） 的寄件订单、配送信息、取件信息——JijianxinxiControllerpage 在 Session 检测到tableName == yonghu 时自动带上账号过滤条件，实现严格的数据行级隔离
在线支付：通过ispay 字段进行订单支付状态流转
消息提醒：调用/yonghu/remind/{columnName}/{type} 获取账号相关的提醒计数（如未支付订单、待审核订单等）
个人中心：维护个人信息、性别、电话、头像

角色三：快递员（Kuaidiyuan / kuaidiyuan 表）

> 定位：**快递作业的执行者**，覆盖从收件、入库、派送到确认取件的全流程。

账号安全：员工账号yuangongzhanghao 登录 / 注册 / 密码重置，登录时生成角色为快递员 的 Token
快递信息管理：录入并维护kuaidixinxi（快递编号、名称、取件站点、时间、快递详情），可关联当前作业员工
配送作业：在peisongxinxi 中更新配送状态（配送中、已签收等）、配送详情、更新时间，供用户跟踪
取件确认：登记qujianxinxi（取件码、快递名称、站点、备注、取件时间），闭环订单流程
个人中心：维护员工姓名、性别、电话、头像

四、项目亮点

亮点 1：三端角色协同 + 行级数据隔离

登录时通过 `TokenServicegenerateToken(userId, username, tableName, role)` 将角色所属表名写入 Token，拦截器再把 `tableName / role / username / userId` 存入 Session。控制器（如 `JijianxinxiController`）通过 Session 中的 `tableName` 判断当前登录者是否为普通用户，自动追加 `yonghuzhanghao` 过滤条件——**同一套接口，同一段代码，天然实现三端权限视图差异**，无需为不同角色写重复接口。

亮点 2：可配置的 Token 拦截器 +`@IgnoreAuth` 白名单注解

`AuthorizationInterceptor` 拦截 `/**` 全部请求，自动处理 CORS、跨域 OPTIONS 预检，识别方法上的 `@IgnoreAuth` 注解跳过登录 / 注册 / 公开列表等接口。**鉴权即注解**，控制器只需在需要放行的方法上加一行 `@IgnoreAuth` 即可，简洁清晰。

亮点 3：MyBatis-Plus 全套增强，超轻 CRUD

主键策略灵活：ID 由时间戳 + 随机数生成，兼顾唯一性与可读性
逻辑删除内置：logic-delete-value=-1 / logic-not-delete-value=0，无需手工判断
驼峰下划线自动转换：字段命名规范一次配置，全局生效
MPUtil 通用查询构造器：likeOrEq / between / allEQMapPre / sort 一行代码生成模糊查询、区间过滤、精确匹配、排序，把 90% 的 CRUD 简化为链式调用

亮点 4：通用统计与可视化服务

`CommonController` 提供了一组"表名 + 列名 + 类型"驱动的通用统计接口，配合前端 `echarts` 图表组件，实现无需为每张表编写统计接口：

| 接口 | 能力 |

| `/cal/{table}/{col}` | 列求和 |

| `/group/{table}/{col}` | 按列分组计数 |

| `/value/{table}/{x}/{y}` | XY 轴聚合 |

| `/value/{table}/{x}/{y}/{timeStatType}` | 时间维度聚合（日/月/年） |

| `/remind/{table}/{col}/{type}` | 提醒计数（数字型 or 日期偏移型） |

| `/option/{table}/{col}` | 联动下拉数据源 |

| `/follow/{table}/{col}` | 按列值反查完整记录 |

前端 `board.vue` 直接消费这些接口，图表零耦合业务代码。

亮点 5：AI 能力集成——百度人脸识别

`FileControllerupload` 支持 `type=1` 特殊类型：上传后自动将文件名写入 `config` 表的 `faceFile` 键；配合 `BaiduUtil` + `AipFace` SDK，为登录、身份核验等场景预留了 **人脸识别匹配** 的扩展能力，从"账号密码"迈向"生物特征"。

亮点 6：审核 + 支付双状态流转

寄件订单同时具备 **审核（sfsh：待审核 / 是 / 否 + 审核回复 shhf）** 与 **支付（ispay：已支付 / 未支付）** 两条独立的状态流：

- 用户发单后，管理员审核并可附加驳回原因

- 审核通过的订单进入支付环节，未支付订单可持续提醒

- **业务边界清晰**：审核走审核流、支付走支付流、配送走物流状态流，互不干扰

亮点 7：企业级工程能力

文件系统：上传路径统一到classpath:static/upload/，文件名以时间戳保证唯一，支持热部署路径回写（注释提示）
Excel 处理：内建 Apache POI，可对任意实体表进行导入导出扩展
多数据库支持：Maven 已集成 MySQL 与 SQL Server 双驱动，切换数据源零成本
富前端交互：Vue 端集成富文本编辑器 + 高德地图 + ECharts + 打印 + Excel 导出，覆盖运营日常所有交互场景
响应统一：R.ok() / R.error() 链式风格 + 统一code / msg / data 响应体，前后端联调无沟通成本

亮点 8：友好的开箱即用体验

项目内置1-install.bat / 2-run.bat / 3-build.bat 三个批处理脚本，本地新手一键跑通
SQL 初始化脚本db/springbootgbu3f.sql 附带示例数据 8 条（用户、快递员、寄件订单、快递、配送、取件均已预填），下载即演示
默认管理员账号admin / admin 无需查文档即可登录

五、目录结构（后端核心）

```

springbootgbu3f/

├── src/main/java/com/

│ ├── annotation/ @IgnoreAuth / @LoginUser 自定义注解

│ ├── config/ 拦截器、MyBatis-Plus、支付宝配置

│ ├── controller/ 10 个 REST 控制器（含 5 大业务表 + 3 大角色 + 通用/文件）

│ ├── dao/ MyBatis Mapper 接口

│ ├── entity/ 实体类（含 view / vo / model 子包）

│ ├── interceptor/ AuthorizationInterceptor Token 鉴权

│ ├── service/ + impl/ 业务服务层

│ └── utils/ R / MPUtil / PageUtils / MD5Util / BaiduUtil 等

├── src/main/resources/

│ ├── application.yml 数据源、MyBatis-Plus、静态资源配置

│ ├── mapper/*.xml SQL 映射文件

│ ├── admin/ 打包后的 Vue 管理端静态资源

│ └── static/upload/ 用户上传文件目录

└── db/springbootgbu3f.sql 数据库初始化脚本（含示例数据）

六、快速启动

```bash

1. 导入数据库

mysql -uroot -proot < db/springbootgbu3f.sql

2. 后端启动

mvn spring-boot:run

3. 前端启动

cd springbootgbu3f-admin

pnpm install

pnpm serve

- 后端接口：`http://localhost:8080/springbootgbu3f`

- 管理端：`http://localhost:8080/springbootgbu3f/admin/dist/index.html`

- 默认管理员：`admin / admin`

- 示例用户：`user001 / 123456`

- 示例快递员：`kuaidi001 / 123456`

软件定制及其他业务

文章有帮助的话，在看，转发吧。

谢谢支持哟 (*^__^*）

快递管理系统 项目说明文档