架构与系统设计 / 系统课时

租户订阅模型

租户订阅模型

本课建立租户订阅的核心数据结构,用一条当前订阅记录管理周期和续费策略,再用事件历史保存试用、激活、变更、取消与到期过程。

学习目标

  • 设计订阅周期、试用期和自动续费字段
  • 理解订阅状态的合法迁移与生效时点
  • 使用事件表和并发控制保留完整变更历史

当前订阅与历史事件分开保存

租户订阅表回答“这个租户现在订阅什么、处于什么状态、当前周期何时结束”。订阅事件表回答“它为什么变成现在这样”。前者适合在线鉴权与额度计算,后者适合审计、账单追踪和问题排查。

一条当前记录通常引用已发布的套餐版本,而不是套餐主表。这样即使运营人员发布了新价格,租户仍能按签约时的版本继续执行。套餐升级、降级和续费都追加事件,不覆盖历史原因。

租户订阅状态与周期迁移

建立订阅与事件表

下面脚本采用“一租户一条当前订阅”的简化模型。version 用于乐观锁,next_plan_version_id 用于预约下个周期生效的降级或套餐切换。

sql
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;

预期结果:

text
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 建联合索引,批量扫描即将续费、待取消或已过宽限期的订阅。

验收检查

至少验证试用转正式、自动续费成功、续费失败进入宽限期、周期末取消和预约降级五条路径。每次状态或套餐版本变化,都应能在事件表中找到对应记录,并能还原生效时间和触发原因。

本课总结

  • 当前订阅表保存可直接判断的实时状态,事件表保存不可变的变更轨迹
  • 试用、续费、取消和过期必须通过受控状态迁移完成
  • 套餐变更要明确立即生效还是周期末生效,并用锁或版本号处理并发

下一课预告

下一课将基于订阅状态和套餐权益实现资源配额校验,处理额度占用、释放、超限提示与并发一致性。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

租户订阅模型

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通