架构与系统设计 / 系统课时
租户订阅模型
租户订阅模型
本课建立租户订阅的核心数据结构,用一条当前订阅记录管理周期和续费策略,再用事件历史保存试用、激活、变更、取消与到期过程。
学习目标
- 设计订阅周期、试用期和自动续费字段
- 理解订阅状态的合法迁移与生效时点
- 使用事件表和并发控制保留完整变更历史
当前订阅与历史事件分开保存
租户订阅表回答“这个租户现在订阅什么、处于什么状态、当前周期何时结束”。订阅事件表回答“它为什么变成现在这样”。前者适合在线鉴权与额度计算,后者适合审计、账单追踪和问题排查。
一条当前记录通常引用已发布的套餐版本,而不是套餐主表。这样即使运营人员发布了新价格,租户仍能按签约时的版本继续执行。套餐升级、降级和续费都追加事件,不覆盖历史原因。

建立订阅与事件表
下面脚本采用“一租户一条当前订阅”的简化模型。version 用于乐观锁,next_plan_version_id 用于预约下个周期生效的降级或套餐切换。
DROP TABLE IF EXISTS saas_subscription_event;
DROP TABLE IF EXISTS saas_tenant_subscription;
CREATE TABLE saas_tenant_subscription (
id BIGINT PRIMARY KEY,
tenant_id BIGINT NOT NULL UNIQUE,
plan_version_id BIGINT NOT NULL,
next_plan_version_id BIGINT NULL,
status VARCHAR(20) NOT NULL,
start_at DATETIME NOT NULL,
current_period_start DATETIME NOT NULL,
current_period_end DATETIME NOT NULL,
trial_end_at DATETIME NULL,
auto_renew TINYINT(1) NOT NULL DEFAULT 1,
cancel_at_period_end TINYINT(1) NOT NULL DEFAULT 0,
version INT NOT NULL DEFAULT 0,
created_at DATETIME NOT NULL,
updated_at DATETIME NOT NULL
);
CREATE TABLE saas_subscription_event (
id BIGINT PRIMARY KEY,
subscription_id BIGINT NOT NULL,
event_type VARCHAR(40) NOT NULL,
from_status VARCHAR(20) NULL,
to_status VARCHAR(20) NULL,
effective_at DATETIME NOT NULL,
detail_json JSON NULL,
created_at DATETIME NOT NULL,
KEY idx_subscription_time (subscription_id, effective_at),
CONSTRAINT fk_event_subscription FOREIGN KEY (subscription_id)
REFERENCES saas_tenant_subscription(id)
);
INSERT INTO saas_tenant_subscription (
id, tenant_id, plan_version_id, status,
start_at, current_period_start, current_period_end,
trial_end_at, auto_renew, cancel_at_period_end,
version, created_at, updated_at
) VALUES (
2001, 3001, 1001, 'TRIALING',
'2026-08-01 00:00:00', '2026-08-01 00:00:00',
'2026-09-01 00:00:00', '2026-08-08 00:00:00',
1, 0, 0, '2026-08-01 00:00:00', '2026-08-01 00:00:00'
);
INSERT INTO saas_subscription_event VALUES (
9001, 2001, 'SUBSCRIPTION_CREATED', NULL, 'TRIALING',
'2026-08-01 00:00:00',
JSON_OBJECT('source', 'self_service'),
'2026-08-01 00:00:00'
);
START TRANSACTION;
UPDATE saas_tenant_subscription
SET status = 'ACTIVE',
version = version + 1,
updated_at = '2026-08-08 00:00:00'
WHERE id = 2001
AND status = 'TRIALING'
AND version = 0;
INSERT INTO saas_subscription_event VALUES (
9002, 2001, 'TRIAL_CONVERTED', 'TRIALING', 'ACTIVE',
'2026-08-08 00:00:00',
JSON_OBJECT('paymentStatus', 'PAID'),
'2026-08-08 00:00:00'
);
COMMIT;
SELECT tenant_id, plan_version_id, status,
current_period_end, auto_renew, version
FROM saas_tenant_subscription
WHERE id = 2001;预期结果:
tenant_id | plan_version_id | status | current_period_end | auto_renew | version
3001 | 1001 | ACTIVE | 2026-09-01 00:00:00 | 1 | 1示例表示租户在试用结束后完成付款,订阅从 TRIALING 转为 ACTIVE,并保留一条 TRIAL_CONVERTED 事件。生产代码还应检查更新影响行数;若为 0,说明状态或版本已被其他请求修改,不能继续写入成功事件。
定义清晰的状态迁移
TRIALING 表示试用有效但尚未完成正式订阅;付款成功后进入 ACTIVE。续费扣款失败可进入 PAST_DUE,在宽限期内补款后回到 ACTIVE,宽限期结束则进入 EXPIRED。
用户主动取消时,不一定立即改成 CANCELED。常见做法是先设置 cancel_at_period_end=1,继续提供服务到当前周期结束,再由周期任务切换状态。立即停用只适用于退款、风控或管理员强制终止等明确场景。
处理续费与套餐变更
自动续费成功后,把 current_period_start 推进到旧的结束时间,再按计费周期计算新的 current_period_end,同时写入 RENEWED 事件。扣款、周期推进和事件记录应处于同一事务或可靠消息流程中,避免已收费但订阅周期未延长。
升级通常立即生效,可切换 plan_version_id 并记录补差价结果;降级通常在下个周期生效,只写入 next_plan_version_id。到达周期边界后,再把预约版本替换为当前版本并清空预约字段。每次变更都应记录操作者、来源、旧版本、新版本和生效时间。
保证并发与可追溯性
续费任务、支付回调和人工操作可能同时修改同一订阅。可以使用数据库行锁,也可以像示例一样通过 version 做乐观锁;无论采用哪种方式,都必须让状态更新与事件写入保持一致。
事件表应只追加、不修改。detail_json 适合保存渠道单号、失败原因或变更来源,但常用检索字段仍应单独建列和索引。定时任务可按 status 与 current_period_end 建联合索引,批量扫描即将续费、待取消或已过宽限期的订阅。
验收检查
至少验证试用转正式、自动续费成功、续费失败进入宽限期、周期末取消和预约降级五条路径。每次状态或套餐版本变化,都应能在事件表中找到对应记录,并能还原生效时间和触发原因。
本课总结
- 当前订阅表保存可直接判断的实时状态,事件表保存不可变的变更轨迹
- 试用、续费、取消和过期必须通过受控状态迁移完成
- 套餐变更要明确立即生效还是周期末生效,并用锁或版本号处理并发
下一课预告
下一课将基于订阅状态和套餐权益实现资源配额校验,处理额度占用、释放、超限提示与并发一致性。