webhook invoice.paid 到达，INSERT provider_events；PK 冲突即重放，直接 200。
同 batch：INSERT transactions(renewal)，UPDATE plan_subscriptions 推 current_period_end 与 access_until。
source_updated_at 不比现状新则 outcome = ignored。
resolveEntitlement 重算，UPSERT entitlements 且 version + 1；UPDATE provider_events 置 processed_at / outcome。

🍎 Apple 退款

REFUND 通知按 originalTransactionId 找到 plan_subscriptions。
同 batch：status = revoked、revoked_at、ended_at；INSERT transactions(refund, 负额, refunds_transaction_id)。
重算 entitlements；若无其他来源则删行回落 free。

🪙 加密预付 3 个月

下单：INSERT crypto_orders(pending)，应付额 = cryptoExpectedAmount(标价, nonce)，30 分钟有效。
拉收款地址账本（provider_sync_cursors 断点），按 (收款地址, 付款地址, 金额) 命中 pending 单。
同 batch：crypto_orders → credited、INSERT transactions(purchase, tx hash)、新建或延长 plan_subscriptions(crypto)、重算 entitlements。

设计要点

为什么单独一个库营收账本要永久保留、要按 user_id 跨用户对账，且与 USER_DB 的生命周期不同（注销后账本仍在）。分库后计费迁移不影响登录路径。

为什么 status 与 revoked_at 并存status 是五态状态机；revoked_at 记撤销事实供审计。CHECK 把二者绑成同一事实，不会出现矛盾行（约定 7）。

provider_mode 必须进列生产 App 也会收到 Apple Sandbox 收据（TestFlight），同一部署环境里 live 与 sandbox 数据并存。

聚合每张表恰好属于一个聚合；kind=supporting 是辅助表

通用语言（术语定义）以 contexts/billing/CONTEXT.md 为准，这里不重复。

PlanCatalog

聚合根 plans + features + plan_features + prices

档位、权益键、每档额度与标价；运维 / 定价票通过迁移维护。

领域对象

PlanKey / FeatureKey / FREE_PLAN_KEY contexts/billing/src/domain/billing.types.ts

不变量与保证方

rank 全表唯一	数据库	plans.rank UNIQUE
free 存在且覆盖全部权益键	SQL	0001 种子；billingDb.integration.test.ts 守
flag 额度只能 0 / 1	数据库	plan_features_flag_value_insert / _update
加密价格无外部引用且以 USDC 计价，法币价格反之	数据库	prices CHECK
同一通道外部价格引用（同模式）只一行	数据库	prices_provider_ref

PlanSubscription

聚合根 plan_subscriptions + billing_customers

一条通道上的可续期访问及用户在各通道的客户身份。

领域对象

mapStripeStatus / mapAppleNotification contexts/billing/src/domain/providerStatus.ts
accessUntil / prorateCryptoUpgrade contexts/billing/src/domain/billingRules.ts

不变量与保证方

Apple originalTransactionId / Stripe subscription id（同模式）只绑一个用户、一行	数据库	plan_subscriptions_provider_ref
加密预付每用户每 provider_mode 至多一条有效订阅（过期 / 撤销 / 已结束的不占名额）	数据库	plan_subscriptions_one_crypto
档位 / 通道 / 模式与所引价格一致	数据库	plan_subscriptions 复合外键 → prices
当期末晚于期初；revoked 与 revoked_at 一致；加密不自动续费	数据库	plan_subscriptions CHECK
乱序事件不回退状态	SQL	处理器按 source_updated_at 条件写（后续票）
appAccountToken 小写 UUID 且唯一	数据库	billing_customers CHECK / UNIQUE

生命周期 · 付费订阅状态

activepast_duegraceexpiredrevoked

active→past_dueStripe past_due / unpaid；Apple DID_FAIL_TO_RENEW（无宽限）
active→graceApple DID_FAIL_TO_RENEW + GRACE_PERIOD
past_due→activeStripe invoice.paid；Apple DID_RENEW
grace→expiredApple GRACE_PERIOD_EXPIRED
active→expiredStripe canceled / incomplete_expired / paused；Apple EXPIRED；加密时段到期
active→revoked全额退款 / 拒付 / Apple REFUND · REVOKE

RevenueLedger

聚合根 transactions

只追加的营收账本；退款为负并指回原交易。

领域对象

TransactionKind contexts/billing/src/domain/billing.types.ts

