自助健身小程序源码：架构拆解、核心链路与本地部署实战

自助健身小程序源码，通常指的是一套可以直接部署运行的「无人值守健身房」业务系统代码，覆盖用户扫码进店、设备开门、计时计费、课程预约、教练排班、会员管理等完整闭环。它和普通健身房管理系统的区别在于：业务的起点不是前台收银，而是硬件指令的下发与回传，系统必须同时处理「软件订单」和「物理门禁」两条状态线。本文从源码结构、核心链路、部署步骤和二次开发四个角度，拆解这套系统怎么跑起来。

一、技术选型与源码整体结构

从目前主流的实现方案看，自助健身小程序源码的典型技术栈是：

后端服务：Spring Boot + MyBatis Plus + MySQL，负责订单、会员、设备、结算等核心领域
用户端 / 教练端：UniApp（Vue 语法），一套代码编译到小程序、H5、App
管理端：Vue + ElementUI，运行在浏览器中，供运营人员使用
配套资料：技术文档、资料准备文档、部署文档

选择 UniApp 而不是原生小程序开发，主要原因是业务需要在多个入口同时存在：用户可能从小程序扫码进来，也可能从 H5 活动页进来，教练端则常常需要 App 的推送能力。用同一套 Vue 语法维护三端，比维护三份代码的边际成本低很多。

后端目录一般按领域划分，而不是按技术分层。一个比较清晰的包结构是：

text 复制代码

com.example.gym
├── module
│   ├── member        // 会员、实名、押金
│   ├── order         // 计时订单、课程订单
│   ├── device        // 门禁、闸机、储物柜、跑步机
│   ├── course        // 团课、私教、排班
│   └── settle        // 结算、分账、流水
├── common
│   ├── mqtt          // 设备指令通道
│   ├── lock          // 分布式锁与幂等
│   └── wechat        // 小程序登录、支付回调
└── job               // 超时关单、设备离线巡检

把 device 单独作为一个领域模块，是这类系统区别于普通电商的关键。设备有在线、离线、故障、使用中四种状态，且状态变更来自硬件主动上报，不能只依赖数据库事务。

二、核心业务链路：从扫码开门到订单结算

自助健身的完整链路可以拆成六个阶段：

用户在门店上扫码，小程序携带门店 ID 与场景值进入
后端校验会员资格：是否实名、是否有未支付订单、当前时段是否允许进入
校验通过后，通过 MQTT 或厂商 HTTP 接口下发开门指令，同时落一条「入场记录」
用户开始使用设备，计时订单以「入场时间」为起点，进入进行中状态
用户离店触发结算，按实际时长生成订单
若订单未支付，写入欠费记录，下次入场时拦截

第 3 步和第 5 步是问题高发区。门禁指令下发失败但订单已经创建，会导致用户没进门却被计费；离店信号丢失，会导致订单一直挂着。因此设备指令必须和业务状态解耦：

java 复制代码

// 先落入场记录，再异步下发指令，失败进入重试队列
EntranceRecord record = new EntranceRecord();
record.setMemberId(memberId);
record.setStoreId(storeId);
record.setStatus(EntranceStatus.PENDING);
entranceMapper.insert(record);

mqttTemplate.publish(deviceTopic, buildOpenCommand(record.getId()));

对应的表结构建议至少包含 member、entrance_record、device、order、order_item 五张主表。entrance_record 与 order 分开，是因为入场不一定产生消费（例如参观、体验），而消费也不一定来自入场（例如线上购买课程）。

计时订单还需要一个兜底任务：对于超过 N 小时仍处于「进行中」的订单，由定时任务扫描并置为异常待处理，避免资金流水长期悬空。

java 复制代码

@Scheduled(cron = "0 */10 * * * ?")
public void closeTimeoutOrders() {
    List<Order> list = orderMapper.selectTimeoutOrders(Duration.ofHours(12));
    for (Order o : list) {
        orderService.markException(o.getId(), "离店信号缺失");
    }
}

三、本地部署与联调步骤

拿到源码后，建议按下面的顺序推进，不要一上来就跑通全流程。

步：环境准备

JDK 17、Maven 3.8+
MySQL 8.0，字符集 utf8mb4
Redis，用于缓存会员状态与分布式锁
Node.js 18+，用于 UniApp 与管理端构建
HBuilderX 或开发者工具

第二步：初始化数据库

导入源码中的 SQL 文件，确认表数量与文档描述一致。重点检查 device 表是否有门店维度的索引，避免多门店共用一个设备编号。

第三步：启动后端

bash 复制代码

mvn clean package -DskipTests
java -jar gym-admin/target/gym-admin.jar --spring.profiles.active=dev

配置文件中的数据库、Redis、MQTT Broker 地址需要按实际环境替换。MQTT 如果没有真实 Broker，可以先用本地的 EMQX 或 Mosquitto 做指令收发验证。

第四步：编译用户端

在 HBuilderX 中打开 UniApp 工程，修改 manifest.json 中的小程序 AppID，然后运行到开发者工具。注意后端接口地址要切换成局域网 IP，而不是 localhost，否则真机调试会失败。

第五步：管理端启动

bash 复制代码

npm install
npm run dev

管理端与后端之间通常有跨域问题，开发阶段可在后端开启 CORS，生产环境建议由 Nginx 统一反向代理。

第六步：模拟设备回调

在真实门禁接入之前，可以用 Postman 或 MQTTX 手动发送一条状态上报消息，验证「入场记录 → 订单状态 → 结算」这条链路是否按预期流转。这一步能提前暴露 80% 以上的状态机问题。

四、二次开发中容易踩的坑

设备协议不统一。 不同厂商的门禁、储物柜、闸机协议差异很大，有的是 MQTT，有的是 HTTP 轮询，有的只提供串口。建议在 device 模块下做一层适配器接口，把厂商差异收敛到 DeviceAdapter 实现类里，业务层只依赖统一的方法签名。

重复开门与并发。 用户快速连点扫码按钮时，可能触发多次开门指令。需要在入场记录上做幂等：以 memberId + storeId + 时间窗口 作为键，或者用 Redis 锁控制。

小程序域名与备案。 小程序要求请求域名必须备案且配置在白名单中。如果源码本身不限制 IP 和域名，部署时也要按平台规则配置合法域名，否则真机上接口全部失败。

多门店数据隔离。 如果一套系统服务多个门店，所有查询都要带上 store_id 条件。建议在 MyBatis Plus 中通过 TenantLineInnerInterceptor 做统一拦截，而不是在每个 Mapper 里手写。

升级与兼容。 源码交付时通常会带技术文档和部署文档，二次开发前先把当前版本打一个 tag，避免后续升级时无法比对差异。

FAQ

Q1：自助健身小程序源码一般包含哪几个端？

通常包括用户端（小程序 / H5 / App）、教练端和管理后台三部分，后端为统一的 Spring Boot 服务。

Q2：没有硬件设备可以先把系统跑起来吗？

可以。先用本地 MQTT Broker 或接口 Mock 模拟设备上报，把会员、订单、结算三条链路验证通，再接入真实硬件。

Q3：源码支持二次开发吗？

多数方案支持二次开发，并提供技术文档、资料准备文档和部署文档。改动前建议先理清 device 与 order 两个模块的边界。

Q4：用户端为什么常用 UniApp 而不是原生开发？

因为同一套代码可以编译到小程序、H5 和 App，维护成本更低，适合需要多渠道入口的健身业务。

Q5：部署时容易出问题的地方在哪？