ramirez
d7efc99fdc
Translated all UAT test guides and how-it-works documentation to Japanese. Files are organized under docs/ja/uat/ and docs/ja/how-it-works/.
57 lines
4.5 KiB
Markdown
57 lines
4.5 KiB
Markdown
---
|
||
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/*` — 認証が必要。アカウント固有のカタログバリアント返却可能。
|