不变量与保证方

同一通道凭证只入账一次	数据库	transactions_provider_txn_ref
退款 / 拒付为负、其余非负；金额为十进制	数据库	transactions CHECK
非 manual 通道必须带凭证	数据库	transactions CHECK

CryptoOrder

聚合根 crypto_orders

加密预付的待付单；链上转账是凭证。

领域对象

cryptoExpectedAmount / CRYPTO_ORDER_TTL_MINUTES contexts/billing/src/domain/billingRules.ts

不变量与保证方

pending 单 (收款地址, 付款地址, 应付额) 唯一	数据库	crypto_orders_pending_match
同一笔链上转账只认一张单	数据库	crypto_orders_paid_tx
到账三元组 / 入账两列跟随状态；过期晚于创建	数据库	crypto_orders CHECK
付款人是用户的 users.wallet_address	领域代码	加密下单用例（后续票）
转账真实到账	外部	HL L1 账本（action / info type 待核，ADR-0236）

生命周期 · 订单状态

pendingpaidcreditedunderpaidexpiredcanceled

pending→paid链上转账命中且金额足额
pending→underpaid命中但金额不足
paid→credited同 batch 写 transactions + plan_subscriptions + entitlements
pending→expired超过 expires_at + 10 分钟未到账
pending→canceled用户取消

ProviderEventInbox

辅助根 provider_events + provider_sync_cursors

通道事件去重 inbox 与拉取断点。

领域对象

ProviderEventChannel contexts/billing/src/domain/billing.types.ts

不变量与保证方

同一通道事件只处理一次	数据库	provider_events PRIMARY KEY (channel, event_id)
processed_at 与 outcome 同生同死；error 只在 failed	数据库	provider_events CHECK

Entitlement

聚合根 entitlements + entitlement_grants

当前生效档位的投影与人工授予。

领域对象

resolveEntitlement contexts/billing/src/domain/entitlement.ts
SessionEntitlement contexts/users/src/domain/user.types.ts — 经 SessionRpc 下发的契约

不变量与保证方

每用户至多一行权益	数据库	entitlements PRIMARY KEY (user_id)
多来源并存取 rank 最高、同档取截止最晚	领域代码	resolveEntitlement
version 为正且每次重算 +1	数据库	entitlements CHECK；递增由处理器条件写（后续票）
授予结束晚于开始、理由 ≤ 200 字	数据库	entitlement_grants CHECK

保证方：数据库约束 / 索引 / 触发器　SQL 仓储里的条件写 / batch　领域代码 domain 层规则　外部链上等外部权威

写路径矩阵哪个仓储方法写哪几张表

操作	原子性	billing_customers	crypto_orders	entitlement_grants	entitlements	features	plan_features	plan_subscriptions	plans	prices	provider_events	provider_sync_cursors	transactions
0001 schema 与目录种子 apps/server/migrations/billing/0001_billing_foundation.sql 本票无运行时仓储；通道处理器、对账与注销编排（BERTH-1925）后续实现，每条事件一个 db.batch。	batch					●	●		●

跨库 / 链上引用都没有外键，靠应用层维持

本库字段	对应	说明
`billing_customers.user_id`	USER_DB users.user_id	跨库无外键；注销编排归 BERTH-1925。
`plan_subscriptions.user_id`	USER_DB users.user_id	跨库无外键；注销编排归 BERTH-1925。
`transactions.user_id`	USER_DB users.user_id	跨库无外键；注销编排归 BERTH-1925。
`crypto_orders.user_id`	USER_DB users.user_id	跨库无外键；注销编排归 BERTH-1925。
`entitlement_grants.user_id`	USER_DB users.user_id	跨库无外键；注销编排归 BERTH-1925。
`entitlements.user_id`	USER_DB users.user_id	跨库无外键；注销编排归 BERTH-1925。
`crypto_orders.pay_from_address`	USER_DB users.wallet_address（下单时快照）	经 users /server 门读，不写 USER_DB SQL。
`crypto_orders.paid_tx_hash`	HL L1 USDC 转账	链上凭证；action 名与账本 info type 待核（ADR-0236）。
`plan_subscriptions.provider_ref`	Stripe subscription / Apple originalTransactionId	法币侧权威在通道，本库是投影。
`billing_customers.stripe_customer_id`	Stripe customer
`entitlements.version`	bot / strategy / social DO 的权益缓存	经 SessionRpc 下发，DO 按它失效缓存。

