--- sidebar_position: 1 title: "システム概要" --- # ポータルの仕組み（概要） 目的：ポータルの機能、各システムが管理するデータ、データの鮮度管理方法を説明します。 ## コアコンポーネントと責務 - Portal UI (Next.js) + BFF API (NestJS)：すべてのユーザートラフィックを処理し、外部システムを呼び出します。 - Postgres：ポータルユーザーとクロスシステムマッピング `user_id ↔ whmcs_client_id ↔ sf_account_id` を保存。 - Redisキャッシュ：**グローバル**キャッシュ（商品カタログなど）と**アカウントスコープ**キャッシュ（利用資格など）の組み合わせで負荷を軽減し、顧客データの混在を防ぎます。 - WHMCS：請求の管理システム（クライアント、住所、請求書、支払い方法、サブスクリプション）。 - Salesforce：CRM（アカウント/コンタクト）、商品カタログ/価格表、注文、サポートケースの管理システム。 - Freebit：SIMプロビジョニングのみ、モバイル/SIM注文のフルフィルメント時に使用。 ## 高レベルデータフロー - **サインアップ**：ポータルがSalesforceでCustomer Numberを確認 → WHMCSクライアント（請求アカウント）を作成 → ポータルユーザー + マッピングを保存 → Salesforceをポータルステータス + WHMCS IDで更新。 - **ログイン/リンク**：既存WHMCSユーザーがWHMCS認証情報を検証。ポータルユーザーを作成し、IDをマッピングし、Salesforceアカウントをポータルアクティブとしてマーク。 - **サービス & チェックアウト**：商品/価格はSalesforceのポータル価格表から取得。利用資格はアカウントごとに確認。チェックアウト前にWHMCSの支払い方法が必要。 - **注文**：Salesforceに住所スナップショット付きで作成。Salesforce変更イベントがフルフィルメントをトリガーし、対応するWHMCS注文を作成しSalesforceステータスを更新。 - **請求**：請求書、支払い方法、サブスクリプションはWHMCSから読み取り。WHMCS内での請求書支払い用に安全なSSOリンクを生成。 - **サポート**：ケースはOrigin = "Portal Website"でSalesforceに直接作成/読み取り。 ## データ所有権チートシート - ID & セッション：Portal DB（ハッシュ化パスワード、WHMCS/SF認証情報の保存なし） - 請求プロフィール & 住所：WHMCS（権威的ソース）。ポータルが変更をWHMCSに書き戻し。 - 注文 & 注文ステータス：Salesforce（真のソース）。フルフィルメント時にWHMCSが請求/プロビジョニングコピーを受信。 - サポートケース：Salesforce（ポータルはアカウントのケースのみフィルター）。 ## キャッシュ & 鮮度（Redis） - サービスカタログ：イベント駆動（Salesforce CDC）+ 12時間の安全TTL。「volatile」データは60秒TTL。 - 注文：イベント駆動（Salesforce CDC）、TTLなし。 - 請求書：一覧90秒キャッシュ、詳細5分キャッシュ。 - サブスクリプション/サービス：一覧5分、個別10分キャッシュ。 - 支払い方法：15分キャッシュ。決済ゲートウェイ一覧：1時間キャッシュ。 - WHMCSクライアントプロフィール：30分キャッシュ。 - サポートケース：Salesforceからライブ読み取り（キャッシュなし）。 ## エラー時の動作 - 安全に失敗し明確なメッセージを表示：Customer Number不明、重複アカウント、支払い方法不足など。 - WHMCS/Salesforceが一時的に利用不可の場合、部分的なデータではなく「後でやり直してください」メッセージを表示。 - フルフィルメントがエラーコード/メッセージをSalesforceに書き戻し、チームがプロビジョニング停止の理由を確認可能。 ## パブリック vs アカウントAPIの境界 BFFは2種類のサービスカタログエンドポイントを公開： - **パブリックカタログ（パーソナライズなし）**：`GET /api/public/services/*` — Cookie/トークンを無視。パブリックキャッシュ可能。 - **アカウントカタログ（認証 + パーソナライズ）**：`GET /api/account/services/*` — 認証が必要。アカウント固有のカタログバリアント返却可能。