メンバーウォレット

メンバーウォレットは、メンバーがカフェサービスを前払いできる金銭残高システムです。個別のセッションごとに現金で支払う代わりに、メンバーはウォレットに資金を入金し、PCやコンソールの利用や商品の注文時にシステムが自動的に残高から差し引きます。

クレジットベースのアーキテクチャ

ウォレットは単一の残高ではなく、クレジットシステムを使用しています。メンバーのウォレットに資金が追加されるたびに、システムは新しいウォレットクレジットを作成します。各クレジットエントリは独自の残高、ソース、有効期限、デバイス制限を持つ個別のレコードです。この設計により以下が提供されます。

各残高単位の出所の完全なトレーサビリティ。
クレジットエントリごとの独立した有効期限。
デバイス固有の制限（一部のクレジットはPCでのみ、他はコンソールでのみ使用可能）。
有料資金とプロモーションボーナスの明確な分離。

メンバーのウォレット残高合計は、アクティブなクレジットエントリ全体の残高の合計です。

クレジットタイプ

各ウォレットクレジットには、資金がシステムに入った方法を識別するクレジットタイプがあります。

クレジットタイプ	説明
有料	メンバーがこの資金を支払いました（現金、カード、その他の支払い方法）。金額ベースのキャンペーンパッケージ購入時に作成されます。
ボーナス	パッケージ購入の一部として付与されたプロモーション資金。たとえば「100分分を支払って20分相当のクレジットボーナスを獲得」。
手動	キャッシャーまたは管理者が手動でロードしました。好意的なクレジットや特別な取り決めに使用されます。
修正	メンバーの残高のエラーを修正するための管理的調整。
移行	データ移行中にレガシーシステムからインポートされた資金。
返金取消	以前発行された返金が取り消された際に復元された資金。

クレジットタイプはクレジット作成時に設定され、後から変更できません。永続的な監査証跡として機能します。

クレジットのステータス

各ウォレットクレジットはステータスで追跡されるライフサイクルを経ます。

アクティブ: クレジットに残高があり、有効期限が切れていません。このクレジットから資金を消費できます。
期限切れ: クレジットの有効期限日が過ぎています。残高は使用できなくなります。
消費済み: 通常の消費により残高がゼロに達しました。
キャンセル: 管理者がクレジットを手動でキャンセルし、残高が無効化されました。

ウォレットの消費

メンバーのウォレットに課金される（セッション時間、注文、その他の課金イベント）と、システムは特定のクレジットエントリにリンクし、差し引かれた正確な金額を記録するウォレット消費レコードを作成します。

各消費レコードには差し引きのトリガーを識別するコンテキストが含まれます。

コンテキスト	説明
セッション利用	セッション使用時間の支払いに消費された資金。セッションの実行中にウォレットから差し引きます。
ウォレット支払い	ウォレットからの直接支払い（たとえばメンバーがウォレット残高で商品注文を支払う場合）。
注文	カフェカウンターでの商品注文またはメンバーのPCへの配達の支払いに消費された資金。
返金	返金処理時に作成される負の調整。資金をクレジットエントリに戻すために消費を減額します。

各消費レコードは原因となった特定のセッション、注文、取引にリンクされ、完全な監査追跡を可能にします。

残高ログ

クレジットレベルの消費レコードに加えて、システムはメンバーの全体的なウォレット残高を変更するすべてのイベントを記録するメンバー残高ログを維持します。

イベントタイプ	説明
`load`	ウォレットに資金が追加されました（新しいクレジットエントリの作成または既存エントリへの追加）。
`spend`	ウォレットから資金が消費されました（セッション支払い、注文支払い）。
`refund`	ウォレットに資金が返却されました（注文返金、セッション返金）。
`adjustment`	残高に管理的な変更が行われました（修正、償却）。

各残高ログエントリは変更金額と結果の残高を記録するため、ログを時系列で読むことで任意の時点でのメンバーの残高を再構築できます。

デバイス制限

各ウォレットクレジットには、どのタイプのデバイスがクレジットから消費できるかを制御するデバイス制限があります。

制限	意味
クライアント	クライアントPCで使用可能。明示的に制限されない限りコンソールでも使用可能。
コンソール	ゲーミングコンソールで使用可能。明示的に制限されない限りPCでも使用可能。
PCのみ	クライアントPCでのみ使用可能。コンソールセッションでは消費できません。
コンソールのみ	ゲーミングコンソールでのみ使用可能。PCセッションでは消費できません。
両方	デバイスタイプの制限なし。デフォルトです。

システムがメンバーのウォレットから差し引く必要がある場合、デバイス制限で利用可能なクレジットをフィルタリングし、対象のクレジットのみが課金されることを確保します。

ウォレットカテゴリとクロスカテゴリ利用

ウォレットクレジットにはウォレットカテゴリ（たとえば「ゲーミング」「一般」）をタグ付けできます。これにより特定のコンテキストでのみ使用できる分離された残高プールを作成できます。

各クレジットのクロスカテゴリ利用オプションは、指定されたカテゴリ外で資金を使用できるかどうかを制御します。

無効（デフォルト）の場合、クレジットは自身のカテゴリでのみ消費できます。
有効の場合、クレジットは他のカテゴリの取引でも消費できます。

ウォレットカテゴリが割り当てられていないクレジットは汎用クレジットとして扱われ、カテゴリに関係なく任意の取引で消費できます。

チャージの仕組み

ウォレット資金はいくつかの方法で追加できます。

キャンペーンパッケージ購入: メンバーがキャンペーンから金額ベースのパッケージを購入すると、パッケージ定義に基づいてウォレットクレジットが自動的に作成されます。1回のパッケージ購入で複数のクレジットが作成される場合があります（有料分とボーナス分で各1つ）。
手動ロード: キャッシャーがメンバー詳細パネルからメンバーのウォレットに手動で資金を追加できます。「手動」クレジットタイプのクレジットエントリが作成されます。
移行: システムセットアップ時に、以前のシステムからの既存残高を「移行」クレジットタイプのクレジットエントリとしてインポートできます。

セッション中のウォレット消費の仕組み

ウォレット残高を持つメンバーがセッションを開始すると、システムはウォレットからセッションの支払いを自動的に行えます。

セッション料金エンジンがアクティブな料金スロットと適用されるティア割引に基づいて分単位のコストを計算します。
セッションの実行中、システムはメンバーの対象ウォレットクレジットから蓄積された費用を定期的に差し引きます。
クレジットは有効期限日の早い順に消費され（最も早く期限切れになるクレジットを先に使用）、有効期限による無駄を最小化します。
セッション終了前にウォレット残高が枯渇した場合、残りの費用はセッション終了時に現金支払いとして請求されます。
各差し引きは「セッション利用」エントリとしてセッションにリンクされた消費レコードを作成します。