保留与清理

表	规则
`plans`	永久；下架只置 retired_at。
`features`	永久。
`plan_features`	永久，随定价迁移修改。
`prices`	永久；停售置 active = 0。
`billing_customers`	永久（对账需要）；注销处置归 BERTH-1925。
`plan_subscriptions`	永久；注销时 ended_at 置时。
`transactions`	永久，不改不删。
`crypto_orders`	expired / canceled 90 天后删除；其余永久。清理 cron 归后续票。
`provider_sync_cursors`	常驻，随数据源增删。
`provider_events`	received_at 起 1 年后删除。清理 cron 归后续票。
`entitlement_grants`	永久；撤销只置 revoked_at。
`entitlements`	随重算增删；注销时删行。

敏感度未列出的字段视为「内部」

字段	级别	说明
`billing_customers.stripe_email`	个人数据
`billing_customers.apple_app_account_token`	内部	只用于把 Apple 交易对到用户。
`crypto_orders.pay_from_address`	个人数据	链上公开，但与 user_id 关联后是个人数据。
`provider_events.payload_json`	个人数据	通道原始负载可能含邮箱 / 账单信息。
`transactions.amount`	个人数据

全部字段1 个迁移叠加后的最终结构 · 由迁移自动提取

0003 绿色迁移号表示该字段由后续迁移 ALTER TABLE 加入。点表名展开。

billing_customers计费客户6 字段 · 2 索引

用户在各通道上的客户身份；首次进入付费流程时建行。

聚合 PlanSubscription · 主键 (user_id) · 引入于 0001

字段	类型	约束	含义	迁移
PKuser_id	TEXT	PK	USER_DB users.user_id。	0001
UQstripe_customer_id	TEXT	UQ · CHECK(stripe_customer_id IS NULL OR length(stripe_customer_id) BETWEEN 1 AND 128)	Stripe customer id；首次 Checkout 前为 NULL。	0001
UQapple_app_account_token	TEXT	UQ · NOT NULL · CHECK(length(apple_app_account_token) = 36 AND substr(apple_app_account_token, 9, 1) = '-' AND substr(apple_app_account_token, 14, 1) = '-' AND substr(apple_app_account_token, 19, 1) = '-' AND substr(apple_app_account_token, 24, 1) = '-' AND replace(apple_app_account_token, '-', '') NOT GLOB '[^0-9a-f]' AND length(replace(apple_app_account_token, '-', '')) = 32)	我方生成的小写 UUID，交给 StoreKit 作 appAccountToken；Apple 通知原样带回，用来把交易对到 user_id。 SQL 注释：我方生成、交给 StoreKit 的 appAccountToken，Apple 通知原样带回，用来把交易对到 user_id。 Apple 要求 UUID 格式（此列不用 ULID）；存小写。	0001
stripe_email	TEXT	CHECK(stripe_email IS NULL OR length(stripe_email) BETWEEN 3 AND 320)	Stripe Checkout 收集的收据邮箱；只做对账展示。	0001
created_at	TEXT	NOT NULL	建行时刻。	0001
updated_at	TEXT	NOT NULL	最后修改时刻。	0001

索引 / 唯一约束

UNIQUE (约束) (apple_app_account_token)

UNIQUE (约束) (stripe_customer_id)

crypto_orders加密预付订单16 字段 · 3 索引

一次 HL L1 USDC 转账收款的待付单；命中链上转账即 paid，入账后 credited。

聚合 CryptoOrder · 主键 (order_id) · 引入于 0001

