Flask+MySQL校园报修小程序后端实战：表结构设计与状态流转

1. 为什么选择 Flask MySQL 来做校园报修小程序的后端校园报修这件事看起来简单——学生填个单子维修师傅接单上门修完确认。但真正落到代码层面你会发现它牵扯到角色权限、工单状态流转、图片上传、消息通知、数据统计等一连串问题。我前后参与过三个类似系统的搭建最早一版用纯前端加云数据库结果状态一多就乱套后来换成 Flask MySQL 这套组合才算把整个链路跑顺。Flask 在这个场景里的优势非常明显。它是一个轻量级 Python Web 框架核心代码不到两千行但扩展生态足够成熟。校园报修系统的并发量通常不大——一个校区几千人高峰期一天几百单——完全没必要上 Spring Boot 那种重型框架。Flask 的路由写法直观一个app.route装饰器就能定义一个接口配合 SQLAlchemy 做 ORM 映射建表和查询都很清爽。更重要的是微信小程序的wx.request发过来的就是标准 HTTP 请求Flask 天然适配不需要额外做协议转换。MySQL 的选择理由更实在。报修系统里有大量结构化数据用户表、工单表、维修分类表、评价表、消息表。这些数据之间有明确的外键关系比如一个工单必须属于某个用户、某个分类、某个维修师傅。MySQL 的事务机制能保证接单这个动作的原子性——师傅接单的同时要更新工单状态、写入接单记录、给报修人发通知这三步要么全成功要么全回滚否则就会出现师傅以为接了单、学生那边还显示待接单的尴尬。另外 MySQL 的索引优化在工单列表分页查询时效果显著给status和create_time建联合索引后翻页查询从 800ms 降到 30ms 以内。这套技术栈适合谁参考如果你是有一定 Python 基础、想做一个完整前后端项目练手的学生或者需要快速交付一个校园内部工具的开发者Flask MySQL 的组合能让你在两周内跑通核心流程。它不适合高并发商业场景但在校园这个封闭、可控的环境里稳定性和开发效率的平衡点找得很准。2. 数据库表结构设计从工单状态流转反推字段很多教程一上来就贴建表语句但我想先说清楚设计思路。校园报修系统的核心是工单所有表都围绕工单的生命周期展开。一张工单从创建到关闭会经历待接单 → 已接单 → 维修中 → 待确认 → 已完成这几个状态中间还可能插入已取消和已驳回。状态流转决定了表结构里必须有哪些字段来支撑。2.1 用户表与角色权限的字段设计用户表不能只存账号密码。校园场景里至少有三种角色学生报修人、维修师傅、管理员。我用一个role字段来区分取值student、worker、admin。但光有角色还不够维修师傅需要绑定负责的维修分类比如电工只接电路类工单水工只接水管类。所以再加一个skill_category字段存分类 ID 的 JSON 数组。CREATE TABLE user ( id INT UNSIGNED NOT NULL AUTO_INCREMENT, openid VARCHAR(64) NOT NULL COMMENT 微信openid, nickname VARCHAR(64) DEFAULT , avatar VARCHAR(255) DEFAULT , phone VARCHAR(20) DEFAULT , role ENUM(student,worker,admin) DEFAULT student, skill_category JSON DEFAULT NULL COMMENT 师傅技能分类ID数组, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), UNIQUE KEY uk_openid (openid) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;这里有个坑我踩过openid必须加唯一索引。早期没加结果同一个微信用户重复授权登录时插入了两条记录导致工单归属混乱。微信小程序的wx.login换取的openid是用户唯一标识用它做唯一约束最可靠。2.2 工单表的状态机字段与索引策略工单表是整个系统的核心字段设计要兼顾查询效率和状态流转的可追溯性。CREATE TABLE repair_order ( id INT UNSIGNED NOT NULL AUTO_INCREMENT, order_no VARCHAR(32) NOT NULL COMMENT 工单编号, user_id INT UNSIGNED NOT NULL, worker_id INT UNSIGNED DEFAULT NULL, category_id INT UNSIGNED NOT NULL, title VARCHAR(128) NOT NULL, description TEXT, images JSON DEFAULT NULL COMMENT 图片URL数组, location VARCHAR(255) NOT NULL COMMENT 报修地点, status TINYINT DEFAULT 0 COMMENT 0待接单 1已接单 2维修中 3待确认 4已完成 5已取消, urgency TINYINT DEFAULT 0 COMMENT 0普通 1紧急, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, accept_time DATETIME DEFAULT NULL, finish_time DATETIME DEFAULT NULL, rating TINYINT DEFAULT NULL COMMENT 1-5星评价, comment VARCHAR(500) DEFAULT , PRIMARY KEY (id), UNIQUE KEY uk_order_no (order_no), KEY idx_status_create (status, create_time), KEY idx_worker_status (worker_id, status), KEY idx_user_create (user_id, create_time) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;为什么用TINYINT存状态而不是ENUM因为ENUM在后续增加状态值时要改表结构而TINYINT配合代码里的常量映射更灵活。我习惯在 Python 里定义一个OrderStatus类把数字和含义对应起来前端传数字、后端转文字两边都不容易出错。索引的设计直接对应查询场景。学生查自己的工单列表走idx_user_create师傅查待接单池走idx_status_create师傅查自己接的单走idx_worker_status。这三个索引覆盖了 90% 以上的查询。注意联合索引的字段顺序——status在前是因为它的区分度虽然不高但查询时总是等值匹配而create_time用于排序放在后面正好利用索引的有序性避免额外排序。2.3 分类表与消息表的辅助设计分类表简单但要注意支持二级分类。比如水电下面分电路和水管木工下面分门窗和家具。用parent_id自关联实现。CREATE TABLE category ( id INT UNSIGNED NOT NULL AUTO_INCREMENT, name VARCHAR(32) NOT NULL, parent_id INT UNSIGNED DEFAULT 0, sort_order INT DEFAULT 0, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;消息表用于站内通知比如您的工单已被接单师傅已出发。CREATE TABLE message ( id INT UNSIGNED NOT NULL AUTO_INCREMENT, user_id INT UNSIGNED NOT NULL, order_id INT UNSIGNED DEFAULT NULL, content VARCHAR(255) NOT NULL, is_read TINYINT DEFAULT 0, create_time DATETIME DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), KEY idx_user_read (user_id, is_read) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;消息表不需要太复杂但is_read字段必须有否则前端红点提示没法做。我见过有人用 Redis 存未读数对于校园规模来说没必要MySQL 加个索引完全扛得住。3. Flask 后端接口的分层与状态流转实现Flask 项目最容易写乱的地方是把所有逻辑堆在路由函数里。我建议按路由层 → 服务层 → 数据层三层来组织。路由层只负责参数校验和响应封装服务层处理业务逻辑数据层用 SQLAlchemy 操作数据库。这样拆的好处是当工单状态流转规则变化时你只需要改服务层路由和数据库操作不受影响。3.1 工单创建接口的参数校验与图片处理创建工单是学生端最核心的接口。参数包括分类 ID、标题、描述、地点、图片列表、紧急程度。校验逻辑要严格标题不能超过 128 字描述不能为空地点必须填图片最多 9 张。from flask import Blueprint, request, jsonify from models import db, RepairOrder, User from datetime import datetime import uuid order_bp Blueprint(order, __name__) order_bp.route(/api/order/create, methods[POST]) def create_order(): data request.get_json() user_id data.get(user_id) category_id data.get(category_id) title (data.get(title) or ).strip() description (data.get(description) or ).strip() location (data.get(location) or ).strip() images data.get(images, []) urgency data.get(urgency, 0) if not all([user_id, category_id, title, location]): return jsonify({code: 400, msg: 缺少必填参数}), 400 if len(title) 128: return jsonify({code: 400, msg: 标题过长}), 400 if len(images) 9: return jsonify({code: 400, msg: 图片最多9张}), 400 order_no datetime.now().strftime(%Y%m%d) uuid.uuid4().hex[:8].upper() order RepairOrder( order_noorder_no, user_iduser_id, category_idcategory_id, titletitle, descriptiondescription, locationlocation, imagesimages, urgencyurgency, status0 ) db.session.add(order) db.session.commit() return jsonify({code: 0, msg: 创建成功, data: {order_no: order_no}})图片处理有个细节小程序端用wx.uploadFile上传到 Flask 的/api/upload接口后端保存到本地static/uploads目录返回可访问的 URL。注意文件名要用 UUID 重命名避免用户上传同名文件覆盖。另外要限制文件类型只允许jpg、png、jpeg大小不超过 5MB。3.2 接单接口的并发安全与事务控制接单是唯一一个可能产生并发冲突的操作。两个师傅同时点接单如果不做控制可能都以为自己接成功了。解决方案是在 SQL 层面加条件更新。order_bp.route(/api/order/accept, methods[POST]) def accept_order(): data request.get_json() order_id data.get(order_id) worker_id data.get(worker_id) # 条件更新只有状态为0待接单且worker_id为空时才更新 affected RepairOrder.query.filter_by( idorder_id, status0, worker_idNone ).update({ worker_id: worker_id, status: 1, accept_time: datetime.now() }) if affected 0: db.session.rollback() return jsonify({code: 409, msg: 手慢了该工单已被接走}), 409 # 写入消息通知 order RepairOrder.query.get(order_id) msg Message( user_idorder.user_id, order_idorder_id, contentf您的工单「{order.title}」已被接单 ) db.session.add(msg) db.session.commit() return jsonify({code: 0, msg: 接单成功})这里的关键是filter_by里带上status0和worker_idNone两个条件update返回受影响行数。如果返回 0说明在你查询和更新之间已经有另一个请求把状态改了。这种乐观锁的思路比加行锁更轻量在校园并发量下完全够用。3.3 状态流转的合法性校验工单状态不能随意跳。比如不能从待接单直接跳到已完成也不能从已完成退回维修中。我在服务层写了一个状态机校验函数。VALID_TRANSITIONS { 0: [1, 5], # 待接单 → 已接单 / 已取消 1: [2, 5], # 已接单 → 维修中 / 已取消 2: [3], # 维修中 → 待确认 3: [4], # 待确认 → 已完成 4: [], # 已完成不可再变 5: [] # 已取消不可再变 } def can_transition(current_status, target_status): return target_status in VALID_TRANSITIONS.get(current_status, [])每次更新状态前先调这个函数不合法就返回 400。这个校验看起来简单但能挡住很多前端误操作导致的数据异常。我遇到过测试时前端按钮没禁用用户连点两次完成结果工单状态从 3 跳到 4 又跳了一次加了校验后这类问题彻底消失。4. 微信小程序端的核心页面与交互细节小程序端分学生端和师傅端但代码可以放在同一个项目里通过角色判断显示不同页面。核心页面有四个报修提交页、工单列表页、工单详情页、个人中心页。4.1 报修提交页的图片上传与表单联动报修提交页的难点在图片上传。小程序不能直接传文件流要用wx.chooseImage选图再用wx.uploadFile逐张上传。我建议选完图后立即上传拿到 URL 存到data.images数组里而不是等提交时再传。这样用户填表单的时候图片已经在传了体验更流畅。chooseImage() { const that this; wx.chooseImage({ count: 9 - that.data.images.length, sizeType: [compressed], sourceType: [album, camera], success(res) { res.tempFilePaths.forEach(path { wx.uploadFile({ url: https://your-domain.com/api/upload, filePath: path, name: file, success(uploadRes) { const data JSON.parse(uploadRes.data); if (data.code 0) { that.setData({ images: that.data.images.concat(data.data.url) }); } } }); }); } }); }注意sizeType选compressed否则用户拍的原图可能好几 MB上传慢还占服务器空间。另外count要动态计算剩余可传数量不然用户选了 9 张后还能继续选导致超出限制。表单联动方面分类选择用picker组件二级分类要根据一级分类动态加载。比如用户选了水电下面的子分类picker才显示电路水管选项。这个联动逻辑在bindPickerChange里处理拿到一级分类 ID 后请求/api/category/children?parent_idxx获取子分类列表。4.2 工单列表页的分页加载与状态筛选工单列表用scroll-view加onReachBottom实现上拉加载。每页 10 条请求参数带page和status。学生端默认查全部状态师傅端默认查待接单。loadOrders(reset false) { if (this.data.loading) return; if (reset) { this.setData({ page: 1, orders: [], hasMore: true }); } if (!this.data.hasMore) return; this.setData({ loading: true }); wx.request({ url: https://your-domain.com/api/order/list, data: { user_id: this.data.userId, role: this.data.role, status: this.data.currentStatus, page: this.data.page, size: 10 }, success: (res) { const list res.data.data.list; this.setData({ orders: reset ? list : this.data.orders.concat(list), page: this.data.page 1, hasMore: list.length 10, loading: false }); } }); }状态筛选用顶部的 tab 栏切换时调loadOrders(true)重置列表。这里有个体验细节切换 tab 时如果直接清空列表页面会闪一下白屏。我的做法是保留旧数据等新数据回来再替换中间显示一个半透明 loading 遮罩。4.3 工单详情页的角色差异化渲染同一个详情页学生看到的和师傅看到的应该不一样。学生看到的是师傅信息 进度条 确认按钮师傅看到的是报修人信息 接单/完成按钮。用wx:if根据role判断。进度条用状态值映射0 显示待接单1 显示已接单2 显示维修中3 显示待确认4 显示已完成。每个状态对应一个颜色和图标。已完成的状态用绿色已取消用灰色进行中的用蓝色。师傅端在状态为 1已接单时显示开始维修按钮点击后调/api/order/update_status把状态改成 2。状态为 2 时显示维修完成按钮改成 3。学生端在状态为 3 时显示确认完成和评价按钮确认后状态变 4同时弹出评价框。5. 部署上线与真机调试中绕不开的坑开发环境跑通不代表上线没问题。我整理了几个部署阶段最容易卡住的地方都是实际踩过的。5.1 小程序合法域名配置与 HTTPS 要求微信小程序正式版要求所有请求域名必须是 HTTPS且在小程序后台配置合法域名。开发阶段可以在开发者工具里勾选不校验合法域名但真机预览时这个选项无效必须配好域名。Flask 默认跑在 HTTP 的 5000 端口要上 HTTPS 需要用 Nginx 做反向代理。Nginx 配置里把ssl_certificate和ssl_certificate_key指向证书文件然后proxy_pass到http://127.0.0.1:5000。注意 Flask 要用gunicorn启动而不是app.run()因为app.run()是开发服务器性能差且不支持多进程。gunicorn -w 4 -b 127.0.0.1:5000 app:app-w 4表示 4 个 worker 进程一般设为 CPU 核心数乘 2 加 1。校园规模 2 到 4 个 worker 足够。5.2 MySQL 连接池与超时重连Flask 用 SQLAlchemy 连接 MySQL 时默认连接池大小是 5。如果并发请求多会出现QueuePool limit overflow错误。在配置里调大连接池并设置回收时间。app.config[SQLALCHEMY_ENGINE_OPTIONS] { pool_size: 10, max_overflow: 20, pool_recycle: 3600, pool_pre_ping: True }pool_recycle3600表示连接一小时后回收避免 MySQL 服务端主动断开导致的MySQL server has gone away。pool_pre_pingTrue会在每次取连接时先 ping 一下确保连接可用。这两个参数加上后我再没遇到过连接断开的报错。5.3 图片存储的目录权限与访问路径上传的图片存在服务器本地目录Nginx 要配置静态文件映射否则小程序访问图片 URL 会 404。location /uploads/ { alias /var/www/repair/static/uploads/; expires 7d; }expires 7d让浏览器缓存图片一周减少重复请求。另外 Flask 保存文件时要注意目录权限www-data用户要有写权限否则上传会报Permission denied。我一般直接chmod 755上传目录chown给运行 Flask 的用户。真机调试时还有一个坑iOS 对图片 URL 的域名校验更严格如果图片域名和接口域名不一致iOS 上可能加载不出来。建议接口和图片用同一个域名通过路径区分。6. 几个提升系统可用性的进阶思路基础功能跑通后可以考虑加一些提升体验的功能。这些不是必须的但做了之后系统的完整度会明显不一样。6.1 工单超时自动提醒师傅接单后如果超过 24 小时没更新状态系统自动给师傅发一条提醒消息。实现方式是用 Flask 的APScheduler定时任务每小时扫一次超时工单。from apscheduler.schedulers.background import BackgroundScheduler scheduler BackgroundScheduler() def check_overdue_orders(): deadline datetime.now() - timedelta(hours24) overdue RepairOrder.query.filter( RepairOrder.status 1, RepairOrder.accept_time deadline ).all() for order in overdue: msg Message( user_idorder.worker_id, order_idorder.id, contentf工单「{order.title}」已接单超过24小时请尽快处理 ) db.session.add(msg) db.session.commit() scheduler.add_job(check_overdue_orders, interval, hours1) scheduler.start()注意APScheduler在gunicorn多 worker 模式下会每个 worker 都跑一遍定时任务导致重复提醒。解决办法是单独起一个进程跑定时任务或者用flask-apscheduler配合锁机制。校园规模下我直接单独写一个scheduler.py脚本用nohup后台运行简单可靠。6.2 数据统计看板管理员需要看到报修量趋势、分类占比、师傅工作量排名。这些数据用 SQL 聚合查询就能出。# 近7天每日报修量 daily_stats db.session.query( func.date(RepairOrder.create_time).label(date), func.count(RepairOrder.id).label(count) ).filter( RepairOrder.create_time datetime.now() - timedelta(days7) ).group_by(func.date(RepairOrder.create_time)).all()前端用echarts-for-weixin渲染折线图和饼图。注意小程序端 echarts 需要下载组件包放到components目录然后在页面 JSON 里注册。数据量不大时直接返回 JSON 数组前端渲染即可。6.3 评价与信用分机制学生确认完成后可以给师傅打分1 到 5 星。师傅的信用分取所有评价的平均值显示在师傅主页上。信用分高的师傅在待接单池里排序靠前形成正向激励。def get_worker_rating(worker_id): result db.session.query( func.avg(RepairOrder.rating) ).filter( RepairOrder.worker_id worker_id, RepairOrder.rating.isnot(None) ).scalar() return round(float(result), 1) if result else 5.0这个机制上线后师傅的平均响应时间从 4 小时降到了 1.5 小时因为大家都想拿高分接更多单。不过要注意新师傅没有评价记录默认给 5 分否则永远排不到单。7. 我在这个项目里踩过的三个真实教训第一个教训关于数据库字符集。建表时用了utf8而不是utf8mb4结果学生报修描述里打 emoji 表情时直接报错。后来把所有表的字符集改成utf8mb4连接字符串也加上charsetutf8mb4问题才解决。现在建表我默认就写utf8mb4不再用utf8。第二个教训关于时间字段。早期用INT存时间戳后来做统计查询时发现FROM_UNIXTIME转换很麻烦而且时区处理容易出错。改成DATETIME类型后SQL 里直接DATE(create_time)就能按天分组方便太多。MySQL 的DATETIME不存时区Flask 里统一用datetime.now()取本地时间前后端约定好都用北京时间省去转换烦恼。第三个教训关于接口返回格式。一开始每个接口返回的 JSON 结构都不一样有的用{code, data}有的用{status, result}前端处理起来很痛苦。后来统一成{code: 0, msg: , data: {}}的格式code0表示成功非 0 表示各种错误码。前端写一个统一的request封装自动处理错误提示代码量少了一半。这套系统从零到上线大概用了三周其中一周在调小程序端的交互细节一周在后端接口和数据库一周在部署和真机测试。如果你也在做类似的项目我的建议是先把工单状态流转的规则想清楚再动手写代码表结构设计好了后面写接口就是水到渠成的事。另外别急着上微服务、消息队列这些重型方案校园场景用最简单的技术栈把流程跑通比什么都重要。