大学城和园区这类场景里报修永远是个刚需。宿舍水龙头漏水、办公室空调不制冷、楼道灯坏了一周没人管——过去靠微信群接龙、电话轮流打信息一多就容易漏维修师傅忙的忙死闲的闲死。我在桃李园这类一线场景里落地过一套在线报修维修接单平台后端用Python Flask前端用uniapp打包成微信小程序管理端再配可视化统计大屏。整套做完报修响应时间从平均一天多降到了2小时以内工单全程可追溯管理员打开大屏就能看到本周哪类故障最多、哪个维修工最忙。这个技术组合目前很主流也特别适合做实战项目或毕设参考。Flask负责把API和业务逻辑轻松跑起来uniapp让一套代码同时输出微信小程序、H5和App可视化模块把数据库里那些死数据变成管理决策的依据。这篇文章不聊空理论直接按我实际开发这条路把业务拆解、表设计、接口实现、小程序联调、可视化落地、部署上线和排错经验完整走一遍你可以照着复现。1. 报修业务拆解与技术选型为什么是Flaskuniapp1.1 三种角色和一个工单闭环这类平台最核心的不是技术而是业务流程。很多人一上来就建表结果漏了状态流转和日志后面工单走到一半查不到历史。动代码之前先把角色和流程理清楚。系统按角色分三类人普通用户报修人在小程序里提交报修单描述故障、上传现场照片、填位置之后随时看进度维修工接单人在接单大厅抢单或等管理员派单接单后上门处理完成后提交维修结果和耗材管理员在后台管理异常单、分配工单、查看可视化报表和数据大屏。业务闭环是用户报修 → 待接单 → 维修工接单/管理员派单 → 维修中 → 用户确认完成 → 评价。每个状态节点都对应一条状态变更记录这既是工单追溯的依据也是统计分析的原始数据。我建议在纸上把流程图画一遍再动手建表能省很多返工。状态这块我吃过亏当时少设计了order_log表结果用户投诉维修师傅到底什么时候接的单我查遍数据库都查不到时间线。后来加了日志表每次状态变更写一条记录这类问题彻底解决。1.2 技术栈选型的真实考量为什么是Flask而不是Django、Spring Boot一个字快。报修平台本质是轻后台、多端前台的CRUD业务Flask路由干净、扩展成熟配合Flask-SQLAlchemy和Flask-CORS一天能搭完API骨架。Django的Admin和ORM很强但框架约束多、上手要学的概念也多对这个项目来说偏重。为什么是uniapp而不是原生小程序因为报修平台大概率会扩展。测试版用H5验证流程正式版发布微信小程序后面还可能出安卓App给物业人员用。uniapp基于Vue语法一套代码多端编译我实测从微信小程序切到H5页面基本不用改差异主要在处理生命周期、路由跳转和部分组件兼容上。微信小程序作为触达端是最优解用户不用下载App群聊里发个码就能打开登录用微信授权体验也无摩擦。所以这套技术栈不是最流行而是最合适后文所有设计都建立在这个选型之上。2. Flask后端开发数据库表、API与工单状态机2.1 数据库表设计6张核心表避免返工报修系统的对象很简单人、工单、日志、评价、公告。我的建议是至少6张表字段不要贪多够用就好。user表存用户和维修工的基础信息核心字段是openid微信唯一标识、nickname、avatar、phone、roleuser/worker/admin、status。worker_profile表单独存维修工的扩展信息比如技能标签水电/空调/网络、可接单范围、服务评分。repair_order表是业务主表字段包括order_no、user_id、worker_id、title、category、description、image_urls、location、contacts_name、contacts_phone、status、priority以及各种时间字段。order_log表记录状态流转历史字段是order_id、operator_id、action、from_status、to_status、remark、created_at。review表存评价字段是order_id、user_id、rating、content。notice表存公告字段是title、content、created_at。这里有两个容易踩的坑。第一个image_urls不要用逗号分隔的字符串我见过太多人这么干后续做展示和统计都要split。直接用JSON数组文本SQLAlchemy映射过来用json.loads解析或者干脆用JSON类型少写很多代码。第二个order_no要自己生成我用的格式是BX日期三位流水号例如BX20250101001好处是人眼能读还能避免自增ID暴露业务量。2.2 RESTful API设计把报修流程变成端点后端给小程序端提供接口我习惯按资源拆严格走RESTful风格。认证接口是POST /api/auth/login微信code换token和PUT /api/auth/profile更新资料报修单接口包括POST /api/orders提交报修、GET /api/orders?roleuser我的报修、GET /api/orders/pool接单大厅、GET /api/orders/ 详情、PUT /api/orders/ /accept接单、PUT /api/orders/ /confirm用户确认完成、PUT /api/orders/ /cancel取消评价接口是POST /api/orders/ /review公告接口是GET /api/notices统计接口我单独放在stats蓝图里。认证用JWT流程是小程序端uni.login拿到临时code传给后端login接口后端拿着code向微信接口换openid然后签发JWT返回前端。后续每个请求前端在header里带上Authorization: Bearer Flask侧用jwt_required装饰器保护需要登录的接口。这里有个细节开发阶段微信登录需要AppID和AppSecret的配合可以先做一个mock登录接口方便前端联调等真机测试再切换成真实微信登录否则前后端联调会被微信后台拖死。2.3 工单状态机防止状态乱飞的关键工单状态是整个项目最容易被改乱的地方。我定义的状态流转是PENDING待接单→ ACCEPTED已接单→ REPAIRING维修中→ COMPLETED已完成PENDING或ACCEPTED状态下用户可以取消进CANCELLEDCOMPLETED后可以评价评价不影响状态单独存到review表。实现上我建议把所有状态变更写成一个Service方法比如order_service.change_status(order, new_status, operator, remark)在这个方法里校验当前状态能否变到目标状态能就更新状态、写order_log、返回success不能就抛异常。千万不要在每个视图函数里直接改order.status字段一旦有遗漏工单状态就全乱了。还要加一层防护维修工接单时用乐观锁通过SQLAlchemy的update构造执行UPDATE ... WHERE status PENDING判断rowcount是否为1是才算抢单成功。这比先查再更新靠谱两个维修工同时抢单时不会重复接单。3. uniapp小程序端开发从登录到报修表单的完整链路3.1 页面结构与uniapp生命周期适配用HBuilderX创建uniapp项目pages目录下我规划了五个页面pages/index/index是首页展示公告、报修入口和进度卡片pages/repair/create是报修填单页包含分类选择、图片上传、定位pages/order/list是工单列表/接单大厅用tab切换我的报修和全部工单pages/order/detail是工单详情与操作按钮pages/mine/mine是个人中心。这里有一条很重要的经验uniapp的onLoad和onShow生命周期在多端有细微差别。拿工单列表这个页面来说我用onShow而不是onLoad去拉取列表数据。因为在微信小程序里从详情页返回列表页时onLoad不会重新触发但onShow会。如果你写在onLoad里用户报修完返回列表数据还是旧的体验很拉胯。另外小程序顶部导航栏高度不同机型不一样用uniapp的uni.getSystemInfoSync()拿statusBarHeight再结合胶囊按钮位置动态设置自定义导航的高度这个适配每次都有同学踩坑。3.2 登录、请求封装与多域名配置uniapp自带的uni.request功能够用但到处直接写会非常痛苦。我封装了一个request.js统一处理baseURL、token注入、状态码拦截和错误提示。开发时在微信开发者工具里可以填http://localhost:5000但真机和打包后必须填线上HTTPS域名所以我习惯把环境拆成dev和prod两份发布小程序时只改一处。有朋友问过uniapp封装H5如何指向2个域名本质就是环境配置问题。小程序端多环境的做法是在manifest.json的h5节点下配置devServer代理或者用Vite的mode区分环境变量文件。我在项目里单独维护了一个apiConfig.js按环境导出baseURL发布前切换打包配置即可。登录流程做成这样首次启动uni.getStorage(token)有就直接放行没有就调用uni.login拿code请求后端登录接口换token存到storage。后端用code换openid需要AppSecret这个密钥绝对不能放前端。我见过有人为了省事把AppSecret写在前端配置里上线后被直接扒走微信登录形同虚设。3.3 报修表单、图片上传与进度轮询报修表单是小程序的重头戏。字段包括标题、故障分类picker选择器、详细描述textarea、联系人电话、地址、图片uni.chooseImage选择最多三张。图片上传我推荐的做法是选择图片后立即调用uni.uploadFile传到后端后端返回图片URL表单里存URL数组提交时把数组一起传。千万别等表单一起提交时再处理文件那样请求会复杂很多。后端接收图片用Flask的request.files我的处理流程是校验扩展名jpg、png、限制大小单张不超过5MB、用UUID重新命名、保存到项目下的uploads目录、生成可访问的静态URL。开发阶段Flask的静态目录直接映射uploads即可。进度查询就是列表页不断刷新工单状态前端用setInterval轮询详情页的接口每10秒查一次状态从REPAIRING变成COMPLETED就提示用户确认完成。轮询虽然简单但在这个场景完全够用等订单量大了再换WebSocket现在不必提前设计。4. 可视化大屏Flask聚合接口ECharts图表落地4.1 可视化指标拆解管理端真正需要看什么可视化不是把数据堆出来好看而是给管理者提供决策信息。我在桃李园这套平台里做的图表不多但每张都对应一个管理问题核心指标卡展示今日报修单数、待接单数、平均响应时长、本月完成率管理员打开就要看到趋势折线图统计近30天每天的报修量用来发现故障高峰规律分类环形图统计水、电、空调、网络各占比帮管理者定维修工的技能培训方向维修工接单柱状图展示谁接单多、谁完成快、谁评分高绩效一目了然再加一个服务评价分布条形图服务质量好不好一眼看出来。实测下来我的体会是图表宁精勿滥。最开始我做了七八张图结果管理者只盯着前三个看。后来就把次要图表砍掉把关键信息做大做直观。可视化是为了让人一眼看懂不是为了炫技这个原则贯穿整个设计。4.2 Flask统计接口趋势、分类与排行榜可视化前端需要数据Flask侧做了几个聚合接口。拿近30天报修趋势举例实现思路是先循环生成最近30天的日期列表再用SQLAlchemy按日期分组统计把缺失的日期补0返回。如果不补0折线图会出现断点观感很差。核心代码是这样的from datetime import datetime, timedelta from flask import jsonify, request from sqlalchemy import func from models import RepairOrder app.route(/api/stats/trend, methods[GET]) def stats_trend(): days request.args.get(days, 30, typeint) today datetime.now().date() start today - timedelta(daysdays - 1) rows db.session.query( func.date(RepairOrder.created_at).label(d), func.count(RepairOrder.id).label(cnt) ).filter(RepairOrder.created_at start).group_by(d).all() count_map {str(row.d): row.cnt for row in rows} date_list [(start timedelta(daysi)).strftime(%Y-%m-%d) for i in range(days)] data [{date: d, count: count_map.get(d, 0)} for d in date_list] return jsonify({code: 0, data: data})分类占比接口就是按category字段分组统计维修工排行按worker_id分组统计再关联user表取昵称和头像。这些接口都放在stats蓝图里前端直接调用。聚合统计是Python的强项基本就是几个group by的问题比Java写起来省一半代码。4.3 ECharts在H5管理端的实现细节uniapp里用ECharts有几个选择我推荐把图表放在管理端H5而不是小程序里。管理端用npm安装ECharts组件里import * as echarts from echarts在div上初始化chart实例数据更新时调用chart.setOption传入新配置即可。小程序端不是标准DOM塞ECharts要么用renderjs要么用ucharts反而增大包体积和出错概率不如让用户看列表和简版统计文字。Flask端如果要渲染管理端大屏页面我直接用Jinja2模板返回一个HTML页面页面里通过fetch请求上面的stats接口渲染图表。前后端分离很时髦但这种内部管理后台用服务端渲染反而更快也不用单独部署一套前端工程。需要注意图表的自适应问题管理端大屏往往在PC和平板上切换ECharts实例默认不跟随容器尺寸变化。我在组件里加了window.onresize监听调用chart.resize()重新计算尺寸否则切个窗口图表就变形了。5. 上线部署本地联调、小程序发布与Nginx配置5.1 本地联调CORS、局域网IP与静态图片本地联调有三个必踩点踩过一遍后面就顺了。第一是跨域。小程序在开发者工具里默认勾选不校验合法域名开发时可以打开但H5端调试时浏览器跨域是跑不掉的。后端直接加上Flask-CORS允许所有来源即可上线前再收紧。代码就两行from flask_cors import CORS CORS(app)第二是本机IP访问。小程序开发者工具连本机后端时localhost常常不通安卓真机尤其明显。要把API地址改成电脑的局域网IP比如http://192.168.1.100:5000同时确认系统防火墙放行了5000端口。这个坑很隐蔽报错信息往往只写网络异常我第一次排查花了半小时。第三是静态图片路径。图片上传后保存到uploads目录Flask要显式映射静态目录让图片URL带上/uploads/前缀。我早期忘加静态映射小程序端图片全部404排查了半天才发现是静态目录没生效。5.2 微信小程序上线域名、HTTPS与类目上线这个环节流程比代码复杂。微信小程序的硬性要求必须提前准备注册小程序账号拿到AppID配置AppSecret到后端环境变量服务器绑定完成备案的域名小程序后台配置request合法域名必须是HTTPSNginx配置SSL证书反向代理到Flask应用端口。uniapp打包流程是HBuilderX里选择发行-小程序-微信生成微信小程序代码目录用微信开发者工具打开、上传、提交审核。审核通过后发布版本。这里特别提醒一件事小程序后台的服务器域名配置分成request合法域名和uploadFile合法域名uploadFile域名要单独加。如果图片上传走的是/uploads接口漏加uploadFile域名小程序里图片就传不上去报错信息还特别隐晦。图片加载的downloadFile合法域名也要核对一次上线要确认三个列表。审核对类目要求严格报修平台属于生活服务-维修类提交时要选对类目不然会被驳回。如果只是内部项目可以走体验版或测试号不用走公开审核体验版用招待二维码即可。5.3 gunicornNginx生产环境实操生产部署我在Linux服务器上的顺序是这样先装Python 3.8创建虚拟环境pip install -r requirements.txt再把项目代码传到服务器指定目录用gunicorn启动Flask应用绑到127.0.0.1:5000不直接暴露公网最后Nginx配置server块80端口重定向到443443配置SSL证书location / 代理到Flask端口同时把/uploads/映射到项目静态目录。Nginx关键配置参考如下server { listen 443 ssl; server_name yourdomain.com; ssl_certificate /etc/nginx/cert/yourdomain.pem; ssl_certificate_key /etc/nginx/cert/yourdomain.key; location / { proxy_pass http://127.0.0.1:5000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } location /uploads/ { alias /home/project/repair/uploads/; } }gunicorn启动命令是gunicorn -w 4 -b 127.0.0.1:5000 app:app。4个worker对报修平台这种量级完全够如果以后并发上来了再考虑加gunicorn的worker数或者上Docker。6. 实战排错这个平台里踩过的坑和应对6.1 uniapp打包后接口不通的排查思路典型现象本地H5跑得好好的微信开发者工具里接口全部报错。排查顺序很重要先看请求URL是不是被写死了localhost其次看后端有没有跨域配置再看小程序后台request合法域名有没有填。最常见的原因就是baseURL被硬编码在业务代码里一打包就废。我的解法是把环境拆成dev和prod在apiConfig.js里维护一份环境map发布前通过配置切换。另外开发者工具里勾选不校验合法域名只能作为开发期临时手段真机预览和体验版会原形毕露所以线上环境的合法域名配置一定要提前走流程不要拖到最后一刻。6.2 图片上传成功但换设备就裂图这个是域名问题开发者工具勾选不校验合法域名时图片能加载真机或线上环境如果图片URL的域名不在downloadFile合法域名里直接被拦截。还有一个隐蔽坑图片URL如果用了localhost或者局域网IP其他用户根本访问不到。早期我把上传路径写成本地路径结果同一部手机能看换一台手机就裂图。后来统一改成服务器HTTPS绝对地址问题才彻底解决。6.3 可视化数据不刷新的定时器坑管理端大屏数据停留是常见问题原因是页面打开后chart.setOption只执行一次没有重新请求数据。解决办法是在页面里放一个定时器每5分钟重新fetch一次stats接口然后调用chart.setOption更新图表。注意组件销毁时一定要clearInterval不然页面开多浏览器直接卡死。这个定时器坑很经典我一度以为是ECharts缓存后来定位到是定时器泄漏。6.4 常见问题速查表现象可能原因解决方向手机无法访问本地后端防火墙未放行、用了localhost而不是局域网IP换192.168.x.x地址检查防火墙数据库datetime字段序列化报错datetime不是JSON可序列化类型自定义JSONEncoder把datetime转字符串两个维修工同时抢到同一单先查后改产生竞态UPDATE带WHERE statusPENDING判断rowcount小程序预览报错does not exist数据为null时访问嵌套属性接口返回前做空值处理前端用可选链部署后访问500gunicorn未加载环境变量启动前用export或用.env文件加载图片上传失败但不报错uploadFile合法域名未配置小程序后台单独添加上传域名最后再分享几个实操细节报修分类别做太细水、电、网络、空调、门锁、其他六个就够太细反而增加用户选择成本评价体系一定要做但别强制完成订单后弹一次提醒就好后台给维修工设一个接单范围字段比如只接3号楼和4号楼可以避免高峰期抢单混乱。这些细节看着小实际运营时都是用户和物业管理员能直接感受到的痛点。我做这个平台最深的感受是业务规则清晰比代码技巧重要表设计、状态机、合法域名这三件事做好了整个项目就稳了一大半。