字段	类型	约束	含义	迁移
PKorder_id	TEXT	PK	ULID。	0001
user_id	TEXT	NOT NULL	下单用户。	0001
FKprice_id	TEXT	FK→prices.price_id · NOT NULL	所买价格（crypto 通道）。	0001
network	TEXT	NOT NULL · CHECK(network IN ('mainnet','testnet'))	HL 网络：staging 收 testnet，production 收 mainnet。	0001
asset	TEXT	NOT NULL · CHECK(asset IN ('USDC'))	v1 只收 USDC。	0001
pay_from_address	TEXT	NOT NULL · CHECK(length(pay_from_address) = 42 AND substr(pay_from_address, 1, 2) = '0x' AND substr(pay_from_address, 3) NOT GLOB '[^0-9a-f]')	付款地址 = 下单时 users.wallet_address（小写）。	0001
pay_to_address	TEXT	NOT NULL · CHECK(length(pay_to_address) = 42 AND substr(pay_to_address, 1, 2) = '0x' AND substr(pay_to_address, 3) NOT GLOB '[^0-9a-f]')	我方收款地址（小写）。	0001
expected_amount	TEXT	NOT NULL · CHECK(expected_amount GLOB '[0-9]' AND expected_amount NOT GLOB '[^0-9.]' AND expected_amount NOT GLOB '..' AND expected_amount NOT GLOB '*.')	cryptoExpectedAmount(标价, nonce)：标价 + 微量尾数，6 位小数。	0001
status	TEXT	NOT NULL · CHECK(status IN ('pending','paid','credited','underpaid','expired','canceled'))	pending → paid → credited；金额不足 underpaid；超时 expired；用户取消 canceled。	0001
created_at	TEXT	NOT NULL	下单时刻。	0001
expires_at	TEXT	NOT NULL	created_at + 30 分钟；到账容忍再 +10 分钟。	0001
paid_tx_hash	TEXT	CHECK(paid_tx_hash IS NULL OR ( length(paid_tx_hash) = 66 AND substr(paid_tx_hash, 1, 2) = '0x' AND substr(paid_tx_hash, 3) NOT GLOB '[^0-9a-f]' ))	命中的链上转账 hash（小写 0x+64 hex）；全表唯一。	0001
paid_amount	TEXT	CHECK(paid_amount IS NULL OR ( paid_amount GLOB '[0-9]' AND paid_amount NOT GLOB '[^0-9.]' AND paid_amount NOT GLOB '..' AND paid_amount NOT GLOB '*.' ))	实际到账金额。	0001
paid_at	TEXT		链上转账时刻。	0001
FKcredited_subscription_id	TEXT	FK→plan_subscriptions.subscription_id	入账后延长 / 新建的付费订阅。	0001
credited_at	TEXT		入账时刻。	0001

表级 CHECK

expires_at > created_at

(status IN ('paid','credited','underpaid')) = (paid_tx_hash IS NOT NULL AND paid_amount IS NOT NULL AND paid_at IS NOT NULL)

paid_tx_hash IS NOT NULL OR (paid_amount IS NULL AND paid_at IS NULL)

(status = 'credited') = (credited_subscription_id IS NOT NULL AND credited_at IS NOT NULL)

credited_subscription_id IS NOT NULL OR credited_at IS NULL

索引 / 唯一约束

UNIQUE crypto_orders_paid_tx (paid_tx_hash) WHERE paid_tx_hash IS NOT NULL

UNIQUE crypto_orders_pending_match (pay_to_address, pay_from_address, expected_amount) WHERE status = 'pending'

crypto_orders_status_expires (status, expires_at)

entitlement_grants运维授予9 字段 · 1 索引

不经通道的人工权益；永久保留，撤销只置 revoked_at。

聚合 Entitlement · 主键 (grant_id) · 引入于 0001

字段	类型	约束	含义	迁移
PKgrant_id	TEXT	PK	ULID。	0001
user_id	TEXT	NOT NULL	受益用户。	0001
FKplan_key	TEXT	FK→plans.plan_key · NOT NULL	授予档位。	0001
starts_at	TEXT	NOT NULL	生效时刻。	0001
ends_at	TEXT		结束时刻；NULL = 不限期。	0001
reason	TEXT	NOT NULL · CHECK(length(reason) BETWEEN 1 AND 200)	授予理由（≤ 200 字）。	0001
granted_by	TEXT	NOT NULL · CHECK(length(granted_by) BETWEEN 1 AND 128)	执行人（运维标识）。	0001
revoked_at	TEXT		撤销时刻；NULL = 未撤销。	0001
created_at	TEXT	NOT NULL	建行时刻。	0001

表级 CHECK

ends_at IS NULL OR ends_at > starts_at

索引 / 唯一约束

entitlement_grants_user_ends (user_id, ends_at)

entitlements权益7 字段

每用户当前生效档位的投影，由 resolveEntitlement 重算；没行 = free。

聚合 Entitlement · 主键 (user_id) · 引入于 0001

