組織のクレジット台帳
利用量の測り方を選び、組織で共有するクレジットを安全に付与、消費、失効、返却します。
スターターのコミット
2a1a04aで検証済みです。
クレジットは任意の料金設計であり、すべての機能に必要なものではありません。プラン内で操作ごとの原価が異なる場合や、購入済みの利用量を繰り越す場合に使います。顧客がある操作を利用できるかだけを判断するなら、単純なエンタイトルメントまたは上限を使います。
決めること
| 問い | 同梱の選択 | 代替案 |
|---|---|---|
| クレジットの所有者 | 組織。メンバーは一つの残高を共有 | 組織の台帳を保ったまま、メンバーごとの予算を追加する |
| 残高の保存方法 | 追記専用の記録 | 監査可能性と再実行時の保証も置き換えない限り、書き換え可能なカウンターにしない |
| 最初に消費する付与分 | 最も早く期限切れになるもの | 失効のテストを追加してから、割り当て規則を変更する |
| 後続処理が失敗した場合 | 元の消費にひも付く返却行を追加 | 契約上、失敗した処理も課金対象にする場合だけ、消費を残す |
クレジットは組織に属し、メンバーは一つの残高を共有します。台帳は追記専用です。行を更新・削除せず、SQL を直接実行して src/services/credit.ts を迂回しないでください。
付与は、一意な取引番号と任意の有効期限を持つ正数の行です。消費処理は、組織単位のアドバイザリーロック内で台帳全体を再計算し、期限が近い付与分から使います。利用可能残高が十分な場合だけ負数の行を追加します。一回の消費が :part:n という複数行に分かれても、API は一つの論理取引としてまとめます。返却は、元の消費にひも付く補償行です。
balance_after は行を追加した時点の会計上の総額であり、期限切れを除いた現在の利用可能額とは限りません。組織の集計から available、granted、consumed、expired を取得してください。
金銭やクレジットの変更には、安定した業務上の冪等性キーが必須です。同じ呼び出しを二回行っても、台帳への反映は一度だけです。サブスクリプション更新と Stripe の履行処理にも決定的な番号を使い、管理者による付与には上限と監査があります。
有料機能を追加するときは、設定から費用を計算し、エンタイトルメントを確認し、クレジットサービスで消費します。その機能の行に元取引を保存し、後続処理が失敗したら返却行を追加します。
二つの消費を同時に実行しても残高を超えず、同じ業務キーによる再試行が一度だけ作用し、期限切れの付与分が利用可能残高から除外され、UI が内部の分割行ではなく論理取引を表示し、失敗したタスクに監査可能な補償返却が残れば完成です。プランと権限で利用可否と上限を、Stripe 課金で定期付与の起点を確認してください。