校园快递代取管理系统

校园快递代取管理系统

本文档为项目的完整技术说明，涵盖系统架构、目录结构、双平台运行方式、功能细节、数据库策略及开发约定。面向需要全面了解或维护本项目的开发者与答辩评审。

学生日常运行与测试，优先阅读 README.md（Windows 一键运行说明）。

---

一、项目概述

本系统是一套校园快递代取管理平台，解决在校师生不便自取快递、代取员接单配送、管理员统一运营三类场景。

角色	入口	核心能力
师生用户	统一登录 → 师生用户	发单、虚拟支付、查单、收货、评价
代取员	统一登录 → 代取员	待接单、接单、更新配送状态、收益统计
系统管理员	统一登录 → 管理员	用户/代取员管控、订单与费用分析、公告管理

技术栈： Python 3.12、Flask 3.0、MySQL 5.7/8.0、原生 HTML + CSS + JavaScript、PyMySQL、Werkzeug（密码哈希）、ECharts 5.5（本地静态资源）。

设计原则（作业简化）：

• 虚拟支付，不涉及真实资金
• 代取费用由用户手填，不做距离计价
• 短信验证码 Mock，任意 6 位数字即可
• 管理员不可代客创建订单
• 禁用账号仅限制新发单/新接单，不强制终止进行中订单

---

二、系统架构

浏览器
   │
   ▼
app.py（Flask 入口）
   ├── utils/startup.py     启动前 MySQL 检测与库准备
   ├── routes/
   │     ├── auth_routes    统一登录 / 退出
   │     ├── user_routes    师生端
   │     ├── courier_routes 代取员端
   │     └── admin_routes   管理后台
   ├── utils/db.py          数据库读写封装
   ├── utils/auth.py        登录态与角色校验
   ├── utils/helpers.py     订单状态、通知、分页等
   ├── utils/admin_charts.py 控制台图表数据聚合
   └── templates/ + static/  页面与样式
           │
           ▼
      MySQL（campus_express）

启动流程：

1. startup_prepare() 连接 MySQL 服务
2. 库不存在 → 执行 sql/init.sql 初始化
3. 库已存在 → 补全默认账号，不覆盖已改密码
4. 校验默认测试账号可用后启动 Flask
5. Debug 模式下自动打开浏览器至 /login

---

三、目录结构

homework-xiaoyuan-kuaidi-daiqu/
├── app.py                      # Flask 应用入口
├── config.py                   # 数据库、密钥、端口等配置
├── init_db.py                  # 独立数据库维护脚本
├── requirements.txt            # Python 依赖
├── window_run.bat              # Windows 一键安装并运行
├── mac_run.sh                  # macOS 一键安装并运行
├── README.md                   # 学生向运行说明（Windows）
├── 项目说明.md                 # 本文档（完整项目介绍）
├── 需求.md                     # 原始功能需求
├── db说明.md                   # 数据库表结构说明
├── 代码要求.md                 # 课程提交规范
├── sql/
│   └── init.sql                # 建库、建表、初始数据
├── routes/
│   ├── auth_routes.py          # 统一登录（角色切换表单）
│   ├── user_routes.py          # 师生端路由
│   ├── courier_routes.py       # 代取员端路由
│   └── admin_routes.py         # 管理后台路由
├── utils/
│   ├── startup.py              # 启动时 MySQL 准备
│   ├── defaults.py             # 默认测试账号（唯一数据源）
│   ├── db.py                   # 数据库连接与 CRUD
│   ├── auth.py                 # login_required 装饰器
│   ├── helpers.py              # 业务常量、通知、分页
│   └── admin_charts.py         # 控制台 ECharts 数据
├── templates/
│   ├── base.html               # 公共布局（导航/侧边栏）
│   ├── auth.html               # 登录与注册
│   ├── home.html               # 用户/代取员首页
│   ├── account.html            # 个人中心、消息通知
│   ├── orders.html             # 订单相关各视图
│   ├── admin.html              # 管理后台各视图
│   └── partials/
│       ├── flash.html          # 操作提示
│       └── pagination.html     # 分页组件
└── static/
    ├── css/style.css           # 全站样式
    └── js/
        ├── echarts.min.js      # ECharts 5.5.1（本地，非 CDN）
        └── admin-dashboard.js  # 管理后台图表初始化

模板说明： 前端采用共享模板 + portal / view 参数区分角色与页面，便于维护；与 代码要求.md 中「每端独立 HTML」的表述略有出入，以当前源码为准。

---

四、运行方式

4.1 Windows（学生推荐）

window_run.bat

或手动：

python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
python app.py

4.2 macOS

首次需赋予执行权限：

chmod +x mac_run.sh
./mac_run.sh

也可：

bash mac_run.sh

Mac 脚本使用 python3.12 创建虚拟环境；Windows 使用 python。

手动运行：

python3.12 -m venv venv
source venv/bin/activate
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
python app.py

4.3 配置项

编辑 config.py：

配置项	默认值	说明
DB_HOST	127.0.0.1	MySQL 主机
DB_PORT	3306	MySQL 端口
DB_USER	root	数据库用户
DB_PASSWORD	12345678	数据库密码
DB_NAME	campus_express	业务库名

app.py 中 PORT = 8080（避免 macOS 5000 端口被 AirPlay 占用）。

4.4 访问地址

说明	URL
统一登录	http://127.0.0.1:8080/login
师生首页	http://127.0.0.1:8080/user/home
代取员首页	http://127.0.0.1:8080/courier/home
管理后台	http://127.0.0.1:8080/admin/dashboard
师生注册	http://127.0.0.1:8080/user/register

---