字段	类型	约束	含义	迁移
PKuser_id	TEXT	PK	用户（每人至多一行）。	0001
FKplan_key	TEXT	FK→plans.plan_key · NOT NULL	生效档位。	0001
source	TEXT	NOT NULL · CHECK(source IN ('subscription','grant'))	来自付费订阅还是授予。	0001
source_id	TEXT	NOT NULL	subscription_id 或 grant_id。	0001
access_until	TEXT		生效截止；NULL = 不限期授予。	0001
version	INTEGER	NOT NULL · CHECK(version > 0)	每次重算 +1；随 SessionRpc 下发，DO 据此失效缓存。	0001
computed_at	TEXT	NOT NULL	最后重算时刻。	0001

features权益键4 字段

可被限额或开关的功能清单；加一项 = 一条 INSERT + 每档一行 plan_features。

聚合 PlanCatalog · 主键 (feature_key) · 引入于 0001

字段	类型	约束	含义	迁移
PKfeature_key	TEXT	PK · CHECK(length(feature_key) BETWEEN 1 AND 64 AND feature_key NOT GLOB '[^a-z_.]')	点分键，如 `bot.routines.max`。	0001
kind	TEXT	NOT NULL · CHECK(kind IN ('limit','flag'))	limit = 数量上限；flag = 开关。	0001
enforced_by	TEXT	NOT NULL · CHECK(enforced_by IN ('bot','strategy','server','social'))	谁计数、谁拦截（billing 只下发档位，不集中计量）。 SQL 注释：计数与拦截归各执行方自己（ADR-0236 决策 13）；本库只下发档位。	0001
description	TEXT	NOT NULL · CHECK(length(description) BETWEEN 1 AND 200)	给运维与字典读的说明。	0001

plan_features档位额度3 字段 · 2 触发器

每档每个权益键的取值。free 行等于现有代码常量；pro / max 是占位，定价票再改。

聚合 PlanCatalog · 主键 (plan_key, feature_key) · 引入于 0001

字段	类型	约束	含义	迁移
PKFKplan_key	TEXT	PK · FK→plans.plan_key	档位。	0001
PKFKfeature_key	TEXT	PK · FK→features.feature_key	权益键。	0001
value	INTEGER	CHECK(value IS NULL OR value >= 0)	limit：数量，NULL = 不限；flag：0 / 1（触发器 plan_features_flag_value_* 守）。	0001

触发器

CREATE TRIGGER plan_features_flag_value_insert BEFORE INSERT ON plan_features
WHEN (SELECT kind FROM features WHERE feature_key = NEW.feature_key) = 'flag'
  AND (NEW.value IS NULL OR NEW.value NOT IN (0,1))
BEGIN
  SELECT RAISE(ABORT, 'plan_features: flag value must be 0 or 1');
END

CREATE TRIGGER plan_features_flag_value_update BEFORE UPDATE OF value, feature_key ON plan_features
WHEN (SELECT kind FROM features WHERE feature_key = NEW.feature_key) = 'flag'
  AND (NEW.value IS NULL OR NEW.value NOT IN (0,1))
BEGIN
  SELECT RAISE(ABORT, 'plan_features: flag value must be 0 or 1');
END

plan_subscriptions付费订阅18 字段 · 4 索引

一条通道上的一段可续期访问。法币侧是 Stripe / Apple 状态的投影，加密侧本库是权威。

聚合 PlanSubscription · 主键 (subscription_id) · 引入于 0001

