登録が捉えるのは意図です。ユーザーが製品の利用を要求します。これに対し、運用上のオンボーディングが確認するのは、より厳しい事項です。組織が利用開始可能であり、有効な最小構成を備え、担当者に必要な権限があり、必要なリソースが整合性を保って存在することです。この二つの時点を単一のHTTPリクエストとして扱うと、不完全なアカウント、タイムアウト、重複、監査が困難な手作業の手順が生じがちです。
PHPでのSaaSアカウントプロビジョニングは、復旧可能な業務プロセスとして設計する必要があります。すなわち、状態を保持し、バックグラウンドで処理を実行し、繰り返しに耐え、運用担当者が本番環境でレコードを直接変更せずに対応できる十分なコンテキストを提供することです。
組織が実際に準備完了となる条件を定義する
テーブル、イベント、キューを決める前に、準備完了の契約を定めることが重要です。データベースに行が挿入されたからというだけで、組織をアクティブとマークすべきではありません。製品に依存する、検証可能な条件を満たす必要があります。
- アイデンティティとアクセス: 組織が存在し、初期ユーザーが作成または招待され、想定された管理者ロールを持っている。
- 基本構成: タイムゾーン、言語、アクセスポリシー、プランまたは上限が明示的な値で解決されている。
- 初期データ: ワークスペース、空のカタログ、ルール、設定など、不可欠なリソースが作成されている。
- 外部依存関係: 必要な場合、プロバイダー上のテナント、サブスクリプション、技術認証情報などのリソースが要求または検証されている。
- 責任: 未完了の手順を誰が完了でき、その人にどのアクションが許可されているかが明確である。
必須要件と任意の改善を分けることで、重要ではないタスクのためにアクセスを妨げずに済みます。たとえば、サンプルインポートの生成は任意にできますが、必須のセキュリティポリシーの検証は任意ではありません。この区別は、チームが個々の営業上の要望を恒久的な製品バリアントに変えてしまうことも防ぎます。
オンボーディングを状態機械としてモデル化する
状態機械により許可された遷移が可視化され、activeのような汎用フィールドの曖昧さが減ります。初期モデルには、requested、provisioning、ready、blocked、failed、cancelledを含められます。正確な名前よりもルールのほうが重要です。
たとえば、有効な要求は組織をrequestedで作成します。オーケストレーターがそれをprovisioningへ移し、タスクをスケジュールします。準備完了チェックだけがreadyへ移行できます。契約上の制約や無効なデータのような復旧不能なエラーはblockedへ移行させられます。技術的障害で試行回数を使い果たした場合は、常に構造化された理由とともにfailedに留められます。
各遷移を日時、実行者、原因、相関情報とともに保存してください。実行者はユーザー、プロセス、運用担当者のいずれでもかまいません。コントローラーや管理スクリプトから任意の変更を許可しないでください。遷移はドメインサービスに集約し、遷移元の状態を検証します。これにより、たとえば遅延した再試行によってキャンセル済み組織を再アクティブ化することを防げます。
リクエストと低速処理を分離する
登録リクエストは、データを検証し、冪等キーを適用し、要求を永続化して、迅速にレスポンスを返すべきです。低速なリソース作成、サードパーティAPIの呼び出し、メール送信、基本データの読み込みは、非同期ジョブに移す必要があります。
PHPでは、キューワーカーが小さく観測可能なタスクを実行できます。管理者の作成、構成テンプレートの適用、統合のプロビジョニング、準備完了の確認などです。すべてのロジックを単一の不透明なジョブに委ねるべきではありません。失敗した場合、何が完了し、何を再試行できるのかを把握しにくくなるためです。テンプレートは再利用可能な初期値を定義するものであり、データモデルや顧客ごとに分離されたアプリケーションのコピーと混同してはいけません。
プロビジョニングタスクにおける冪等性とトレーサビリティ
ネットワークは障害を起こし、ブラウザーはフォームを再送し、ワーカーは同じメッセージを複数回処理することがあります。冪等性が保証するのは、操作を繰り返しても同じ論理的効果が得られることであり、二度実行されないことではありません。
オンボーディング要求にidempotency_keyを割り当て、適切なスコープ、通常はチャネルと要求された組織とともに保存します。検証済みドメインや外部識別子など、該当するビジネスアイデンティティに一意制約を課してください。派生リソースには安定したキーを使用します。組織向けにdefaultスペースを作成する場合、すでに存在すればそれを見つけるべきであり、別のものを挿入してはいけません。
provisioning_task - organization_id - task_type - input_payload - status - attempt_count - result_payload - error_code - error_detail - correlation_id - started_at - finished_at
input_payloadにより、何が要求されたかを再構築できます。結果には外部識別子または作成済みリソースを記録します。error_codeは安定させ、自動化に役立つものにしてください。一方、詳細には保護された技術的コンテキストを含められます。correlation_idは、完全なオンボーディングを手作業で手掛かりを結び付けずに調査できるよう、要求からログ、イベント、送信呼び出しへ伝播させる必要があります。
ワーカーはタスクを安全に取得し、試行を記録し、その結果を永続化した後でのみ結果を確定すべきです。外部APIが冪等キーを受け付ける場合は、再試行ごとにランダムなキーを使うのではなく、タスクから導出したキーを使用してください。対応していない場合は、作成前に決定論的な識別子でリモートリソースを照会します。
部分的な障害を隠さずに復旧する
すべてのエラーに同じ対応が必要なわけではありません。一時的な利用不能、レート制限、並行性の競合といった一過性の障害は、回数を制限して再試行してください。段階的な待機と試行回数の上限を適用します。無制御な再試行は負荷を増やし、外部への影響を増幅しかねません。
ロールバックが安全で価値がある場合にのみ補償してください。部分的に作成された組織の削除は、アクセスを付与する前であれば正しいことがありますが、すでに顧客のアクティビティを含む場合は危険です。多くの場合、アクティブ化をブロックし、証跡を保持してレビューへ回すほうが望ましいです。
- 再試行: 依存関係が一時的に利用不能で、操作が冪等である。
- 補償: 作成されたリソースに後続の利用がなく、トレーサビリティを失わずに削除できる。
- ブロック: 検証や必須の承認など、必須条件が欠けている。
- レビュー: ローカル状態と外部プロバイダー間に不一致がある、または再試行回数を使い果たした。
最小限の運用コンソールには、組織、現在の状態、タスク、試行回数、直近のエラー、相関情報、許可されたアクションを表示すべきです。許可されたアクションとは、タスクの再試行、フローの再開、キャンセル、理由を添えて例外としてマークすることです。アクションは監査証跡を生成しなければなりません。通常の手順としてデータベースへの直接アクセスを与えると、制御が失われ、修正と偶発的な改変を区別できなくなります。
保守可能な初期構成とフローのテスト
製品セグメント、プラン、リージョンごとの基本値には、バージョン管理された宣言的構成を使用してください。顧客ごとにコードを分岐させるのではなく、明示的かつ限定的なルールを適用します。真の例外は、所有者、レビュー日、既知の影響を備えた構成可能な機能として残す必要があります。そうしなければ、オンボーディングのたびに取り除けない条件が蓄積します。
テストはフォーム以上を対象にする必要があります。有効および無効な遷移、同じ要求の繰り返し、ジョブの重複実行、同一アイデンティティに対する二つの並行要求、障害後の再開を検証してください。存在する場合は補償と、前提条件なしに組織をアクティブ化できないこともテストします。外部統合には、低速なレスポンス、エラー、すでに作成済みの結果を再現するテストダブルを使用してください。
要求から準備完了までの時間、介入が必要なオンボーディングの割合、タスク種別ごとの再試行、終端障害、各状態での時間を測定します。フローのバージョン、流入元、アカウント種別でセグメント化し、特定のリグレッションを検出してください。完了した登録が増加しても、ブロックされた組織が増えているなら、オンボーディングの改善ではありません。摩擦を移しただけです。
現在のプロセスをレビューするためのチェックリスト
- 準備完了した組織について、共有され検証可能な定義があるか。
- 遷移は制限され、監査されているか。
- HTTPレスポンスは低速なタスクや外部プロバイダーに依存していないか。
- 各要求とタスクに冪等キーと追跡可能な相関情報があるか。
- 再試行は一過性のエラーと業務エラーを区別しているか。
- 運用担当者はデータを直接編集せずにオンボーディングを診断し、再開できるか。
- 初期構成は宣言的で、バージョン管理され、限定されているか。
- テストは重複、並行性、部分障害を対象にしているか。
これらの回答が肯定的なら、オンボーディングは脆弱なフォームではなく、SaaSの運用能力になります。観測可能で、復旧可能であり、その複雑さを顧客やサポートチームへ移すことなく進化できる能力です。
