# 回数券 ## 概要 **回数券**は、複数回分の宿泊・利用をまとめて先払いで購入してもらうための商品です。管理画面の **回数券** メニュー（`/ticket-books`）から、施設ごとに「〇回綴り・¥〇〇」や「〇時間分・¥〇〇」という回数券商品を作成・管理できます。 回数券はプロモーション機能の一種（`grantReservations` タイプ）で、**単位（回数 / 時間）** を選んで発行します。 - **回数**単位: 「予約1件＝1枚消費」。ホテル1泊やタイムスロット1件など、1予約あたり定額の商品向け - **時間**単位: 「予約の所要時間分を消費」。時間貸し（会議室・シェアオフィス）で、予約1件あたりの利用時間が可変な商品向け 作成した回数券は、ゲストが会員アプリから購入すると、有効残高として発行されます。ゲストは対象プランを予約する際にその残高を消費して代金0円で予約できます。 > **対応状況（2026-08）**: 商品の作成・管理（このページ）、会員アプリからの購入、予約時の充当、キャンセル時の復元、失効前のメール通知まで一連の業務フローが実装されています。 --- ## 詳細機能 ## 機能1: 回数券の作成 1. 管理画面の左メニューから **回数券** を開く 2. **回数券を作成** ボタンをクリック 3. 以下の項目を入力する | 項目 | 説明 | |------|------| | **名前** | 回数券の商品名（例: 「10泊綴りチケット」「50時間パス」）。一覧画面や購入時に表示されます | | **説明（任意）** | 補足説明。空欄可 | | **単位** | **回数** or **時間**。回数=1予約で1枚消費、時間=予約の所要分を消費（詳細は[機能7](#機能7-単位回数--時間)を参照） | | **綴り枚数 / 時間数** | 単位が「回数」なら1冊あたりの利用回数、「時間」なら1冊あたりの利用可能時間数（いずれも1以上の整数） | | **販売価格（円）** | 冊全体の販売価格（0以上の整数、税込・税別の扱いは施設の運用に準拠） | | **有効期間** | 購入日を起点とした失効までの期間。**1ヶ月（30日） / 3ヶ月（90日） / 6ヶ月 / 1年 / 2年** から選択。短期（30日/90日）は日数固定、6ヶ月以降は月末換算 | | **購入上限（枚数）** | 1人のゲストが購入できる上限数。**必ず1以上が保存され、無制限にはできません。** 新規作成時は「1」が入った状態で開き、空欄や0のまま保存しても「1人1枚」になります（詳細は[機能4](#機能4-購入上限の期間-max_per_user_window)を参照） | | **購入上限の期間** | 上記の上限をリセットする周期。**通算（リセットなし） / 暦年ごと / 暦月ごと / 365日ごと / 30日ごと** から選択（詳細は[機能4](#機能4-購入上限の期間-max_per_user_window)を参照） | | **対象プラン** | この回数券が使える予約プランを絞り込み。未選択で施設の全プラン対象。指定した場合はそのプランのみで充当可能（詳細は[機能5](#機能5-対象プラン)を参照） | | **販売中にする** | ONにすると購入可能な状態になります。OFFのままだと下書き（非公開）として保存されます | 4. **保存** をクリックすると回数券が作成されます ## 機能2: 回数券の編集 1. 回数券一覧から編集したい回数券のカードをタップする 2. **編集** タブで各項目を編集し、**保存** をクリックする > **綴り枚数・販売価格・有効期間を編集しても、既に販売済み（購入済み）の回数券には影響しません。** 各購入は購入した時点の条件（枚数・価格・有効期間）で確定し、Stripeの決済データにスナップショットとして保持されます。編集は「これから購入する人向けの条件」を変更するものです。 > **販売済み回数券は「単位」を変更できません。** 一度でも購入が発生した回数券商品は、単位セレクタが自動的にロックされ、「回数」↔「時間」の変更が禁止されます（既存購入者の残高集計と新規購入者の残高集計が別単位になると整合しなくなるため）。変更したい場合は、その商品を **下書き** に戻して販売停止し、新しい単位で別の商品を作り直してください。 > **削除済みの対象プラン**: 対象プランに紐づけた予約プランが後から削除された場合、編集画面の対象プラン欄にそのプランが赤色の「(削除済みプラン)」chip として表示されます。× ボタンでクリアしてください。放置すると、その回数券は「削除済みプランのみ対象」として扱われ、どの予約でも充当できなくなります。 ## 機能3: 一覧画面の見方 回数券一覧には、作成済みの回数券がカード形式で表示されます。 - **名前**と、「**{枚数}枚綴り / ¥{価格}**」というサマリーが表示されます - 右側のバッジで状態がわかります - **販売中**: ゲストが購入できる状態 - **下書き**: 非公開（購入不可）の状態 - カードをタップすると編集画面に移動します 回数券を停止したい場合は、編集画面で **販売中にする** のチェックを外して保存してください。**現在の管理画面には回数券を削除するボタンはありません。** 販売を止めたい場合は下書き状態（非公開）に切り替えて運用してください。 ## 機能4: 購入上限の期間 (max_per_user_window) **購入上限（枚数）** と **購入上限の期間** は、1人のゲストがこの回数券を何回まで購入できるかを制御する組み合わせ設定です。 | 項目 | 意味 | |------|------| | **購入上限（枚数）** | 1人のゲストが（下記の周期内で）購入できる上限回数。1以上の整数のみで、無制限は選べません | | **購入上限の期間** | 上限回数をカウントする際のリセット周期（起点）。**通算（リセットなし） / 暦年ごと（毎年1月1日起点） / 暦月ごと（毎月1日起点） / 365日ごと（直近365日のローリングウィンドウ） / 30日ごと（直近30日のローリングウィンドウ）** | 上限に達したゲストがもう一度購入しようとすると、購入手続きが拒否されます。 > **重要な注意（既定値の挙動）**: **回数券に「無制限」はありません。** 「購入上限（枚数）」を空欄や0のまま保存しても、上限1回として保存されます（既定の周期は「通算（リセットなし）」なので、**1人のゲストが生涯に購入できるのは1回だけ**）。この欄を触らずに作成した回数券もこの状態です。複数回購入できるようにしたい場合は、「購入上限（枚数）」に希望する回数を明示的に入力し、必要なら「購入上限の期間」も併せて設定してください。 > > 新規作成フォームは既定値の「1」が入った状態で開きます（保存される値をそのまま表示するため）。 ## 機能5: 対象プラン 「この回数券はどの予約プランで使えるか」を絞り込む設定です。編集画面の **対象プラン** 欄で MultiSelect UI から選択します。 - **未指定（デフォルト）**: 施設内の**全予約プラン**で充当可能 - **1つ以上を指定**: **選択した予約プランのみ**で充当可能（他のプランでは充当されず、通常決済になります） 選択済みプランは青色の chip として表示され、× ボタンで個別に外せます。検索窓でプラン名の絞込も可能です。 > **メンバーシップ専用プラン（¥0）は選択肢に出ません** — 会員特典で無料化される予約に回数券を充当するのは意味がないため、対象候補は有料の予約プランのみに絞られます。 ## 機能6: 販売・利用状況（SalesTab） 回数券の詳細画面には、**編集** タブと並んで **販売・利用状況** タブがあります。この回数券の販売実績と、購入者ごとの利用状況を集計表示します。 - **サマリー**（4カード）: 販売数 / 発行枚数（時間の場合は発行時間） / 利用 / 残り - **購入一覧**: 各購入について - 購入者メールアドレスと購入日 - 「残 / 発行」の残高 - **単位が「回数」**: ◯ゲージ（塗り＝残り、白抜き＝利用済み） - **単位が「時間」**: 残量バー（brand accent 色で残時間を可視化） - 「利用 N · 残り M」の内訳表示 失効・キャンセル済みの credit の残高は「残り」から自動的に除外されるので、常に**利用可能な**残高が表示されます。 ## 機能7: 単位（回数 / 時間） 回数券作成時に選ぶ **単位** は、消費のカウント方法を決めます。 | 単位 | 消費モデル | 主な用途 | |------|-----------|---------| | **回数** | 1予約 = 1枚消費 | 宿泊1泊、タイムスロット予約、貸切枠など「1回いくら」商品 | | **時間** | 1予約 = 予約の所要時間分を消費（例: 3時間予約なら3時間分） | 会議室・シェアオフィスの時間貸し | **時間**単位の場合、予約の所要時間が回数券の残時間を超える場合は充当できません（回数券は分割せず、1本の回数券で1予約を賄えないなら通常決済扱い）。ゲスト側のブッキング画面では、STEP3（確定画面）でその予約が回数券で賄えるかどうかが自動判定されます。 ## 機能8: 権限 回数券の作成・編集・閲覧には、**施設オーナー以上**の権限が必要です。 | 権限レベル | 回数券へのアクセス | |-----------|-------------------| | Organization Owner | 自組織配下の全施設の回数券を管理可能 | | Facility Owner | 自施設の回数券のみ管理可能 | | Facility Member | アクセス不可 | --- ## 機能9: 失効前のメール通知 回数券の残高（credit）には有効期限があります。ゲストが失効に気づかず使い忘れることがないよう、失効が近づくと自動的にメールで通知します。 | タイミング | 件名 | |-----------|------| | 失効30日前 | 【失効予告】回数券の有効期限まで 30 日を切りました | | 失効7日前 | 【まもなく失効】回数券の有効期限が近づいています | | 失効当日 | 【本日失効】回数券の有効期限のお知らせ | - 毎日 **朝7時（JST）** に自動チェックが走り、該当するゲストの登録メールアドレス宛に送信されます - 1人のゲストが同じ日に複数の回数券（credit）の期限を迎える場合、1通のメールにまとめて送られます - メール本文には、失効日・残数（回数券は「残N回」、時間単位は「残N時間」）・会員ページへのリンクが記載されます - 同じ回数券・同じ閾値（30日前/7日前/当日）で二重に送信されることはありません - **この通知はあくまで事前案内であり、残高そのものを変更したり失効を早めたりはしません。** 失効判定は予約充当時・残高照会時にその都度行われます - 現バージョンでは、通知メールの文面は**日本語固定**です（ゲストの表示言語設定（英語等）に関わらず日本語で届きます） --- ## 業務フローの全体像 回数券に関わる一連の流れは、次のステップで構成されます。**すべて実装済み** です。 1. **① 商品作成（このページ）**: 管理者が回数券メニューで単位・枚数（時間数）・価格・有効期間・購入上限・対象プランを設定して商品を作成 2. **② ゲストによる購入（会員アプリ）**: ゲストが会員アプリ（`member.unlockos.io`）のホーム画面、またはマイページから遷移する回数券ページ（`/{施設スラッグ}/tickets`）で該当商品を選び、Stripe 決済で購入。決済完了後、会員の残高として発行されます 3. **③ 予約時の充当（Booking アプリ）**: 有効な回数券残高を持つゲストが対象プランを予約する際、ブッキング画面 STEP3 に「**回数券で充当**」トグルが表示されます。選択すると1回分（または所要時間分）を消費して代金0円の予約として成立します。オプション商品（追加サービス）は回数券の対象外で、選択すると別途課金されます 4. **④ キャンセル時の扱い**: 回数券で作成した予約をキャンセルした場合、**チェックイン7日前まで**にキャンセルすれば残高が元に戻り、再度別の予約に使えます。チェックイン7日前を過ぎてのキャンセルは残高が失効（消費されたまま）します 5. **⑤ 失効前の通知**: 失効30日前・7日前・当日の3段階で、ゲストにメールでお知らせします（詳細は[機能9](#機能9-失効前のメール通知)を参照） --- ## よくある質問 ### Q: 作成した回数券を今すぐゲストに販売できますか？ はい。**販売中** にした商品は、ゲストが会員アプリ（`member.unlockos.io`）のホーム画面や回数券ページから購入できます。決済完了後、会員の残高として自動的に発行され、対象プランの予約時に充当できます。 ### Q: 単位を「回数」で作った回数券を、後から「時間」に変えられますか？ **販売実績（購入者）がまだ0件なら変更可能**です。1件でも購入が発生した回数券は、単位セレクタが自動でロックされ変更できなくなります（既存購入者の残高が「N回」で発行されているのに新規購入者が「N時間」になると、販売集計や残高比較が壊れるため）。 単位を切り替えたい場合は、その商品を **下書き** にして販売停止し、新しい単位で別商品として作成してください。 ### Q: 対象プランを指定した場合、他のプランでは充当できませんか？ はい。対象プランを1つ以上指定した回数券は、その **選択したプランでのみ** 充当されます。他のプランを予約する際は「回数券で充当」トグルが表示されず、通常決済になります。全プラン対象にしたい場合は対象プラン欄を空のままにしてください。 ### Q: 対象プランに指定した予約プランを削除したらどうなりますか？ 編集画面の対象プラン欄に、そのプランが赤色の「(削除済みプラン)」chip として表示されます。× ボタンでクリアしてください。放置すると、その回数券は「削除済みプランのみ対象」となり、どの予約でも充当できなくなります（購入済み残高は無効化されるので、返金対応などが必要になります）。 ### Q: 時間単位の回数券で、5時間残っているのに 6時間の予約に充当できないのはなぜ？ 回数券は分割せず、**1本の回数券で1予約を賄える** ことが充当の条件です。5時間残の回数券で 6時間予約を全額充当することはできず、その予約は通常決済になります。ゲスト側のブッキング画面 STEP3 で自動的に判定され、賄えない場合は「回数券で充当」トグルが表示されません。 ### Q: 綴り枚数や価格を後から変更したら、既に購入済みのゲストにも影響しますか？ 影響しません。購入時点の条件（枚数・価格・有効期間）が決済データにスナップショットとして固定されるため、編集は「これから購入する人向け」の条件変更になります。 ### Q: 回数券を削除したいのですが、ボタンが見当たりません 現在の管理画面には削除ボタンはありません。販売を停止したい場合は、編集画面で **販売中にする** のチェックを外して下書き状態に切り替えてください。すでに購入（利用）実績がある回数券は、データ整合性のため今後も物理削除はできない設計になっています。 ### Q: 「購入上限（枚数）」を空欄のままにすると、ゲストは何回でも買えますか？ **いいえ。** 空欄や0で保存すると「1人あたり生涯1回まで」に制限されます（[機能4](#機能4-購入上限の期間-max_per_user_window)を参照）。**購入上限を無くす設定は用意されていません。** 何度でも購入できるようにしたい場合は、購入上限（枚数）に十分大きい回数を明示的に入力してください。 ### Q: 回数券で予約した後にキャンセルすると、枚数は戻りますか？ チェックイン**7日前まで**にキャンセルした場合は、消費したクレジットが1枚戻り、他の予約に再利用できます。チェックイン7日前を過ぎてからのキャンセルは、クレジットは戻らず消費されたままになります。 ### Q: 回数券で予約すると、オプション商品（追加サービス）も無料になりますか？ いいえ。回数券で充当されるのは予約プラン本体の代金のみです。予約時に追加したオプション商品（アドオン）は回数券の対象外で、通常どおり別途課金されます。 ### Q: メンバーシップの無料枠と回数券の両方を持っている場合、どちらが優先されますか？ メンバーシップの無料枠（クォータ）が優先されます。無料枠の範囲内で予約できる場合は回数券は消費されず、無料枠を使い切っている（または対象外の）予約に対してのみ回数券が充当されます。 ### Q: 回数券の購入・利用は「ご利用履歴」（Go ポータル）に表示されますか？ **いいえ、表示されません。** 回数券の購入、および回数券を使った予約（代金0円）は、現バージョンでは「ご利用履歴」ページの集計対象外です。ゲストは回数券の残高を会員アプリのマイページで確認してください。 ### Q: 回数券メニューが表示されません **回数券** メニューは既定で非表示のベータ機能で、施設単位でのオプトイン（個別有効化）が必要です。表示されない場合や、URLを直接開いてもトップページにリダイレクトされてしまう場合は、サポートに `menu_ticket_books` の有効化をご依頼ください。 --- ## 関連ページ - [メンバーシップ管理](membership-plans.md) - [予約管理ダッシュボード](booking.md) - [ホーム画面（会員アプリ）](member-home.md) - [マイページ（会員アプリ）](member-mypage.md) --- 最終更新: 2026-08-21 - #2809（購入上限の文言を実挙動に合わせて修正: プレースホルダー「空欄=制限なし」→「空欄=1人1枚」、新規作成の初期値に既定値 1 を表示、「購入上限の期間」を常時操作可能に、周期ラベル「制限なし」→「通算（リセットなし）」）。PR #2374（購入上限（枚数）フィールド追加・既定値が実質1回になる挙動を追記 + 失効前メール通知（30日/7日/当日）を追加）反映。会員アプリの URL 誤記（`app.unlockos.io` → `member.unlockos.io`）を修正。オプション商品は回数券対象外、メンバーシップ無料枠が回数券より優先、ご利用履歴には非表示、の3点を追記 以前の更新: 2026-08-06 - PR #2224 反映（単位=回数/時間 + 対象プラン MultiSelect + 販売後 unit lock + 有効期間 30日/90日追加 + 販売・利用状況タブ + 会員アプリ購入導線）