字段	类型	约束	含义	迁移
PKsubscription_id	TEXT	PK	ULID。	0001
user_id	TEXT	NOT NULL	订阅者（USER_DB user_id）。	0001
FKplan_key	TEXT	FK→prices.plan_key · NOT NULL	当前档位；Apple DID_CHANGE_RENEWAL_PREF 改它。	0001
FKprice_id	TEXT	FK→prices.price_id · NOT NULL	当前价格；与 plan_key / channel / provider_mode 一致（复合外键）。	0001
FKchannel	TEXT	FK→prices.channel · NOT NULL · CHECK(channel IN ('stripe','apple','crypto'))	收款通道。	0001
provider_ref	TEXT	CHECK(provider_ref IS NULL OR length(provider_ref) BETWEEN 1 AND 128)	Stripe subscription id / Apple originalTransactionId；crypto 恒 NULL。	0001
FKprovider_mode	TEXT	FK→prices.provider_mode · NOT NULL · CHECK(provider_mode IN ('live','sandbox'))	live / sandbox。	0001
status	TEXT	NOT NULL · CHECK(status IN ('active','past_due','grace','expired','revoked'))	mapStripeStatus / mapAppleNotification 的结果；active / past_due / grace 仍给访问。	0001
auto_renew	INTEGER	NOT NULL · CHECK(auto_renew IN (0,1))	Stripe cancel_at_period_end / Apple DID_CHANGE_RENEWAL_STATUS；crypto 恒 0。	0001
current_period_start	TEXT	NOT NULL	当期开始。	0001
current_period_end	TEXT	NOT NULL	当期末；续订 / 加密续买向后推。	0001
access_until	TEXT	NOT NULL	访问截止 = accessUntil(当期末, grace_days)；权益判定只看它与 status。	0001
canceled_at	TEXT		用户关闭自动续费的时刻；期内仍有访问。	0001
ended_at	TEXT		订阅彻底结束的时刻（到期 / 撤销 / 注销编排置时）；NULL = 未结束。	0001
revoked_at	TEXT		全额退款 / 拒付 / Apple REVOKE 的时刻；与 status = revoked 同生同死。	0001
source_updated_at	TEXT	NOT NULL	通道侧该状态的时间；新事件不比它新则记 ignored，防乱序回退。	0001
created_at	TEXT	NOT NULL	建行时刻。	0001
updated_at	TEXT	NOT NULL	最后修改时刻。	0001

表级 CHECK

current_period_end > current_period_start

access_until >= current_period_start

(channel = 'crypto') = (provider_ref IS NULL)

channel <> 'crypto' OR auto_renew = 0

(status = 'revoked') = (revoked_at IS NOT NULL)

索引 / 唯一约束

plan_subscriptions_live_access_until (access_until) WHERE status IN ('active','past_due','grace')

UNIQUE plan_subscriptions_one_crypto (user_id, channel, provider_mode) WHERE channel = 'crypto' AND status NOT IN ('expired','revoked') AND ended_at IS NULL

UNIQUE plan_subscriptions_provider_ref (channel, provider_ref, provider_mode) WHERE provider_ref IS NOT NULL

plan_subscriptions_user_status (user_id, status)

plans档位7 字段 · 1 索引

会增长的档位参照表；rank 决定多来源并存时取哪档，grace_days 是法币扣款失败后保留访问的天数。种子 free / pro / max。

聚合 PlanCatalog · 主键 (plan_key) · 引入于 0001

字段	类型	约束	含义	迁移
PKplan_key	TEXT	PK · CHECK(length(plan_key) BETWEEN 1 AND 32 AND plan_key NOT GLOB '[^a-z_]')	档位键，小写字母与下划线；`free` 必须存在（没有 entitlements 行的用户即 free）。	0001
name	TEXT	NOT NULL · CHECK(length(name) BETWEEN 1 AND 40)	展示名。	0001
UQrank	INTEGER	UQ · NOT NULL · CHECK(rank >= 0)	越大越高，全表唯一；resolveEntitlement 据此取最高档。	0001
is_public	INTEGER	NOT NULL · DEFAULT 1 · CHECK(is_public IN (0,1))	1 = 出现在付费墙；0 = 只能运维授予。	0001
grace_days	INTEGER	NOT NULL · DEFAULT 0 · CHECK(grace_days >= 0)	法币通道扣款失败后 access_until 在当期末上加的天数；加密预付不用它（无宽限）。 SQL 注释：法币通道扣款失败后保留访问的天数；加密预付无宽限（ADR-0236 决策 9）。	0001
created_at	TEXT	NOT NULL	迁移 / 运维插入时刻。	0001
retired_at	TEXT		下架时刻；NULL = 在售。下架不影响已有订阅。	0001

索引 / 唯一约束

UNIQUE (约束) (rank)

种子行

[{"plan_key":"free","name":"Free","rank":0,"is_public":1,"grace_days":0,"created_at":"2026-11-03T04:33:31.640Z","retired_at":null},{"plan_key":"pro","name":"Pro","rank":10,"is_public":1,"grace_days":7,"created_at":"2026-11-03T04:33:31.640Z","retired_at":null},{"plan_key":"max","name":"Max","rank":20,"is_public":1,"grace_days":7,"created_at":"2026-11-03T04:33:31.640Z","retired_at":null}]

prices价格11 字段 · 2 索引

某档在某通道 / 模式下的一个标价；本票不种价格行。

