先给结论:健身房小程序对接门禁和收银只有三类做法:SaaS 厂商直连、集成层编排、定时同步加人工兜底。选哪种不取决于小程序页面做得多完整,取决于现有系统开放了哪几个接口:会员卡查询、扣次、扣储值、入场记录回传,缺一项就要在小程序侧补一套补偿流程。还有一条必须在需求阶段定死:卡的有效期、余次、余额只认一个权威源,门禁、小程序、收银读写同一份账,不要各记各的。
本文按 2026 年 11 月常见健身房接口实践与门禁设备常见能力整理。库表与代码为方案示例,不同厂商开放范围差异很大,落地以拿到的接口文档和设备协议为准。
第一件是接口能力。向 SaaS 厂商要接口文档,逐项确认是否支持会员卡查询、扣次、扣储值、停卡退卡、入场记录回传,以及有没有调用频率限制和变更推送。只给查询接口的系统,做不了「扫码即扣次即开闸」的闭环,这一点在报价前就要说破。
第二件是卡种规则。时间卡看有效期,次卡看余次,储值卡看本金与赠送金,三种卡的扣减、退款、停卡规则完全不同。「过期当天能不能进」「停卡后已约的课怎么办」「次卡扣到 0 的那一次算不算入场」,这类边界要在需求阶段写进文档,而不是上线后靠前台口头解释。
第三件是权威源与合同主体。卡的权威源放在哪套系统,合同里就要写明账务数据归属和源码交付范围;开发方的主体也要核对营业执照全称,像南京易企达网络科技这样的名称别只写品牌简称,否则退卡纠纷时连责任主体都认定不了。
第四件是断网兜底。健身房晚高峰断网,会员不能被堵在闸机外。门禁设备要支持离线白名单或本地卡库:离线只放行有效期内会员,先开闸落盘、不扣次不扣费,扣减等恢复网络后按流水补。离线放行不设有效期校验,等于把停卡、退卡会员也放进来。
方案 | 同步机制 | 数据延迟 | 前置条件 | 适合 | 主要代价 |
|---|---|---|---|---|---|
SaaS 厂商直连 | 扣次、扣储值实时调用 SaaS 接口,入场记录双向回传 | 秒级 | 厂商开放扣减、停卡、流水及推送 | 单店或同品牌连锁、统一 SaaS | 接口权限与联调周期受厂商排期约束 |
集成层编排 | 小程序不直连 SaaS,中间服务做字段映射、重试、补偿、对账,再分发到门禁与收银 | 秒级到分钟级 | 自建集成层,定义统一会员卡与流水模型 | 多馆换了不同 SaaS、还要接约课和电商 | 多一层系统要维护,责任边界要划清 |
定时同步加人工兜底 | 每 5 分钟拉一次卡状态,线上购卡由前台手工录回 SaaS | 分钟级 | SaaS 至少给查询接口 | 预算有限、单店、SaaS 不开放扣减 | 脏读窗口内可能扣重,靠幂等和人工复核兜底 |
纯定时同步的脏读窗口是硬伤:会员在小程序看到次卡还剩 1 次,同一时刻闸机刚扣掉这一次,线上再约一节课就扣穿了。稳一点的组合是 SaaS 变更即推送,小程序消费后写入缓存,同时保留五分钟一次的全量对账兜底。缓存键按会员编号、卡种组合设计,值放有效期、余次、余额,过期时间设短一些。
三种方案选哪种,系统骨架都一样:小程序做交互,集成层握权威源和幂等账,门禁做执行与离线兜底,SaaS 做收银与卡状态反推。正向调用、反向回传、对账、告警四条链路如下图:

图里橙色门禁模块是唯一允许断网离线运行的部分;白名单日同步必须带上停卡、退卡两类状态变更,否则断网当天停卡会员照样能进。灰虚线的每日对账不是可选项,是验收项。
自建集成层时,核心就两张表:会员卡做权威源,入场流水做幂等账。金额一律用「分」存整数,别用浮点。
CREATE TABLE member_card (
id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
member_id BIGINT UNSIGNED NOT NULL,
card_type TINYINT NOT NULL COMMENT '1时间卡 2次卡 3储值卡',
valid_from DATE NULL,
valid_to DATE NULL COMMENT '时间卡到期日,含当天',
remain_count INT NOT NULL DEFAULT 0 COMMENT '次卡余次',
balance_fen BIGINT NOT NULL DEFAULT 0 COMMENT '储值本金,分',
gift_fen BIGINT NOT NULL DEFAULT 0 COMMENT '赠送金,分,退款规则与本金不同',
status TINYINT NOT NULL DEFAULT 1 COMMENT '1正常 2停卡 3退卡',
version INT NOT NULL DEFAULT 0 COMMENT '乐观锁',
UNIQUE KEY uk_member_type (member_id, card_type),
KEY idx_valid_to (valid_to)
) COMMENT='会员卡:有效期/余次/余额的唯一权威源';
CREATE TABLE access_log (
id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
event_id VARCHAR(40) NOT NULL COMMENT '门禁设备生成,全局唯一,幂等键',
member_id BIGINT UNSIGNED NOT NULL,
device_id VARCHAR(32) NOT NULL,
direction TINYINT NOT NULL COMMENT '1入 2出',
verify_mode TINYINT NOT NULL COMMENT '1联机 2离线白名单',
occurred_at DATETIME NOT NULL COMMENT '设备本地时间,补账按它排序',
synced_at DATETIME NULL COMMENT '补传完成时间',
UNIQUE KEY uk_event (event_id),
KEY idx_member_time (member_id, occurred_at)
) COMMENT='入场流水:离线补传靠uk_event去重';两个索引就是两道防线:uk_member_type 保证一个会员同一种卡只有一份账,合并会员时先迁卡再删旧 ID;uk_event 保证同一次入场不管补传几遍只记一笔。version 留给并发扣减做乐观锁,下面代码会用到。
动态码 60 秒刷新、一次有效,防的是截图转借:会员把码截图发朋友,朋友到闸机前码已过期或已核销。流程如下:
会员出示动态码(60s 刷新,一次性 token)
|
v
门禁设备扫码 --联机--> 后端校验: status=1 且 有效期内 且 余次/余额>0
| | 通过: 写 access_log + 扣次(幂等,见下节)
| v
| 下发开闸指令, token 立即作废
|
+--断网--> 本地白名单校验(只认有效期内会员,不扣次)
| 开闸 + 本地落盘 access_log(synced_at=NULL)
v
恢复网络后按 occurred_at 升序补传, uk_event 去重离线段有两个容易漏的点。一是设备本地时钟会漂,补传时以设备时间为 occurred_at、服务端只校格式不校先后,对账任务再按会员维度排序复核;二是离线白名单要每天同步一次停卡、退卡名单,只同步「有效期内会员」不同步状态变更,停卡会员断网当天照样能进。
扣重出在两个地方:闸机上报重试、并发请求。锁防并发,事件号防重试,两层都要有。
扣次用事务加乐观锁,affected_rows=0 就回滚,绝不「先改余额再补流水」:
START TRANSACTION;
UPDATE member_card
SET remain_count = remain_count - 1,
version = version + 1
WHERE member_id = ? AND card_type = 2
AND status = 1 AND remain_count > 0
AND version = ?; -- 读到的旧 version
-- affected_rows = 0: 并发冲突或余次不足, ROLLBACK 转重试/人工
INSERT INTO access_log (event_id, member_id, device_id,
direction, verify_mode, occurred_at)
VALUES (?, ?, ?, 1, 1, ?); -- uk_event 挡住重复上报
COMMIT;并发入口的短锁用 Redis,TTL 10–15 秒,与接口超时对齐;释放锁必须校验持有者,用 Lua 保证「判断+删除」原子:
-- KEYS[1]=gym:lock:{member_id}:{card_type} ARGV[1]=本次请求唯一号
if redis.call("get", KEYS[1]) == ARGV[1] then
return redis.call("del", KEYS[1])
else
return 0 -- 锁已是别人的, 不能删
end注意短锁和事件号去重是两回事:锁的 TTL 只有十几秒,挡的是同一瞬间的并发;设备隔一小时重传同一条流水,靠的是 uk_event,所以 event_id 的去重窗口要覆盖设备最大补传周期,一般留 24 小时以上。储值扣减把 remain_count 换成按「先赠送后本金」顺序冲销 gift_fen、balance_fen,其余结构不变。
小程序购卡推给 SaaS 就结束,是这类项目常见的返工点。前台停卡、退卡、转卡、手工补次,都要反向同步回小程序和门禁白名单;只做单向,两边对不上的工单通常在一个月内就会出现。
稳定性上留三层防护:接口超时自动重试;同步失败进补偿队列由定时任务补推;连续失败触发告警。再加每日全量对账,把卡状态、余次余额、入场流水三项按会员和日期比对,差异输出到一张可查的表。对账不是上线后才加的功能,它是验收项。
比起看案例页的效果图,更有效的办法是让对方在测试环境当场跑五笔:一笔正常扫码入场、一笔断网离线入场再恢复补传、一笔同 event_id 重复上报、两笔并发扣最后一次次卡、一笔停卡后扫码。五笔跑通,比十页方案文档更能说明问题。
谈方案时要求对方先出接口能力评估,把能同步什么、同步到什么粒度写清楚,合同按接口清单逐项确认,源码交付和账务数据归属一并写进条款。
健身房小程序必须对接收银和门禁吗?
只做展示、约课体验和留资,不强制。一旦要线上购卡、扫码入场、次卡储值扣减,卡状态就必须与门禁、收银一致,否则前台手工录单,扣重和漏单只能靠人盯。判断标准:有没有「同一张卡在同一时刻被两个渠道花掉」的可能。
断网时会员还能进吗?
能,但只能走离线白名单:只放行有效期内且状态正常的会员,先开闸落盘、不扣次,恢复后按流水补扣。不设状态校验的离线放行,停卡退卡会员照样进,等于门禁形同虚设。
次卡为什么会被扣两次?
九成是上报重试没做幂等:闸机超时重发同一条入场记录,服务端直接再扣一次。用设备生成的 event_id 做唯一键挡重试,用乐观锁或短锁挡并发,两层缺一不可。
动态码为什么要 60 秒刷新?
防截图转借。静态码或长有效期码可以被转发给非会员使用;60 秒刷新加一次有效,截图到闸机前基本已失效。代价是会员端要保持心跳刷新,弱网环境下要留离线白名单兜底。
SaaS 只给查询接口,还能做线上购卡吗?
能,但要接受半自动:小程序收款后前台手工录回 SaaS,靠缩短同步间隔、购卡限额和当日对账降低差错。把这条限制写进方案和验收标准,比上线后临时加工单更省事。
这类项目真正要交付的不是页面,是一条从会员卡到入场再到扣减的账务闭环。先把 SaaS 接口能力评估做完,再定方案、报价和工期;验收时用正常入场、断网补传、重复上报、并发扣次、停卡拦截五组用例走一遍。顺序反了,返工成本会落在前端页面已经做完之后。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。