从排课冲突到状态流转：微信小程序私教预约系统开发记录

一套私教预约系统做完之后回头看真正考验开发的从来不是界面好看不好看而是排课上有没有冲突、状态流转会不会乱、用户重复提交能不能拦住。基于微信小程序实现健身房私教预约管理系统从头到尾把会员端、管理端、数据库和状态机串起来这里把我的设计思路和实操记录完整写一遍。不管你是做课程设计需要参考还是健身房确有排课管理需求这篇都可以拿来对照落地。1. 私教预约这件事为什么必须交给系统来做技术选型之前能想明白“业务痛点到底是什么”的人反而不多。我看过不少小型健身房的真实运作方式教练排课靠微信群会员约时间靠私聊前台确认靠记忆。一旦教练人数超过三五个就必然出现一类典型问题——同一个教练同一时间段被约了两次会员来了说约过教练翻聊天记录说没有最后只能靠店长临时协调。表面上看这是沟通问题本质上却是排课信息不一致的问题。1.1 传统模式下被消耗掉的三类时间我梳理过传统私教沟通模式下的几处损耗这也是最值得被系统优化的地方会员和教练之间的沟通损耗。约课、改约、取消都要来回私聊一个人一天处理二三十条预约消息很常见。教练空档时间的隐形损耗。课时表只有教练自己知道会员看不到空档只能被动等教练回复预约密度很难提上来。月底核对课时的记录损耗。教练按课时拿提成Excel漏记一条就要扯皮半天门店还得专门安排一个人对账。这里有个关键判断信息不一致问题是因为会员、教练、管理员三方掌握的信息各不相同。会员不知道教练哪些时段已被占用教练不知道会员是不是临时变卦管理员更不知道口头承诺算不算数。预约系统的核心任务就是建立统一的数据来源让所有角色都围绕同一份记录做判断减少线下口头承诺造成的混乱。1.2 边界要划清楚这不是一个商城开始动手时很容易犯一个方向性错误把预约系统做成课程商城叠加购物车、满减优惠、积分抵扣、支付流程结果开发周期翻倍核心预约体验还没做好。我最终把边界狠狠划窄了——系统只需要回答三个问题谁在哪个时间段上了哪个教练的课当前预约是什么状态谁能修改这个状态。支付功能可以做但不是核心评价系统可以有但不能淹没预约链路。想清楚边界表结构设计和接口数量都会精简非常多。2. 整体架构与协作方式小程序、管理后台、服务接口的分工系统整体采用前后端分离结构分三层微信小程序端是会员和教练的移动入口负责浏览课程、发起预约、查看记录管理后台是管理员和前台人员处理排课、审核、统计的桌面端后端服务统一处理业务逻辑和数据库读写。数据库选型我偏向关系型数据库因为预约场景对事务一致性要求高关系型数据库的约束机制和事务能力天然匹配。2.1 技术选型的对比与理由选型阶段我对比了好几套组合方案最终结论如下表。关键是看选型逻辑不要只看技术名词本身。端侧候选方案最终选择理由用户端原生App / 小程序 / H5微信小程序无需下载安装授权登录门槛最低管理端桌面客户端 / Web后台Web后台管理员多数时间在电脑前表格化操作效率更高后端服务重量级框架 / 微服务 / 轻量级Web框架轻量级Web框架开发速度快小型业务规模完全够用数据库MySQL / 其他数据库MySQL事务支持稳定社区资料丰富排查问题方便我特别看重微信小程序带来的一个优势会员不需要注册新账号。微信授权登录拿到唯一标识后直接关联业务表即可省掉了短信验证码、密码找回、账号绑定这一整串功能对小型预约系统来说能省出不少开发工时。2.2 模块划分与预约数据的流转方向整个系统分成四个模块用户认证模块、内容展示模块、预约下单模块、后台管理模块。一条完整的预约数据是这样流动的会员在小程序端选中时间片并提交预约后端服务先做时间段冲突校验校验通过后写入预约表再把结果回推给小程序端管理后台同时能看到这条新预约管理员执行确认或驳回操作确认后的状态继续驱动教练端和会员端的界面更新。这里有个设计重点管理员确认动作不能省略它是防止教练私下承诺、随意改课的关键节点不然系统很快就会和线下真实安排脱节。3. 核心数据结构预约不乱套全看这几张表怎么设计预约系统的表数量不多难点在关联关系和时间粒度的控制上。最终落地用了五张核心业务表加两张配置表字段全部用可读性强的命名坚决不用拼音缩写。3.1 会员表、教练表与身份关联会员和教练分开建表按业务需要存不同字段。会员表主要存性别、手机号、剩余课时数教练表存专项方向、授课等级、个人简介和照片链接。两表通过唯一的微信标识与身份关联表做映射。这里有一个很多人会踩的设计坑不要在会员表里直接存微信昵称和头像地址。微信昵称随时会变头像地址属于静态资源两者都不应该被当作业务判断依据。业务逻辑一律依赖后端生成的用户唯一标识前端展示字段可以随时从接口重新拉取。3.2 预约表的关键字段与状态枚举预约表是整个系统的枢纽字段设计如下预约编号唯一主键供后续对账和审计使用会员ID与教练ID外键关联业务表课程ID关联课程表开始时间与结束时间精确到分钟状态字段枚举值标识当前所处状态创建时间、更新时间、取消原因状态枚举我一开始只设计了“待确认”和“已确认”两个上线测试两天就发现完全不够用。真实场景至少需要六种状态待确认、已确认、已取消、已拒绝、已完成、超时关闭。每种状态直接对应管理后台的操作按钮和小程序端的文案展示。另一个细节是“已完成”这个状态不应该由会员端触发而是由教练端或管理端在课程真实结束后确认否则会员随手一点没上的课也会被标成已完成月底统计就全乱了。4. 小程序端开发从授权登录到预约下单的实现细节小程序端表面上是给用户看页面实际上开发重点全部集中在下单主流程的顺畅度和防错能力上。用户打开小程序后路径应该是浏览门店信息、查看教练列表、进入课程详情、选择时间片、提交预约、查看结果。4.1 登录授权就不要把凭证往下传小程序登录流程比我预想中要多一步。标准做法是小程序端先调用登录接口拿到临时凭证再把临时凭证发给后端后端拿凭证向微信平台换取会话密钥和用户唯一标识最后生成自定义登录态返回给小程序。小程序端的关键代码可以简化成下面这样wx.login({ success(res) { if (res.code) { wx.request({ url: https://example.com/api/login, data: { code: res.code }, success: (res) { const { token, memberId } res.data wx.setStorageSync(token, token) wx.setStorageSync(memberId, memberId) } }) } } })很多人图省事直接把微信唯一标识存在前端缓存里做业务判断这个做法我劝你不要学。它属于敏感信息放在本地缓存有泄露风险而且以后账号体系一旦调整这个字段会让你改到崩溃。后端登录接口只需要返回自定义登录态就够了业务侧不要接触原始凭证。4.2 教练列表与课程详情的数据返回策略首页展示教练列表点击教练头像进入详情页可以看到该教练名下可预约的课程以及未来一周的时间片。时间片列表由后端根据排课表计算生成前端只负责展示和选中。这里要特别提醒后端接口返回时间片时必须直接给出剩余可约人数不要返回全量时段让前端自己去减已约数量。否则前端逻辑会越写越复杂还要在后端与前端之间维护两套计数逻辑出问题排查起来非常慢。课程详情页额外加了“剩余名额”和“已约人数”两个展示字段。这两个数据每次请求都实时计算数据库压力扛不住完全用缓存又会显示不准确。我的折中方案是进入详情页时请求一次实时数据用户提交预约成功后刷新一次当前数据。实测在三百人以下的小型健身房场景中这个方案稳定可靠。4.3 重复提交要用前端逻辑拦截下单前的前端校验必不可少至少包括是否选择了教练、是否选择了时间片、剩余课时数是否大于零。这部分校验只是为了优化用户体验接口端的校验才是最后防线。真实项目里遇到过这样的问题会员点击“确认预约”后请求已经发出去了因为网络延迟没立刻收到回执用户以为没提交成功又点了一次结果后台生成了两条预约。解决的办法是在按钮事件上做重复提交保护记录点击时间戳三秒内重复点击直接忽略同时把按钮置灰防止连续操作。5. 管理后台与状态流转预约状态不能拍脑袋定管理后台面向三类角色管理员、前台人员和教练不同角色看到的菜单和操作权限不一样。后台最重要的两个页面是排课管理页和预约管理页。5.1 排课逻辑与时间冲突检测排课的本质是把教练的可用时间切分成标准模块。后台管理员先设定教练每周的可用时间模板系统自动按模板生成未来七天的排课记录。生成过程中必须全程执行冲突检测同一教练同一时间段是否已有排课同一个时间段是否超过最大可约人数。冲突检测我放在后端服务中完成而不依赖数据库的唯一索引。因为预约场景判断的是时间段是否相交不是主键是否重复。核心查询可以这样写SELECT COUNT(*) FROM appointment WHERE coach_id ? AND start_time ? AND end_time ? AND status IN (pending, confirmed)返回结果大于0就说明该时间片已被占用。这个逻辑不难理解但要注意索引设计**coach_id, start_time, end_time**一定要建成组合索引否则数据量稍大查询就会肉眼可见地变慢。5.2 状态机的完整流转规则我把预约状态机最终收敛成下面这套流转规则绝对不允许状态随便跳会员提交预约申请进入待确认管理员后台确认进入已确认管理员驳回申请进入已拒绝必须填写原因会员主动取消进入已取消课程正常上完教练端确认进入已完成超过设置时限未处理自动进入超时关闭有人建议“会员取消必须经过管理员审核”理由是防止会员占住好的时间段后又取消影响后续约课公平性。但我实际测下来这会成倍增加管理员的操作量。更推荐的做法是设置免费取消时限例如开课前两小时可以无条件取消开课前两小时以内的取消才需要联系管理员处理。简单规则交给系统自动执行例外情况保留人工介入的通道。6. 开发过程中踩过的真坑和解决记录这一节是全文含金量最高的部分每一个坑都在实际调试里耗费过时间。如果能把以下三条问题提前在开发阶段规避整个项目的调试周期能缩短一半。6.1 并发预约被双重写入并发冲击是预约系统跑不掉的问题。两个会员在同一秒请求同一个教练的同一个时间片后端两个事务几乎同时查询“这一时间段是否空闲”结果都查到空闲然后各写入一条记录系统里就出现了两单重叠预约。解决思路有两种一种是在查询时加锁简单粗暴但会影响吞吐另一种是乐观锁思路把状态值当作版本号在更新语句的条件里加上版本校验更新的命中条数为0时说明已被抢走直接提示用户重新选择时间片。我用的是第二种实测并发场景下从未出现重复数据实现成本也低很多。6.2 时间片跨日和节假日失效排课模板如果只存“星期几”不考虑具体日期节假日和闭馆日的排课就会出现严重失真。我在系统里增加了一张闭馆日期表管理员可以单独把某一天标记为闭馆。生成排课时直接跳过闭馆日的数据不需要复杂规则一个日期子查询就能完成。这步很容易被忽略但一旦缺失春节期间系统还在正常放出课程时间片会员约了之后教练根本不在后续投诉和改约会占用大量运营时间。6.3 提醒通知的发送限制预约成功后的提醒通知我用的是小程序内部的模板消息能力。这里有个硬性限制模板消息只能在用户主动触发某个行为后才能向该用户发送一次通知系统不能随时随地推送。我的处理方式是把通知触发点绑在用户主动行为上例如会员提交预约后系统立刻发送“预约申请已提交”通知管理员确认后再发送“预约已确认”通知。至于“开课提醒”这类与用户主动行为无关的通知小程序消息通道天然发不出去需要额外引入其他触达通道否则会白白开发。7. 拿到源码后该怎么跑通上线如果你手上是一份现成的源码我强烈建议不要上来就部署先花半小时把项目结构读一遍搞清楚它依赖哪些环境。这类项目一般需要能运行后端服务的环境、一个MySQL数据库、微信开发者工具。启动顺序建议是先初始化数据库再启动后端服务确认接口能正常访问然后在微信开发者工具中导入小程序项目填好基础配置。数据库初始化阶段我栽过一次跟头建库脚本缺了字符集参数数据表默认字符集不对中文昵称和地址全部乱码排查了很久才发现是建库时的问题。在初始化命令里显式加上字符集配置即可CREATE DATABASE IF NOT EXISTS fitness_db DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;部署上线前还要测一个容易被忽略的场景手机号兼容问题。如果业务表里预留了手机号字段但用户一直没填写后面接短信用提醒功能时就会卡住。稳妥的办法是在用户首次提交预约时强制补充手机号而不是等通知功能上线后再去批量补数据那样大概率补不齐还会产生大量重复推送。8. 最后说点个人体会整套系统做完我最大的体会是预约系统的复杂度不在功能数量上而在状态一致性的维护上。每一个“确认”“取消”“完成”动作修改的都是全系统共享的数据源状态枚举一旦混乱界面上就会出现“按钮点了没反应”“状态变了但列表没刷新”这类现象用户会直接怀疑系统坏了而不是怀疑自己操作错了。如果你也要做类似的系统建议先不写任何代码把会员从打开小程序到上完一节私教课的完整路径画出来再为每一步列出涉及的数据字段和状态变化。这步做完开发环节已经有七成的答案。源码和文档里的说明可以参考但真正值钱的是你调试异常情况时积累下来的判断能力尤其是对并发和状态流转的那份敏感度。