Assist_Design/docs/ja/how-it-works/system-overview.md

sidebar_position, title

sidebar_position	title
1	システム概要

ポータルの仕組み（概要）

目的：ポータルの機能、各システムが管理するデータ、データの鮮度管理方法を説明します。

コアコンポーネントと責務

• 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/* — 認証が必要。アカウント固有のカタログバリアント返却可能。