Exception Flow — Central Membership & SSO Hub
1. ドキュメントの目的
このドキュメントでは、システムで発生する可能性のあるすべての例外条件、システムの対応、ユーザーまたはシステムが取るべきアクションについて説明します。
2. 例外カテゴリ
- 登録 & 認証
- ログイン & 認証
- ライセンスのアクティベーション
- チェックアウト & 支払い
- Webhook Payment Gateway
- SSO & トークン
- グレース期間 & 一時停止
- システム & インフラストラクチャ
3. 例外: 登録 & 認証
EX-REG-01: メールアドレスが既に登録されている
| 属性 |
詳細 |
| 条件 |
ユーザーがシステムに既に存在するメールアドレスで登録を試みる |
| システム |
登録を拒否する |
| HTTP 応答 |
422 Unprocessable Entity |
| ユーザーへのメッセージ |
"このメールアドレスは既に登録されています。ログインするか、別のメールアドレスを使用してください。" |
| ユーザーのアクション |
同じメールアドレスでログインするか、パスワードを忘れた機能を使用する |
| 備考 |
メッセージでは、メールアドレスが登録されているかどうかを確認しないこと（プライバシーのため） |
EX-REG-02: メールアドレスの形式が不正
| 属性 |
詳細 |
| 条件 |
入力されたメールアドレスの形式が正しくない |
| システム |
フロントエンドとバックエンドの両方で検証を拒否する |
| HTTP 応答 |
422 Unprocessable Entity |
| ユーザーへのメッセージ |
"メールアドレスの形式が不正です。" |
| ユーザーのアクション |
メールアドレスの形式を修正する |
EX-REG-03: パスワードが条件を満たしていない
| 属性 |
詳細 |
| 条件 |
パスワードが短すぎる、数字や大文字を含んでいないなど |
| システム |
検証で拒否する |
| HTTP 応答 |
422 Unprocessable Entity |
| ユーザーへのメッセージ |
"パスワードは少なくとも 8 文字で、文字と数字を含める必要があります。" |
| ユーザーのアクション |
条件を満たすパスワードを作成する |
EX-REG-04: メールの検証リンクが期限切れ
| 属性 |
詳細 |
| 条件 |
ユーザーが検証リンクをクリックするが、リンクの有効期限が切れている (例: 24 時間) |
| システム |
検証を拒否し、リンクは無効になる |
| HTTP 応答 |
410 Gone |
| ユーザーへのメッセージ |
"検証リンクは期限切れです。下のボタンをクリックして再送信してください。" |
| ユーザーのアクション |
検証メールの再送信を要求する |
| システムのアクション |
新しいリンクを含む新しい検証メールを送信する |
EX-REG-05: 検証リンクが既に使用されている
| 属性 |
詳細 |
| 条件 |
ユーザーが既に使用された検証リンクをクリックする |
| システム |
アカウントが既にアクティブかどうかを確認する |
| ユーザーへのメッセージ |
"あなたのアカウントは既に検証されています。ログインしてください。" |
| ユーザーのアクション |
ログインする |
4. 例外: ログイン & 認証
EX-LOGIN-01: 認証情報が間違っている
| 属性 |
詳細 |
| 条件 |
入力されたメールアドレスまたはパスワードが間違っている |
| システム |
ログインを拒否する |
| HTTP 応答 |
401 Unauthorized |
| ユーザーへのメッセージ |
"メールアドレスまたはパスワードが間違っています。" |
| ユーザーのアクション |
再試行するか、パスワードを忘れた機能を使用する |
| 備考 |
メッセージでは、メールアドレスが存在しないこととパスワードが間違っていることを区別しないこと（セキュリティのため） |
EX-LOGIN-02: アカウントが検証されていない
| 属性 |
詳細 |
| 条件 |
ユーザーがメールの検証を完了していないアカウントでログインを試みる |
| システム |
ログインを拒否し、検証メールの再送信を提案する |
| HTTP 応答 |
403 Forbidden |
| ユーザーへのメッセージ |
"アカウントが検証されていません。メールを確認するか、再送信ボタンをクリックしてください。" |
| ユーザーのアクション |
メールを確認し、検証リンクをクリックする |
EX-LOGIN-03: アカウントが停止されている
| 属性 |
詳細 |
| 条件 |
ユーザーのアカウントが管理者によって停止されている |
| システム |
ログインを拒否する |
| HTTP 応答 |
403 Forbidden |
| ユーザーへのメッセージ |
"あなたのアカウントは停止されています。詳細についてはサポートに連絡してください。" |
| ユーザーのアクション |
サポートに連絡する |
EX-LOGIN-04: ログイン試行回数が多すぎる
| 属性 |
詳細 |
| 条件 |
ユーザーが短時間にログインに失敗する回数が多すぎる (例: 10 分間で 5 回) |
| システム |
一時的にログインエンドポイントをロックする |
| HTTP 応答 |
429 Too Many Requests |
| ユーザーへのメッセージ |
"ログイン試行回数が多すぎます。10 分後に再試行してください。" |
| ユーザーのアクション |
待ってから再試行する |
5. 例外: ライセンスのアクティベーション
EX-LIC-01: アカウントが検証されていないときにライセンスをアクティベートする
| 属性 |
詳細 |
| 条件 |
ユーザーがアカウントを検証する前にライセンスをアクティベートしようとする |
| システム |
アクティベーションを拒否する |
| HTTP 応答 |
403 Forbidden |
| ユーザーへのメッセージ |
"メールの検証を完了してから、製品をアクティベートしてください。" |
| ユーザーのアクション |
メールの検証を完了する |
EX-LIC-02: 同じ製品のライセンスが既にアクティブである
| 属性 |
詳細 |
| 条件 |
ユーザーが同じ製品の無料ライセンスをアクティベートしようとするが、既にアクティブなライセンスを持っている |
| システム |
デュプリケートを拒否し、既存のライセンスの詳細に誘導する |
| HTTP 応答 |
409 Conflict |
| ユーザーへのメッセージ |
"あなたは既にこの製品のアクティブなライセンスを持っています。" |
| ユーザーのアクション |
ダッシュボードでアクティブなライセンスを確認するか、アップグレードを選択する |
EX-LIC-03: 製品が利用できない
| 属性 |
詳細 |
| 条件 |
ユーザーが削除または無効化された製品のライセンスをアクティベートしようとする |
| システム |
アクティベーションを拒否する |
| HTTP 応答 |
404 Not Found |
| ユーザーへのメッセージ |
"製品は現在利用できません。" |
| ユーザーのアクション |
別の製品を選択する |
6. 例外: チェックアウト & 支払い
EX-PAY-01: 支払い前に注文が期限切れになる
| 属性 |
詳細 |
| 条件 |
ユーザーが注文を完了する前に支払いが期限切れになる |
| システム |
注文を「期限切れ」とマークし、ライセンスをアクティベートしない |
| ユーザーへのメッセージ |
"あなたの支払いセッションは期限切れになりました。購入プロセスを再開してください。" |
| ユーザーのアクション |
カタログに戻って新しい注文を作成する |
EX-PAY-02: 支払いが拒否される
| 属性 |
詳細 |
| 条件 |
支払いが拒否される (残高不足、カード拒否など) |
| システム |
注文を「失敗」とマークし、ライセンスをアクティベートしない |
| ユーザーへのメッセージ |
"支払いは失敗しました。別の方法を試してください。" |
| ユーザーのアクション |
別の支払い方法を試す |
EX-PAY-03: 支払い額が不正
| 属性 |
詳細 |
| 条件 |
Webhook で受け取った支払い額が注文の金額と一致しない |
| システム |
ライセンスのアクティベーションを拒否し、ログに記録する |
| ユーザーへのアクション |
なし |
| システムのアクション |
ライセンスをアクティベートせず、ログを保存する |
EX-PAY-04: ダブルチェックアウト (重複注文)
| 属性 |
詳細 |
| 条件 |
ユーザーが同じ製品に対して短時間に複数の注文を作成する |
| システム |
1 つの注文のみを処理し、重複注文を「重複」とマークする |
| ユーザーへのメッセージ |
"あなたは既にこの製品のアクティブな注文を持っています。進行中の注文を完了してください。" |
| ユーザーのアクション |
既存の注文を完了する |
7. 例外: Webhook Payment Gateway
EX-WH-01: Webhook の検証に失敗
| 属性 |
詳細 |
| 条件 |
Webhook の署名が不正または無効 |
| システム |
Webhook を無視し、エラーログに記録する |
| HTTP 応答 (ゲートウェイに) |
400 Bad Request |
| ライセンス |
アクティベートされない |
| アクション |
管理者がログを確認し、必要に応じて手動で検証する |
EX-WH-02: Webhook の再送信 (リトライ)
| 属性 |
詳細 |
| 条件 |
支払いゲートウェイが成功応答を受け取らないため、同じ Webhook を再送信する |
| システム |
order_id が既に処理されたかどうかを確認し、重複を無視する (イデンプテント) |
| HTTP 応答 (ゲートウェイに) |
200 OK (ゲートウェイがリトライを停止するため) |
| ライセンス |
二重にアクティベートされない |
EX-WH-03: Webhook が届いたときにサーバーがダウンしている
| 属性 |
詳細 |
| 条件 |
支払いゲートウェイが Webhook を送信するときに、サーバーが利用できない |
| システム |
支払いゲートウェイは自動的にリトライを試みる |
| アクション |
サーバーが回復した後、Webhook エンドポイントが応答できることを確認する |
| フォールバック |
管理者が支払いログを確認し、必要に応じて手動でアクティベーションを実行する |
8. 例外: SSO & トークン
EX-SSO-01: 製品のライセンスを持っていない
| 属性 |
詳細 |
| 条件 |
ユーザーがライセンスのない製品にログインを試みる |
| システム |
トークンの発行を拒否し、パッケージ選択ページにリダイレクトする |
| 応答 |
403 no_license |
| ユーザーへのメッセージ |
"あなたはこの製品を購読していません。パッケージを選択して開始してください。" |
EX-SSO-02: ライセンスが停止されている
| 属性 |
詳細 |
| 条件 |
ユーザーが停止されたライセンスでアプリケーションにログインを試みる |
| システム |
トークンの発行を拒否し、更新ページにリダイレクトする |
| 応答 |
403 license_suspended |
| ユーザーへのメッセージ |
"あなたのアクセスはブロックされています。サブスクリプションを更新して続行してください。" |
EX-SSO-03: アクセストークンが期限切れ
| 属性 |
詳細 |
| 条件 |
アプリケーションが期限切れのアクセストークンでリクエストを受け取る |
| システム |
リクエストを拒否する |
| HTTP 応答 |
401 Unauthorized |
| アプリケーションのアクション |
リフレッシュトークンを使用して新しいアクセストークンを取得する |
EX-SSO-04: リフレッシュトークンが不正または期限切れ
| 属性 |
詳細 |
| 条件 |
リフレッシュトークンが期限切れまたは無効 |
| システム |
新しいアクセストークンの発行を拒否する |
| 応答 |
401 invalid_refresh_token |
| アプリケーションのアクション |
ユーザーをハブのログインページにリダイレクトする |
EX-SSO-05: ステートパラメータが一致しない (CSRF)
| 属性 |
詳細 |
| 条件 |
ハブによって返される state の値がアプリケーションによって保存された値と一致しない |
| システム |
SSO プロセスを拒否する |
| アプリケーションのアクション |
エラーメッセージを表示し、ユーザーにログインプロセスを再開するように求める |
| 備考 |
CSRF 攻撃からの保護 |
EX-SSO-06: JWT の署名が不正
| 属性 |
詳細 |
| 条件 |
アプリケーションがハブのパブリックキーで検証できない JWT を受け取る |
| システム |
JWT を拒否する |
| アプリケーションのアクション |
アクセスを拒否し、ログインページにリダイレクトする |
| 備考 |
トークンが偽造された場合に発生する可能性がある |
9. 例外: グレース期間 & 停止
EX-GP-01: グレース期間の通知が失敗
| 属性 |
詳細 |
| 条件 |
グレース期間のリマインダーメールが送信できない (メールサービスエラー) |
| システム |
失敗をログに記録し、リトライポリシーに従って再送信を試みる |
| アクション |
ダッシュボードのインアプリ通知は表示される |
| 備考 |
メールの失敗はグレース期間のプロセスを停止しない |
EX-GP-02: 停止後にユーザーが支払う
| 属性 |
詳細 |
| 条件 |
ライセンスが停止された後にユーザーが支払う |
| システム |
ライセンスを再アクティベートする |
新しい expired_at |
支払い日 + パッケージ期間 |
| ユーザーへのメッセージ |
"あなたのアクセスは回復しました。ご購読のご継続ありがとうございます |