拓冰网站定制 
校园快递代取管理系统本文档为项目的完整技术说明涵盖系统架构、目录结构、双平台运行方式、功能细节、数据库策略及开发约定。面向需要全面了解或维护本项目的开发者与答辩评审。学生日常运行与测试优先阅读README.mdWindows 一键运行说明。一、项目概述本系统是一套校园快递代取管理平台解决在校师生不便自取快递、代取员接单配送、管理员统一运营三类场景。角色入口核心能力师生用户统一登录 → 师生用户发单、虚拟支付、查单、收货、评价代取员统一登录 → 代取员待接单、接单、更新配送状态、收益统计系统管理员统一登录 → 管理员用户/代取员管控、订单与费用分析、公告管理技术栈Python 3.12、Flask 3.0、MySQL 5.7/8.0、原生 HTML CSS JavaScript、PyMySQL、Werkzeug密码哈希、ECharts 5.5本地静态资源。设计原则作业简化虚拟支付不涉及真实资金代取费用由用户手填不做距离计价短信验证码 Mock任意 6 位数字即可管理员不可代客创建订单禁用账号仅限制新发单/新接单不强制终止进行中订单二、系统架构浏览器 │ ▼ app.pyFlask 入口 ├── 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/ 页面与样式 │ ▼ MySQLcampus_express启动流程startup_prepare()连接 MySQL 服务库不存在 → 执行sql/init.sql初始化库已存在 → 补全默认账号不覆盖已改密码校验默认测试账号可用后启动 FlaskDebug 模式下自动打开浏览器至/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.py4.2 macOS首次需赋予执行权限chmodx mac_run.sh ./mac_run.sh也可bashmac_run.shMac 脚本使用python3.12创建虚拟环境Windows 使用python。手动运行python3.12-mvenv venvsourcevenv/bin/activate pipinstall-rrequirements.txt-ihttps://pypi.tuna.tsinghua.edu.cn/simple python app.py4.3 配置项编辑config.py配置项默认值说明DB_HOST127.0.0.1MySQL 主机DB_PORT3306MySQL 端口DB_USERroot数据库用户DB_PASSWORD12345678数据库密码DB_NAMEcampus_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用户已修改密码不覆盖重建数据库DROPDATABASEIFEXISTScampus_express;然后重新运行python app.py或一键脚本。也可单独执行python init_db.py主要数据表表名用途users师生、代取员、管理员账号orders快递代取订单reviews订单评价announcements系统公告notifications用户消息通知九、管理后台图表ECharts图表库已下载至本地static/js/echarts.min.jsv5.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 位数字即可禁用账号仅禁止新发单 / 新接单管理员不可代客创建订单手机号/单号脱敏不做操作审计日志不做十一、依赖清单Flask3.0.3 PyMySQL1.1.1 Werkzeug3.0.3前端ECharts 5.5.1static/js/echarts.min.js本地静态文件十二、常见问题MySQL 连接失败确认 MySQL 服务已启动config.py中账号密码正确。程序会在启动前检测失败则直接退出并提示。Mac 执行./mac_run.sh提示 permission deniedchmodx mac_run.sh ./mac_run.sh代取员 courier 登录不上确认启动日志有「业务库已就绪」。旧库可能缺少courier账号重启后startup.py会自动补全仍不行则重建数据库见第八节。端口被占用默认 8080可在app.py修改PORT。pip 安装慢一键脚本已配置清华源。手动安装加-ihttps://pypi.tuna.tsinghua.edu.cn/simple十三、配套文档索引文档定位README.md学生向Windows 运行、测试账号、功能概览项目说明.md本文档完整技术说明与双平台指南需求.md课程原始功能需求db说明.md数据库表结构与字段代码要求.md课程提交规范技术栈、脚本、文档要求 校园快递代取管理系统
校园快递代取管理系统本文档为项目的完整技术说明涵盖系统架构、目录结构、双平台运行方式、功能细节、数据库策略及开发约定。面向需要全面了解或维护本项目的开发者与答辩评审。学生日常运行与测试优先阅读README.mdWindows 一键运行说明。一、项目概述本系统是一套校园快递代取管理平台解决在校师生不便自取快递、代取员接单配送、管理员统一运营三类场景。角色入口核心能力师生用户统一登录 → 师生用户发单、虚拟支付、查单、收货、评价代取员统一登录 → 代取员待接单、接单、更新配送状态、收益统计系统管理员统一登录 → 管理员用户/代取员管控、订单与费用分析、公告管理技术栈Python 3.12、Flask 3.0、MySQL 5.7/8.0、原生 HTML CSS JavaScript、PyMySQL、Werkzeug密码哈希、ECharts 5.5本地静态资源。设计原则作业简化虚拟支付不涉及真实资金代取费用由用户手填不做距离计价短信验证码 Mock任意 6 位数字即可管理员不可代客创建订单禁用账号仅限制新发单/新接单不强制终止进行中订单二、系统架构浏览器 │ ▼ app.pyFlask 入口 ├── 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/ 页面与样式 │ ▼ MySQLcampus_express启动流程startup_prepare()连接 MySQL 服务库不存在 → 执行sql/init.sql初始化库已存在 → 补全默认账号不覆盖已改密码校验默认测试账号可用后启动 FlaskDebug 模式下自动打开浏览器至/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.py4.2 macOS首次需赋予执行权限chmodx mac_run.sh ./mac_run.sh也可bashmac_run.shMac 脚本使用python3.12创建虚拟环境Windows 使用python。手动运行python3.12-mvenv venvsourcevenv/bin/activate pipinstall-rrequirements.txt-ihttps://pypi.tuna.tsinghua.edu.cn/simple python app.py4.3 配置项编辑config.py配置项默认值说明DB_HOST127.0.0.1MySQL 主机DB_PORT3306MySQL 端口DB_USERroot数据库用户DB_PASSWORD12345678数据库密码DB_NAMEcampus_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用户已修改密码不覆盖重建数据库DROPDATABASEIFEXISTScampus_express;然后重新运行python app.py或一键脚本。也可单独执行python init_db.py主要数据表表名用途users师生、代取员、管理员账号orders快递代取订单reviews订单评价announcements系统公告notifications用户消息通知九、管理后台图表ECharts图表库已下载至本地static/js/echarts.min.jsv5.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 位数字即可禁用账号仅禁止新发单 / 新接单管理员不可代客创建订单手机号/单号脱敏不做操作审计日志不做十一、依赖清单Flask3.0.3 PyMySQL1.1.1 Werkzeug3.0.3前端ECharts 5.5.1static/js/echarts.min.js本地静态文件十二、常见问题MySQL 连接失败确认 MySQL 服务已启动config.py中账号密码正确。程序会在启动前检测失败则直接退出并提示。Mac 执行./mac_run.sh提示 permission deniedchmodx mac_run.sh ./mac_run.sh代取员 courier 登录不上确认启动日志有「业务库已就绪」。旧库可能缺少courier账号重启后startup.py会自动补全仍不行则重建数据库见第八节。端口被占用默认 8080可在app.py修改PORT。pip 安装慢一键脚本已配置清华源。手动安装加-ihttps://pypi.tuna.tsinghua.edu.cn/simple十三、配套文档索引文档定位README.md学生向Windows 运行、测试账号、功能概览项目说明.md本文档完整技术说明与双平台指南需求.md课程原始功能需求db说明.md数据库表结构与字段代码要求.md课程提交规范技术栈、脚本、文档要求