聚合 PlanCatalog · 主键 (price_id) · 引入于 0001

字段	类型	约束	含义	迁移
PKprice_id	TEXT	PK	ULID。	0001
FKplan_key	TEXT	FK→plans.plan_key · NOT NULL	所售档位。	0001
channel	TEXT	NOT NULL · CHECK(channel IN ('stripe','apple','crypto'))	收款通道。	0001
provider_ref	TEXT	CHECK(provider_ref IS NULL OR length(provider_ref) BETWEEN 1 AND 128)	Stripe price id / Apple productId；crypto 恒 NULL。	0001
interval	TEXT	NOT NULL · CHECK(interval IN ('month','year'))	计费周期单位。	0001
interval_count	INTEGER	NOT NULL · DEFAULT 1 · CHECK(interval_count > 0)	周期数；加密预付 1 / 3 / 12 个月即 month × 1 / 3 / 12。	0001
amount	TEXT	NOT NULL · CHECK(amount GLOB '[0-9]' AND amount NOT GLOB '[^0-9.]' AND amount NOT GLOB '..' AND amount NOT GLOB '*.')	标价十进制 TEXT；加密订单应付额由 cryptoExpectedAmount 在此基础上加尾数。	0001
currency	TEXT	NOT NULL · CHECK(currency IN ('USD','USDC'))	法币 USD；加密 USDC（CHECK 绑定通道）。	0001
active	INTEGER	NOT NULL · DEFAULT 1 · CHECK(active IN (0,1))	0 = 不再售卖，已有订阅不受影响。	0001
provider_mode	TEXT	NOT NULL · CHECK(provider_mode IN ('live','sandbox'))	live / sandbox；Apple Sandbox 收据（TestFlight）落到 sandbox 价格。	0001
created_at	TEXT	NOT NULL	插入时刻。	0001

表级 CHECK

(channel = 'crypto') = (provider_ref IS NULL)

(channel = 'crypto') = (currency = 'USDC')

索引 / 唯一约束

UNIQUE (约束) (price_id, plan_key, channel, provider_mode)

UNIQUE prices_provider_ref (channel, provider_ref, provider_mode) WHERE provider_ref IS NOT NULL

provider_events通道事件9 字段 · 2 索引

所有通道事件的 inbox：先写这里再处理，PK 冲突即重放。保留 1 年。

聚合 ProviderEventInbox · 主键 (channel, event_id) · 引入于 0001

字段	类型	约束	含义	迁移
PKchannel	TEXT	PK · CHECK(channel IN ('stripe','apple','crypto','reconcile','manual'))	stripe / apple / crypto，或 reconcile（对账差异）/ manual（运维授予、注销）。	0001
PKevent_id	TEXT	PK · CHECK(length(event_id) BETWEEN 1 AND 128)	通道事件 id（Stripe event id / Apple notificationUUID / tx hash / 我方 ULID）。	0001
event_type	TEXT	NOT NULL · CHECK(length(event_type) BETWEEN 1 AND 128)	通道事件类型，如 invoice.paid、DID_RENEW、deactivate。	0001
payload_json	TEXT	NOT NULL	原始负载，只做审计，不查询。	0001
received_at	TEXT	NOT NULL	收到时刻。	0001
processed_at	TEXT		处理完成时刻；NULL = 待处理。	0001
outcome	TEXT	CHECK(outcome IN ('applied','ignored','failed'))	applied / ignored（不比现状新、或映射为 ignore）/ failed；与 processed_at 同生同死。	0001
error	TEXT	CHECK(error IS NULL OR length(error) <= 2000)	failed 时的错误摘要。	0001
subscription_id	TEXT		关联的付费订阅（不建外键：事件可能先于订阅到达）。	0001

表级 CHECK

(processed_at IS NULL) = (outcome IS NULL)

error IS NULL OR outcome = 'failed'

索引 / 唯一约束

provider_events_subscription (subscription_id, received_at)

provider_events_unprocessed (processed_at) WHERE processed_at IS NULL

provider_sync_cursors拉取断点3 字段

拉取型数据源（收款地址账本、每日对账）的断点，每源一行。

聚合 ProviderEventInbox · 主键 (source) · 引入于 0001

