如果你正好在找一套能直接跑起来的微信小程序项目源码而且希望把场馆预约、在线支付、设备控制全部串在一起那这套基于微信小程序的无人羽毛球馆系统值得花一个完整周末去研究。我做这套系统的初衷其实很现实一位开球馆的朋友发现每天晚上十点以后场地空着前台却必须有人值班上午十点以前也是淡场人工成本直接把利润吃掉一大半。于是我把预约、支付、门禁和灯光控制做成一个小程序闭环用户自己订场、自己开门、打完自动关灯结账。整套源码是可以免费拿到手的我在这篇里会把设计思路、核心模块和踩坑过程完整拆开讲适合正在做课设、想入门全栈开发或者准备低成本运营一间无人场馆的朋友。1. 项目背景与需求拆解1.1 无人场馆到底在解决什么问题传统羽毛球馆有三笔绕不开的开支前台人力、场地空置、设备损耗。假设一个四片场地的球馆营业时间从早上七点到晚上十一点至少要安排两班前台。晚场到十点以后可能只有两三片场地在使用但值班人员不能走水电也不能停。无人化改造之后用户通过微信小程序在线选场、支付到点自己扫码开门系统自动开灯结束后自动关灯并结算费用省掉的不只是人力成本还有整个预约收银环节的沟通成本。羽毛球馆的租场场景比健身房的月卡更复杂。它不是“付钱进门随便用”而是按场地、按时段、按价格分片出租。用户需要对日期、时间段、场地号做精确选择系统需要处理同一片场地在不同时间段的占用情况。如果直接把一套“共享储物柜”或“会议室预约”代码搬过来很快就会发现冲突判断、退款规则、设备联动这些地方全都要重写。这也是这个项目最适合做案例分析的原因它把一套典型的“按时段出租资源”的业务模型完整落在了小程序加后端加硬件三层结构上。1.2 系统有哪些角色跑通一个订单要经历什么无人羽毛球馆系统主要涉及三类角色普通用户、场馆管理员、系统后台任务。普通用户通过微信小程序完成注册登录、选场、支付、入场、结束订单管理员在管理端配置场地信息、时段价格、设备状态处理异常订单后台任务则负责超时判断、自动关灯、退款等不需要人干预的操作。一个完整订单的流程大概是这样用户打开小程序先看到场馆列表和当天可预约的场地展示选择日期后系统加载每个场地的时间段并标记哪些已经被占用用户选定一片场地和一个时间段提交订单并完成微信支付支付成功后订单变为待使用状态开场前系统提醒用户用户到场后点击小程序里的“开门”按钮或扫描门口二维码门禁打开、灯光自动亮起到结束时间后系统延迟几分钟强制结束并结算剩余押金原路退回全部过程不需要前台出现。1.3 为什么第一版就锁定微信小程序羽毛球馆的顾客来源高度集中在微信生态里球友群、公众号、朋友圈这些渠道都能直接拉起小程序用户不需要额外下载App。微信支付和微信登录天然打通支付体验比在第三方网站扫码顺畅很多。小程序还有订阅消息能力可以在开场前给用户推送提醒也可以处理超时提醒。对开发者来说小程序前端开发门槛低后端可以复用熟悉的Java或Node技术栈这套源码就是典型的小程序前端加Java后端整体结构非常适合当课设案例或者作为创业项目的第一版MVP。2. 系统整体架构设计2.1 小程序端页面划分与技术要点源码的小程序端采用的是原生微信小程序框架目录结构很清晰主要页面分成四个Tab首页、预约、订单、我的。首页用于展示场馆信息和场地状态预约页是关键页面包含日期选择器、场地列表、时间段表格用户在这里完成核心下单操作订单页展示待支付、待开场、使用中、已完成等状态分组我的页面处理登录、优惠记录、退款申请等个人数据。开发时几个技术要点需要特别留意。第一是请求封装小程序的wx.request不能在每个页面重复写源码里封装了一个request工具统一处理登录态token、错误码和加载状态。第二是日期处理日期选择和时段表联动时前端要有一个“根据日期切换场地时段”的公共方法否则代码会越写越乱。第三是倒计时状态订单列表中的“距离开场时间”“距离结束时间”这些展示需要在页面onShow和倒计时定时器里同步更新。2.2 后端接口如何设计后端接口的核心是围绕订单状态展开的接口数量不多但每个接口的职责很明确。下面这张表基本就是整套系统的服务端脉络。接口功能路径示例说明场地列表/api/court/list返回场馆和场地信息可用时段/api/court/available根据日期和场地查询可预约时段创建订单/api/order/create锁定场地并生成待支付订单微信支付/api/pay/unifiedOrder调用微信统一下单支付回调/api/pay/notify微信支付结果通知接口开门入场/api/order/enter校验订单状态并触发设备开门主动结束/api/order/finish用户提前结束场地后台超时处理定时任务自动结束订单并关灯后端建议采用Spring Boot加MyBatis的结构权限控制上用户端用登录token管理端单独走管理员会话。接口统一返回code、message、data三层结构方便前端统一处理错误。这里有一个容易被忽略的点支付创建订单时接口内部必须再次校验场地的占用状态不能只相信前端传过来的参数。2.3 数据库核心表设计数据库设计决定这套系统能不能扛住并发也决定后续改造成其他场景时顺不顺手。核心表主要包括用户表、场地表、时段模板表、订单表、设备表和流水日志表。场地表保存场地名称、编号、容纳人数时段模板表保存每天可被预约的时间模板比如从07:00到23:00按小时切分订单表记录用户、场地、日期、时段、金额、状态设备表记录场地对应的门锁设备和灯控设备流水日志表记录支付回调、开门记录、退款记录等。订单表里最关键的是状态字段和唯一性约束。状态字段至少要覆盖待支付、已支付待使用、使用中、已完成、已取消、退款中、已退款。唯一性约束的目的是避免同一片场地在同一个日期时段被重复下单实际项目中我在用户点击下单时会先锁场地行再插入订单这样并发场景下也不会出现超卖。2.4 硬件联动门禁和灯光怎么接进来无人场馆最容易翻车的不是软件而是硬件联动。这套源码在硬件上采用的是MQTT协议门禁用电磁锁灯光用继电器控制智能断路器设备端用ESP32或树莓派这类联网板卡接入网络。整体链路是小程序点“开门”后后端校验订单是否有效随后发送一条MQTT消息到对应主题设备收到消息后控制继电器打开门锁再返回一条消息给服务器记录状态。灯光控制可以做得更主动一些。预约开场前十分钟定时任务向设备发送开灯指令订单结束并确认用户离场后向设备发送关灯指令。为了安全门锁推荐选断电开锁型电磁锁这样遇到停电时门会自动打开不会把用户困在场馆里。3. 关键模块实现细节与源码解析3.1 场地预约与时间冲突处理羽毛球馆预约的核心问题是时间冲突。同一个场地同一个时段不能让两个用户同时支付成功。实现上我建议把时间切成固定粒度的时段比如一小时或半小时一段然后在下单时通过数据库事务来控制。参考代码思路如下begin; select * from court where id #{courtId} for update; select count(*) from orders where court_id #{courtId} and booking_date #{date} and time_slot_id #{slotId} and status in (1, 2, 3); if count 0 then rollback; else insert into orders(...); commit;先锁场地再做占用判断最后插入订单这样并发请求会被数据库行锁串行化。这个方案实现简单而且能保证不超卖。如果不想锁表也可以依赖唯一索引在插入订单时对场地、日期、时段加唯一键数据库冲突时捕获DuplicateKeyException提示用户“该时段已被抢”。两种方式我都实际跑过慢一点但更稳妥的是行锁方案代码可读性也更好。3.2 微信支付与订单状态机微信支付是整个系统里最容易出问题的模块但不是因为支付SDK有多难而是因为订单状态管理太粗糙。很多第一次做支付的人只用一个status字段支付成功置1退款置2看起来简单却埋了一堆雷。我在这套源码里把状态拆成七个分别是0待支付、1已支付待使用、2使用中、3已完成、4已取消、5退款中、6已退款。用户创建订单后进入0支付回调成功后进入1扫码入场后进入2用户主动结束或系统超时结束进入3。如果开场前取消已支付的订单要走到5再变成6而不是直接从1跳到4。微信支付回调有三个必须处理好的细节金额单位是分接口拿到的是分数据库里建议也按分存储避免浮点误差。回调地址必须是公网HTTPS地址本地联调需要先部署到云服务器或使用公网映射服务。回调通知可能重复处理逻辑必须幂等同一笔订单收到多次通知不能重复更新状态或重复退款。回调处理成功后接口必须返回微信要求的成功报文否则微信会按照失败策略持续重试。这个机制本身是保护但如果代码没有幂等处理就会造成重复退款。3.3 扫码入场和远程开门怎么配合无人球馆的用户体验很大程度上取决于“开门”这一步是否顺畅。最理想的情况是用户走到门口小程序自动识别蓝牙或地理位置然后门自动打开。但第一版项目把硬件成本压得很低所以我采用了“小程序点击开门”加“门口二维码读头”双方案。简单做法是用户订单详情页生成一个有效期为60秒的动态二维码门口安装一个二维码扫码摄像头用户扫码后设备端拿到订单号调用后端接口校验后开锁。更省钱的做法是直接在小程序里放一个按钮用户到达场馆后点击“开门”后端判断当前时间是否在预约时段内并且订单状态为已支付待使用然后向MQTT设备发送开锁指令。远程开门后台要注意设备在线状态。设备需要每30秒上报一次心跳后端把心跳时间记录在设备表里。如果设备超过两分钟没有心跳前端在用户点击开门时应提示“设备离线请联系管理员”而不是默默地发送一条永远不会被收到的消息。我在这套源码里专门为这条链路加了指令ID设备收到指令后必须回复前端收到回复才显示开门成功。3.4 超时、爽约和自动退款怎么算无人值守系统必须有异常订单的兜底规则。我在开发时把用户付了钱但不来、来了不打完就走、到点不走这三种情况分别做了处理。开场后三十分钟用户没有扫码入场系统自动取消订单已付金额原路退回用户入场后提前离开点击“主动结束”则按实际使用时长结算剩余金额退回用户到时间没有主动结束系统会提前十五分钟通过订阅消息提醒到点后再延迟十分钟强制结束并自动关灯关门防止场地被免费占用。退费规则不要写死在代码里我建议放到配置表里比如“开场前24小时可免费取消”“开场后30分钟内未使用可全额退”。这样后续运营调策略时不用重新发布版本管理员在后台改配置即可。4. 部署与调试实录4.1 本地跑起来需要哪些环境如果你拿到源码想先跑通需要准备这些基础环境JDK 1.8以上、MySQL 5.7或8.0、Redis、微信开发者工具。数据库脚本在源码的sql目录下直接执行init.sql就能创建表和初始化数据。后端配置文件里需要修改数据库连接、小程序appid和secret、微信支付商户号等信息。前端项目导入微信开发者工具后要把config.js里的baseURL改成后端实际地址。本地联调阶段微信开发者工具可以勾选“不校验合法域名”这样http地址也能访问但要发布上线所有请求域名必须备案并且是HTTPS。源码里自带了一个mock支付开关没有真实商户号时打开这个开关支付流程会自动跳到回调成功方便本地把完整链路走通。4.2 核心配置与演示数据源码内置的管理员账号和测试用户数据直接放在初始化脚本里。用户登录流程是典型的wx.login获取code后端再用code换取openid生成token返给前端。这里要特别提醒小程序的appsecret是敏感信息绝不能暴露在小程序前端代码中所有的登录逻辑必须走后端接口。演示用的场地数据包含四片羽毛球场地每片场地对应一个时段模板。管理员可以在后台调整不同时段的单价比如工作日白天便宜一些晚上和周末贵一些。价格规则做成了一张独立的价格表前端展示时再根据日期和时段去查这样运营策略调整非常灵活。4.3 真机预览与公网联调的坑模拟器跑通只是第一步真机预览时最大的坑就是请求失败。手机访问不到电脑的localhost必须把后端部署到一台公网可达的服务器上或者使用支持HTTPS的公网映射服务。微信小程序正式环境强制要求所有请求域名备案加HTTPS所以领域和证书要早点准备不要等真机调试时才处理。支付回调更依赖公网环境微信服务器需要访问到你的回调地址。第一次接微信支付时最容易卡在这里本地启动的回调地址微信根本访问不到。我当时做这套项目时直接把后端部署到一台低配云服务器上调试省掉了很多麻烦。5. 常见问题与排查技巧实录5.1 登录态和session_key过期用户用着用着突然提示登录过期或者获取微信昵称、手机号失败很多时候是因为前端长期使用同一个登录code或者缓存了过期的session_key。解决办法是让前端在需要用户身份时通过wx.login换取新code后端再根据code刷新token每次请求带上token后端校验token有效性和过期时间。不要在每个页面onLoad里都重复登录这样既慢又容易触发微信接口频率限制。5.2 支付回调丢失或重复用户微信里已经显示扣款成功但小程序订单还停留在待支付状态这个问题八成出在回调环节。先去微信支付商户平台查回调记录看回调请求有没有到达服务器。如果压根没到基本就是回调地址不可达或没有返回正确报文如果到了但订单没更新要在代码里加日志确认是不是更新条件写错了。回调处理必须幂等数据库里应记录每一笔支付流水的唯一流水号重复通知到达直接返回成功。5.3 门禁指令发出但设备没动设备没响应是现场调试最头疼的问题。按钮显示已发送门却没有开可能的原因有设备离线、MQTT主题订阅错误、继电器供电不足、电磁锁电压不够。我在源码里给设备加了心跳机制和指令回执机制设备离线超过设定时间就自动标记为异常用户端访问时直接提示“设备离线”。本地调试时建议用串口工具打印设备接收到的原始消息先确认指令是否到达再排查硬件供电。5.4 时段超卖和并发扣款两个人同时抢同一片场地最后都收到了支付成功通知这种问题在并发测试中很容易暴露。我当时用压测工具模拟了二十个并发请求发现订单表在无锁情况下确实会产生两条相同场地时段的记录。解决方案就是前面提到的在事务里对场地行加排他锁或者依赖唯一索引兜底。加锁以后接口响应会慢一点但对球馆预约这种低频高价值场景完全够用正确性远比极端性能重要。问题现象可能原因处理方式登录频繁失效token过期或session_key失效后端统一刷新token前端带token请求支付成功但订单未更新回调不可达或未幂等处理查看回调日志返回成功报文记录流水号门控设备无响应MQTT离线或供电不足增加心跳检测串口打印接收数据同一场地被重复预约缺少并发锁或唯一约束下单时锁场地行或加唯一索引兜底到点后灯不自动关定时任务未触发检查后端定时任务的执行日志和设备在线状态6. 源码价值、可复用场景与后续扩展6.1 什么人适合读这套源码如果你是做课设或毕业设计的学生这套源码的工程结构很典型前端是原生微信小程序后端是Spring Boot数据库有完整设计再加上硬件联动部分应付答辩绰绰有余。如果你想完整学一遍“小程序加后端加设备”的全栈开发这套源码也是一个很好的起点因为它的业务复杂度适中不会像商城系统那样页面多到看不过来也不会像单页应用那样学不到深度。如果你是准备做无人场馆运营的人我建议先不要急着自己从零开发把源码跑通拿一个小型场地做试运营重点观察异常订单率和设备在线率。技术只是手段真正决定利润的是运营规则。6.2 改成其他共享场景要动哪些地方羽毛球馆本质上是一条“按时段出租场地资源”的业务线。把“羽毛球场地”换成“自习室座位”“会议室”“共享乒乓球台”整个系统骨架几乎不用大改。我在源码里保留了court这张表但增加一个resource_type字段会更通用后台和前端都能识别不同资源类型。价格规则建议独立成一张表而不是硬编码在场地表里。比如工作日与周末、白天与晚上、闲时与旺季定价都不同独立的价格表可以覆盖所有场景。把预约对象抽象成资源后这套代码可以快速改造成会议室预约系统、共享健身房时段预约、自习室座位管理系统核心逻辑完全一致。6.3 从Demo到商用还需要补什么源码的价值是跑通闭环但真要用在正式运营中还有几个地方必须加强。首先是视频监控无人场馆必须有摄像头覆盖至少要能看到入场口和场地全貌其次是异常告警设备离线、订单长时间未结束、退款失败都应该有通知机制能推送给管理员再就是用户实名认证和保险体系不管最终选择哪家服务商这套东西不能省。硬件上建议增加备用电源门禁选用断电开锁类型灯控设备选择有物理开关旁路的型号防止控制器故障导致整个场地无法使用。运营中要定期看设备心跳和定时任务日志把这些基础工作做扎实无人场馆才能真正稳定跑起来。这套代码我后来改造过一个亲子活动室版本最大的体会是无人值守系统的难点从来不是开发而是“无人时发生的问题怎么被知道”。支付回调、门禁心跳、超时任务每一样都要有日志和通知否则用户的投诉电话会一个接一个。源码建议你直接下载跑一遍再对照这篇文章把订单状态流转画清楚之后改造成自己的项目就不会发怵了。如果你也在折腾这一类共享空间系统欢迎一起交流。
