LikeShop 按摩到家系统疗程卡管理:多次服务核销与到期提醒二开方案
一、痛点分析:为什么原生系统撑不起疗程卡
LikeShop 按摩到家系统原生已经具备“预约 → 派单 → 上门服务 → 核销”的完整单次履约链路,订单状态覆盖待接单、技师出发、开始服务、服务完成等节点。技师端支持扫码核销,后台也支持直接核销,单次服务的闭环是通的。
但疗程卡(次卡)的业务模型和单次订单有本质区别。疗程卡是“一次付费、多次核销”的预付费产品,原生系统以单次订单为核心设计,在三个地方存在结构性缺口:
缺口一:次数与生命周期的承载缺失。 原生订单表只能表达“这一次服务是否完成”,无法表达“这张卡总共10次、已用3次、还剩7次、什么时候过期”。就像家政次卡二开实践中所指出的,原生系统能够支撑单笔核销业务闭环,但在持卡用户的次数管理和生命周期管理上存在短板。
缺口二:核销的对账与防重。 按摩到家的技师一天可能服务多个持卡用户,如果每次核销都在不同时间、不同终端发生,缺乏统一的核销流水和幂等控制,容易出现重复扣次、超次核销、余额为负等资损风险。家政次卡的实践也强调了这一点:批量核销、多端操作时,缺少严格的幂等与并发控制,风险非常突出。
缺口三:到期提醒的缺失。 用户买了10次卡,用了3次就忘了,等到想起来时已经过期,剩余7次作废——这是按摩到家客诉最集中的场景之一。临期用户本是召回复购的高价值人群,缺少提醒不仅损失体验,也错失了续卡转化的窗口。
这篇文章的二开方案,核心思路是:不动原生订单表的核心结构,独立构建一套“疗程卡账户 + 核销流水 + 状态机 + 定时提醒”的体系。疗程卡的购买走原生支付通道,核销走独立的卡账户扣减,到期提醒复用 LikeShop 已有的 crontab 定时任务机制。
二、整体架构:卡账户与订单解耦
方案拆成四条独立的链路:
购买链路:用户购买疗程卡 → 生成一条 order_type = package_card 的订单 → 原生支付成功后 → 不触发原生的“服务完成核销”逻辑,而是创建一张疗程卡账户,写入总次数和有效期。
核销链路:技师完成一次服务 → 在技师端发起核销 → 核销服务校验卡状态、有效期、剩余次数 → 扣减次数(乐观锁/分布式锁) → 写入核销流水 → 关联本次服务订单。
状态机:疗程卡本身有独立于订单的状态流转——待激活 → 使用中 → 已用完 / 已过期 / 已冻结。状态变更必须走统一的 PackageCardStatusLogic 入口,不允许在任何地方直接 update 状态字段。
提醒链路:LikeShop 的定时任务通过 php think crontab 统一调度,每分钟执行一次,子任务在后台「系统设置 → 系统维护 → 定时任务」中配置和开关。疗程卡的到期提醒作为一个新的子任务注册进去,按到期节点分级扫描并推送。
遵循 LikeShop 二开的“扩展优先”原则,整个方案不修改 OrderLogic 的核销主链路,疗程卡的核销是旁路扣减,原生订单仍然记录单次服务的履约状态。
三、数据模型:三张核心表
3.1 疗程卡模板表
存储可售卖的疗程卡产品定义。新建 ls_package_card_template:
CREATE TABLE `ls_package_card_template` (
`id` int UNSIGNED NOT NULL AUTO_INCREMENT,
`name` varchar(100) NOT NULL COMMENT '疗程卡名称,如“全身精油SPA 10次卡”',
`goods_id` int NOT NULL COMMENT '关联的服务商品ID',
`total_times` int NOT NULL COMMENT '总次数',
`valid_days` int NOT NULL DEFAULT '365' COMMENT '有效天数',
`price` decimal(10,2) NOT NULL COMMENT '售价',
`status` tinyint DEFAULT '1' COMMENT '1-上架 0-下架',
`create_time` int UNSIGNED DEFAULT '0',
PRIMARY KEY (`id`),
KEY `idx_goods` (`goods_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='疗程卡模板';
total_times 和 valid_days 在用户购买时快照到账户表,后续模板调整不影响已售出的卡。这和 LikeShop 订单商品快照的设计逻辑一致——下单时固化的数据不受商品后续变更影响。
3.2 用户疗程卡账户表
每张卡对应一条记录。新建 ls_user_package_card:
CREATE TABLE `ls_user_package_card` (
`id` bigint UNSIGNED NOT NULL AUTO_INCREMENT,
`card_no` varchar(32) NOT NULL COMMENT '卡号',
`template_id` int NOT NULL,
`user_id` int NOT NULL,
`order_id` int NOT NULL COMMENT '购买时的订单ID',
`total_times` int NOT NULL COMMENT '总次数(购买时快照)',
`used_times` int NOT NULL DEFAULT '0' COMMENT '已用次数',
`remaining_times` int NOT NULL COMMENT '剩余次数(冗余字段,便于查询)',
`status` tinyint NOT NULL DEFAULT '0' COMMENT '0-待激活 1-使用中 2-已用完 3-已过期 4-已冻结',
`activate_time` int UNSIGNED DEFAULT '0',
`expire_time` int UNSIGNED NOT NULL COMMENT '过期时间(购买/激活时固化)',
`version` int DEFAULT '0' COMMENT '乐观锁版本号',
`create_time` int UNSIGNED DEFAULT '0',
`update_time` int UNSIGNED DEFAULT '0',
PRIMARY KEY (`id`),
UNIQUE KEY `uk_card_no` (`card_no`),
KEY `idx_user_status` (`user_id`, `status`),
KEY `idx_expire` (`status`, `expire_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户疗程卡账户';
remaining_times 是冗余字段,虽然可以通过 total_times - used_times 计算,但列表查询和提醒扫描时直接读冗余字段可以避免每行都做减法。一致性由核销逻辑保证:每次核销同时更新 used_times 和 remaining_times。
idx_expire 索引是到期提醒任务的核心查询路径——WHERE status = 1 AND expire_time BETWEEN ? AND ?。
3.3 核销流水表
每一次核销都必须留痕。新建 ls_package_card_log:
CREATE TABLE `ls_package_card_log` (
`id` bigint UNSIGNED NOT NULL AUTO_INCREMENT,
`card_id` bigint NOT NULL,
`user_id` int NOT NULL,
`order_id` int NOT NULL COMMENT '本次服务对应的订单ID',
`technician_id` int NOT NULL COMMENT '核销技师ID',
`change_type` tinyint NOT NULL COMMENT '1-购买激活 2-核销扣次 3-过期作废 4-人工调整',
`change_times` int NOT NULL COMMENT '变动次数(扣减为负数或正数,按约定)',
`times_after` int NOT NULL COMMENT '变动后剩余次数',
`idempotent_key` varchar(64) NOT NULL COMMENT '幂等键:card_id + order_id',
`remark` varchar(255) DEFAULT '',
`create_time` int UNSIGNED NOT NULL,
PRIMARY KEY (`id`),
UNIQUE KEY `uk_idempotent` (`idempotent_key`),
KEY `idx_card` (`card_id`),
KEY `idx_technician` (`technician_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='疗程卡核销流水';
idempotent_key 是防重复扣次的关键。格式为 {card_id}_{order_id},数据库唯一索引保证同一张卡针对同一个服务订单只能核销一次。
四、核销逻辑:幂等与并发的双重保障
4.1 核销入口与前置校验
技师在技师端完成服务后,发起核销。核销服务首先做一轮前置校验:
class PackageCardLogic
{
public static function verify(int $cardId, int $orderId, int $techId): array
{
$card = PackageCardModel::find($cardId);
if (!$card || $card['user_id'] != OrderModel::where('id', $orderId)->value('user_id')) {
throw new Exception('疗程卡与订单不匹配');
}
if ($card['status'] == 3) {
throw new Exception('疗程卡已过期,无法核销');
}
if ($card['status'] == 4) {
throw new Exception('疗程卡已冻结');
}
if ($card['remaining_times'] <= 0) {
throw new Exception('疗程卡次数已用完');
}
if ($card['expire_time'] > 0 && $card['expire_time'] < time()) {
// 过期兜底:状态可能尚未被定时任务更新
throw new Exception('疗程卡已过期');
}
return $card;
}
}
这里有一个容易被忽略的细节:不能只依赖 status 字段判断过期。定时任务每分钟扫描一次,卡可能在两次扫描之间过期。核销时必须同时校验 expire_time 时间戳,作为最后一道防线。
4.2 并发控制:Redis 锁 + 乐观锁
多个技师可能同时为同一个用户的不同服务订单核销同一张卡(比如用户一天内做了两个不同项目),或者在极端情况下同一订单被重复提交核销。采用Redis 分布式锁 + 数据库乐观锁双层控制:
public static function consume(int $cardId, int $orderId, int $techId): bool
{
// 1. 幂等:先查流水是否存在
$idempotentKey = "{$cardId}_{$orderId}";
$exists = PackageCardLogModel::where('idempotent_key', $idempotentKey)->find();
if ($exists) {
return true; // 已核销过,直接返回成功
}
// 2. 分布式锁:防止并发扣减
$lockKey = "pkg_card_lock:{$cardId}";
$locked = Redis::set($lockKey, 1, ['NX', 'EX' => 5]);
if (!$locked) {
throw new Exception('当前核销人数较多,请稍后重试');
}
try {
$card = self::verify($cardId, $orderId, $techId);
// 3. 乐观锁更新:带上当前 version 和 remaining_times 条件
$affected = PackageCardModel::where('id', $cardId)
->where('version', $card['version'])
->where('remaining_times', '>', 0)
->update([
'used_times' => $card['used_times'] + 1,
'remaining_times' => $card['remaining_times'] - 1,
'status' => ($card['remaining_times'] - 1) == 0 ? 2 : $card['status'],
'version' => $card['version'] + 1,
'update_time' => time(),
]);
if (!$affected) {
throw new Exception('核销失败,卡状态已变化,请刷新后重试');
}
// 4. 写入核销流水(唯一索引兜底幂等)
PackageCardLogModel::create([
'card_id' => $cardId,
'user_id' => $card['user_id'],
'order_id' => $orderId,
'technician_id' => $techId,
'change_type' => 2,
'change_times' => -1,
'times_after' => $card['remaining_times'] - 1,
'idempotent_key' => $idempotentKey,
'create_time' => time(),
]);
return true;
} finally {
Redis::del($lockKey);
}
}
幂等有双层保障:第一层是查询流水,第二层是数据库唯一索引。即使两个请求同时穿过了查询检查,唯一索引也会阻止第二条流水插入,此时捕获唯一索引冲突并返回成功即可。
状态自动流转:剩余次数扣到 0 时,status 自动从 1(使用中)变为 2(已用完),不需要单独触发。
五、疗程卡状态机
疗程卡的状态流转独立于订单状态机,但同样需要严格约束:
0(待激活) → 1(使用中) → 2(已用完)
↓
3(已过期)
↓
4(已冻结) ←→ 1(使用中) [解冻]
激活:用户购买支付成功后,卡创建为 0。首次核销时自动激活为 1,同时固化 expire_time(如果模板的 valid_days 从激活日开始计算)。如果模板规定从购买日开始计算,则购买时即固化。
过期:定时任务扫描 status = 1 AND expire_time < now() 的卡,迁移到 3。过期不退还剩余次数对应的金额,除非业务策略另有规定。
冻结/解冻:平台运营人员可以对异常卡执行冻结,冻结后核销被拒绝。解冻后恢复 1。
所有状态变更走统一的 PackageCardStatusLogic::transit(),记录状态变更日志,禁止直接 update:
class PackageCardStatusLogic
{
const TRANSITIONS = [
0 => [1, 3, 4], // 待激活 → 使用中 / 已过期 / 已冻结
1 => [2, 3, 4], // 使用中 → 已用完 / 已过期 / 已冻结
2 => [],
3 => [],
4 => [1], // 已冻结 → 使用中(解冻)
];
public static function transit(int $cardId, int $toStatus, string $remark = ''): bool
{
$card = PackageCardModel::find($cardId);
if (!in_array($toStatus, self::TRANSITIONS[$card['status']] ?? [])) {
throw new Exception("非法状态迁移:{$card['status']} → {$toStatus}");
}
$affected = PackageCardModel::where('id', $cardId)
->where('status', $card['status'])
->update([
'status' => $toStatus,
'update_time' => time(),
]);
if (!$affected) {
throw new Exception('状态更新失败,请重试');
}
// 记录日志(可复用 PackageCardLog,change_type = 5)
return true;
}
}
这与 LikeShop 订单状态机的设计哲学一致:状态流转有规则、变更有日志、非法跳转被拦截。
六、到期提醒:多级节点 + 定时任务驱动
6.1 提醒策略
到期提醒不能只发一次“你的卡快过期了”,而应该按到期节点分级触发,并且每次提醒都带上“剩余次数 + 到期日期 + 续费入口”,让用户可以直接行动。参考行业实践,建议设置四个节点:
| 节点 | 触发条件 | 提醒内容重点 |
|---|---|---|
| 7天前 | expire_time - 7d <= now < expire_time - 3d |
温和提醒,附带剩余次数 |
| 3天前 | expire_time - 3d <= now < expire_time - 1d |
紧迫感加强,引导尽快预约 |
| 1天前 | expire_time - 1d <= now < expire_time |
最后提醒,附续费/延期入口 |
| 过期后 | expire_time <= now 且状态仍为使用中 |
告知已过期,提供挽回方案(如恢复次数需补差价) |
每个节点只提醒一次,通过在账户表增加 notice_flags 字段(JSON 存储已触发的节点)或独立的提醒记录表来实现。
6.2 定时任务实现
在 LikeShop 的 Crontab 命令中新增一个子任务。LikeShop 的定时任务每秒级精度不需要,每天执行一次即可(比如凌晨 3 点),避免每分钟扫描全表:
class PackageCardExpireNoticeJob
{
public function handle(): void
{
$now = time();
$nodes = [
'7d' => [7 * 86400, 3 * 86400],
'3d' => [3 * 86400, 1 * 86400],
'1d' => [1 * 86400, 0],
];
foreach ($nodes as $flag => [$startOffset, $endOffset]) {
$start = $now + $endOffset;
$end = $now + $startOffset;
$cards = PackageCardModel::where('status', 1) // 使用中
->where('expire_time', '>=', $start)
->where('expire_time', '<=', $end)
->whereRaw("JSON_CONTAINS(notice_flags, ?) = 0", [json_encode($flag)])
->limit(200)
->select();
foreach ($cards as $card) {
// 推送模板消息
MessageService::sendCardExpireNotice($card['user_id'], [
'card_name' => $card['template_name'],
'remaining_times'=> $card['remaining_times'],
'expire_date' => date('Y-m-d', $card['expire_time']),
]);
// 标记已提醒
$flags = json_decode($card['notice_flags'] ?: '[]', true);
$flags[] = $flag;
PackageCardModel::where('id', $card['id'])->update([
'notice_flags' => json_encode($flags),
]);
}
}
}
}
6.3 过期状态迁移
提醒任务之后,还需要一个过期处置任务,将超过 expire_time 的卡从 1 迁移到 3:
public function handleExpire(): void
{
$now = time();
$cards = PackageCardModel::where('status', 1)
->where('expire_time', '<=', $now)
->limit(100)
->select();
foreach ($cards as $card) {
try {
PackageCardStatusLogic::transit($card['id'], 3, '到期自动过期');
} catch (\Exception $e) {
Log::error("疗程卡过期处理失败 card_id={$card['id']}: " . $e->getMessage());
}
}
}
核销时的时间戳兜底(第4.1节)保证了即使这个任务因为某种原因延迟,用户也无法用已过期的卡核销。
七、与技师端核销入口的对接
LikeShop 按摩到家系统的技师端本身就有“扫码核销”的交互。二开时,在技师完成服务、提交核销的原有页面上,增加一个“使用疗程卡核销”的选项:
- 如果用户本次服务用的是已购买的疗程卡,技师选择对应的卡,调用
PackageCardLogic::consume()。 - 如果用户是单次付费,仍然走原生核销流程。
- 核销成功后,原生订单的履约状态照常流转到“已完成”,疗程卡的扣次是独立记录。两者解耦的好处是:即使疗程卡模块出现异常,单次订单的履约记录不受影响。
技师端的收入统计仍然基于原生订单的佣金结算,疗程卡的核销不额外产生技师收入(或者按照卡的售价分摊,这属于业务策略,可以在卡模板中配置 technician_commission_rate,但不在本次二开的核销主链路中)。
八、二开避坑清单
坑一:直接在 user_money 或原生订单上记录次数。 疗程卡是“次数债务”,不是“金额余额”。混在一起会导致退款时无法区分哪些是未消耗的卡内权益,财务对账一团乱。必须用独立的账户表。
坑二:核销没有幂等键。 技师端网络抖动导致用户连点两次核销,或者后台重试,会扣两次次数。idempotent_key 的唯一索引是兜底方案,不能省略。
坑三:只靠 status 判断过期。 定时任务有执行间隔,卡可能在间隔期内过期。核销逻辑必须同时比对 expire_time 时间戳。
坑四:提醒任务每分钟扫全表。 到期提醒是低时效性需求,每天执行一次足够。每分钟扫描 expire_time 会让数据库在非高峰时段也承受不必要的压力。
坑五:重复提醒骚扰用户。 如果 notice_flags 没有正确标记,同一个节点可能每天推送一次。用户在 7 天内收到 7 条“快过期了”,体验极差,甚至直接卸载。必须保证每个节点只触发一次。
坑六:状态机被绕过。 过期、用完、冻结都直接 update status,不走 PackageCardStatusLogic,后续排查“这张卡为什么突然不能用了”时没有任何变更日志。
九、总结
LikeShop 按摩到家系统疗程卡管理的二开,核心是三条线:
账户体系:独立的 ls_user_package_card 承载次数和有效期,独立 ls_package_card_log 承载核销流水。不修改原生订单表和余额表,购买走原生支付,核销走旁路扣减。
核销安全:Redis 分布式锁 + 数据库乐观锁 + idempotent_key 唯一索引,三层保障防止重复扣次和并发超扣。核销时双重校验 status 和 expire_time。
到期提醒:复用 LikeShop 的 crontab 机制,按 7天/3天/1天/过期 四个节点分级触发模板消息,每个节点仅提醒一次,并由独立的过期处置任务完成状态迁移。
守住三条底线:次数债务不混入金额余额、核销必须幂等、状态变更必须走状态机。这样既能用疗程卡锁定用户的长期复购,又不会让预付费卡破坏 LikeShop 原有订单履约链路的稳定性和财务可追溯性。