字段	类型	约束	含义	迁移
PKsource	TEXT	PK · CHECK(length(source) BETWEEN 1 AND 64)	数据源键，如 `hl-ledger:testnet:<收款地址>`（具体键由加密处理器票定）。	0001
cursor	TEXT	NOT NULL	上次处理到的位置（时间戳 / 游标，格式由源定）。	0001
updated_at	TEXT	NOT NULL	最后推进时刻。	0001

transactions营收账本13 字段 · 2 索引

一笔入账或退款；永久保留，不改不删。

聚合 RevenueLedger · 主键 (transaction_id) · 引入于 0001

字段	类型	约束	含义	迁移
PKtransaction_id	TEXT	PK	ULID。	0001
user_id	TEXT	NOT NULL	付款人（USER_DB user_id）。	0001
FKsubscription_id	TEXT	FK→plan_subscriptions.subscription_id	归属订阅；comp 等无订阅的为 NULL。	0001
channel	TEXT	NOT NULL · CHECK(channel IN ('stripe','apple','crypto','manual'))	stripe / apple / crypto，或运维手工 manual。	0001
provider_txn_ref	TEXT	CHECK(provider_txn_ref IS NULL OR length(provider_txn_ref) BETWEEN 1 AND 128)	Stripe invoice / charge id、Apple transactionId、链上 tx hash；manual 可空。同通道唯一。 SQL 注释：Stripe invoice / charge id、Apple transactionId、链上 tx hash；manual 可空。	0001
kind	TEXT	NOT NULL · CHECK(kind IN ('purchase','renewal','upgrade','refund','chargeback','comp'))	purchase 首购 · renewal 续订 · upgrade 升级 · refund 退款 · chargeback 拒付 · comp 补偿。	0001
amount	TEXT	NOT NULL · CHECK((amount GLOB '[0-9]' OR amount GLOB '-[0-9]') AND substr(amount, 2) NOT GLOB '[^0-9.]' AND amount NOT GLOB '..' AND amount NOT GLOB '.')	十进制 TEXT；退款 / 拒付为负，其余非负。部分退款只记账不撤销订阅。	0001
currency	TEXT	NOT NULL · CHECK(currency GLOB '[A-Z][A-Z][A-Z]' OR currency GLOB '[A-Z][A-Z][A-Z][A-Z]')	结算币种；Apple 可能是本地币种。 SQL 注释：法币币种随通道结算（Apple 可能是本地币种），故不收窄到 USD / USDC，只校 ISO 形状。	0001
period_start	TEXT		本笔覆盖的时段开始；退款等为 NULL。	0001
period_end	TEXT		本笔覆盖的时段结束。	0001
occurred_at	TEXT	NOT NULL	通道侧发生时刻。	0001
recorded_at	TEXT	NOT NULL	本库写入时刻。	0001
FKrefunds_transaction_id	TEXT	FK→transactions.transaction_id	退款 / 拒付指回的原交易。	0001

表级 CHECK

channel = 'manual' OR provider_txn_ref IS NOT NULL

(kind IN ('refund','chargeback')) = (amount GLOB '-*')

refunds_transaction_id IS NULL OR kind IN ('refund','chargeback')

period_start IS NULL OR period_end IS NULL OR period_end > period_start

索引 / 唯一约束

UNIQUE transactions_provider_txn_ref (channel, provider_txn_ref) WHERE provider_txn_ref IS NOT NULL

transactions_user_occurred (user_id, occurred_at DESC)

由 pnpm schema-docs build billing-db 生成 · 结构来源 apps/server/migrations/billing · 语义来源 docs/data/billing-db/annotations.json · 指纹 sha256:e091c2144f7b040c

BILLING_DB

板块颜色贯穿全文

目录

付费订阅

账本与加密收款

通道事件

权益

全库约定

业务流程跟着流程看表怎么变

💳 Stripe 续订扣款成功

🍎 Apple 退款

🪙 加密预付 3 个月

设计要点

聚合每张表恰好属于一个聚合；kind=supporting 是辅助表

PlanCatalog

PlanSubscription

RevenueLedger

CryptoOrder

ProviderEventInbox

Entitlement

写路径矩阵哪个仓储方法写哪几张表

跨库 / 链上引用都没有外键，靠应用层维持

保留与清理

敏感度未列出的字段视为「内部」

全部字段1 个迁移叠加后的最终结构 · 由迁移自动提取

关系图实线 = 数据库外键（乌鸦脚在「多」端）· 虚线 = 逻辑关联 / 流程 · 点表框跳到字段