五、测试账号

默认账号定义在 utils/defaults.py，与 sql/init.sql 保持一致。密码均为 123456（师生用手机号 + 验证码登录）。

角色	账号	登录方式
管理员	admin	账号密码
代取员	courier	账号密码
师生	13800138001 / 13800138002	手机号 + 任意 6 位验证码

启动时 init_db.py / startup.py 会补全缺失的默认账号；密码占位符 pending 会自动修复，不会覆盖用户已修改的密码。

---

六、功能说明

6.1 师生用户端

功能	说明
注册 / 登录	手机号 + Mock 验证码（任意 6 位数字）
发布订单	快递公司、单号、驿站取件地址、送达地址、代取费用
虚拟支付	提交订单时从虚拟余额扣款
订单管理	全部订单列表，按状态筛选
取消订单	仅「待接单」可取消，费用退回余额
确认收货	代取员配送完成后用户手动确认
订单评价	已完成订单可提交文字评价
消息通知	订单状态变更等，支持分页（每页 10 条）
个人中心	手机号、余额、账号状态

6.2 代取员端

功能	说明
待接单列表	全平台待接单，按下单时间倒序（不算地理距离）
接单	数据库原子 UPDATE ... WHERE status=待接单，防抢单冲突
状态更新	已接单 → 取件中 → 配送中（代取员端操作）
我的订单	本人承接的全部订单
收益统计	已完成订单费用合计

6.3 管理后台

功能	说明
控制台	用户数、订单数、待接单数、已支付总额
图表分析	ECharts：订单状态分布（饼图）、代取员收益排行（柱状图）、近 7 日下单趋势（折线图）
用户管理	师生列表，禁用 / 启用
代取员管理	查看、创建、禁用 / 启用
订单管理	全平台查询与详情，不可创建订单
接单记录	代取员历史接单明细
费用汇总	按状态统计费用与代取员收益
公告管理	新增、编辑、删除

6.4 前端交互约定

• 导航选中态： 用户端、代取员端顶部导航与管理后台侧边栏，根据当前路由高亮，刷新后保持
• 表单 placeholder： 登录、注册、发单、评价、公告等输入控件均提供提示文字

---

七、订单业务流程

师生发单 + 虚拟支付
    ↓
  待接单  ←── 师生可取消（退款）
    ↓ 代取员接单
  已接单
    ↓ 代取员：开始取件
  取件中
    ↓ 代取员：开始配送
  配送中
    ↓ 师生确认收货
  已完成  →  师生评价

其他状态：

• 已取消 — 用户取消待接单订单
• 异常订单 — 管理员手动标记

---

八、数据库说明

详细表结构见 db说明.md，建表 SQL 见 sql/init.sql。

初始化策略

情况	行为
本地没有 campus_express 库	自动执行 init.sql 建库建表并导入测试数据
本地已有该库	不重复导入，补全缺失默认账号
密码为占位符 pending	自动修复为 123456
用户已修改密码	不覆盖

重建数据库

DROP DATABASE IF EXISTS campus_express;

然后重新运行 python app.py 或一键脚本。

也可单独执行：python init_db.py

主要数据表

表名	用途
users	师生、代取员、管理员账号
orders	快递代取订单
reviews	订单评价
announcements	系统公告
notifications	用户消息通知

---

九、管理后台图表（ECharts）

图表库 已下载至本地 static/js/echarts.min.js（v5.5.1），不依赖外网 CDN。

图表	类型	数据说明
订单状态分布	环形饼图	orders 表按 status 分组统计
代取员收益排行	柱状图	已完成且已支付订单，按代取员汇总 Top 8
近 7 日下单趋势	折线图	最近 7 天每日新建订单数

数据聚合逻辑：utils/admin_charts.py → get_dashboard_chart_data()
前端渲染：static/js/admin-dashboard.js → initAdminDashboardCharts()

---

十、业务约定（作业简化项）

项目	约定
代取费用	用户手动填写，系统不做自动计价
待接单排序	仅按下单时间，不计算地理距离
支付	虚拟支付（扣减余额），无微信/支付宝
短信验证码	Mock，任意 6 位数字即可
禁用账号	仅禁止新发单 / 新接单
管理员	不可代客创建订单
手机号/单号脱敏	不做
操作审计日志	不做

---

十一、依赖清单

Flask==3.0.3
PyMySQL==1.1.1
Werkzeug==3.0.3

前端：ECharts 5.5.1（static/js/echarts.min.js，本地静态文件）

---

十二、常见问题

MySQL 连接失败

确认 MySQL 服务已启动，config.py 中账号密码正确。程序会在启动前检测，失败则直接退出并提示。

Mac 执行 ./mac_run.sh 提示 permission denied

chmod +x mac_run.sh
./mac_run.sh

代取员 courier 登录不上

确认启动日志有「业务库已就绪」。旧库可能缺少 courier 账号，重启后 startup.py 会自动补全；仍不行则重建数据库（见第八节）。

端口被占用

默认 8080，可在 app.py 修改 PORT。

pip 安装慢

一键脚本已配置清华源。手动安装加：

-i https://pypi.tuna.tsinghua.edu.cn/simple

---

十三、配套文档索引

文档	定位
README.md	学生向：Windows 运行、测试账号、功能概览
项目说明.md	本文档：完整技术说明与双平台指南
需求.md	课程原始功能需求
db说明.md	数据库表结构与字段
代码要求.md	课程提交规范（技术栈、脚本、文档要求）

获取完整源码

• 网站：AI源码
• 本项目详情：https://www.aiyuanma.vip/posts/homework-xiaoyuan-kuaidi-daiqu