評価と調整
紹介プログラムを追加すべきか
初回接触による追跡を有効にする前に、紹介の帰属、現金報酬、プロダクト内クレジットのどれが必要か判断します。
Sushi SaaS が含むのは紹介制度の技術基盤であり、完成したアフィリエイトプログラムではありません。既定では無効です。有効にすると、新規アカウントを紹介者にひも付け、支払い後に保留中の報酬を記録できます。ただし、アフィリエイト参加者の本人確認、送金、クレジット付与、報酬支払いの完了処理は行いません。
既定のユーザージャーニー
- ログイン済みユーザーが短い紹介コード（通常8文字）を作り、
/i/<code>を共有します。 - 訪問者がリンクを開くと、紹介者の UUID を30日間有効な
refCookie に保存し、トップページへリダイレクトします。 - 訪問者がログインすると、クライアントが Cookie を帰属判定用エンドポイントへ送ります。
- サービスは紹介者を一度だけ確定します。自己紹介は拒否し、複数の再試行が並行しても最初に成功した帰属へ収束します。
- 対象の支払い済み注文から、保留中の報酬を一件作ります。データベースの一意制約により、Webhook を再処理しても重複しません。
ユーザーは my-invites ページで紹介リンクと集計を確認できます。運用担当者は管理コンソールの affiliates ページで記録を確認できますが、ここは読み取り専用で、報酬を支払う機能ではありません。
既定例では、通貨の最小単位で5,000か、支払額の20%のうち大きい方を使います。小数点以下2桁の米ドルなら、5,000は50ドルです。これは設定例であり、推奨料率ではありません。
2a1a04a の src/config/affiliate.ts と src/services/affiliate.tsを参照してください。
コードより先に制度を決める
| 目的 | 必要な対応 |
|---|---|
| 紹介機能なし | enabled: false を維持し、不要と確定したらページ、ルート、テーブル、プロバイダーをまとめて削除する |
| 帰属の記録だけ | 初回接触の方式を維持し、報酬の作成と表示を止め、保持してよい分析データを定義する |
| 現金報酬 | 参加資格、本人確認と税務、不正審査、送金事業者、監査可能な状態変更、照合作業を追加する |
| プロダクト内クレジット | 冪等なクレジット台帳への付与処理を追加する。payoutType を変えるだけでは クレジットは付与されない |
| 最終接触への帰属 | サービスに別の帰属規則を実装してテストする。既存の列挙値を変えるだけでは 初回接触の挙動は変わらない |
報酬額の計算は、固定額のみ、比率のみ、大きい方、合計の四方式に対応します。現在、帰属処理は AttributionModel で分岐しないため、実装済みの契約は初回接触方式です。
まだ必要なポリシー
- どの購入を対象とし、保留中の報酬をいつ支払い可能にするか
- 返金、支払いへの異議申立て、解約、アカウント消去の後にどう扱うか
- 対応通貨と最小単位の規則をどうするか
- 従業員、既存顧客、同一世帯の人が参加できるか
- 対象地域で紹介 Cookie への同意が必要か
- 不正利用の調査と修正を、監査履歴を失わずに行う方法
Stripe の返金処理では保留中の報酬を取り消せますが、支払い済み報酬の回収は未実装です。運用方針と失敗時の処理がそろうまで、送金を自動化しないでください。
安全に有効化する
- Stripe 課金を設定・テストします。
src/config/affiliate.tsの帰属期間と報酬例を、自社の制度に合わせて置き換えます。- 有効化する前に、報酬支払いまたはクレジット付与の流れと、管理操作を実装します。
- 匿名訪問 → 登録またはログイン → 初回接触の帰属 → 支払い → Webhook の再処理 → 返金、という一連の流れを試します。
- 自己紹介、競合する二つのリンク、Cookie の期限切れ、イベントの同時処理を試します。
具体的な設定と確認手順は紹介とアフィリエイト報酬を設定する、現在の確認画面は管理コンソールのページと運用を参照してください。