# ユースケース

## ケース: 小売業支援SaaSにおける埋め込みダッシュボードの活用

### シナリオ

小売業の店舗運営を支援するSaaSプラットフォームにおいて、店舗ごとの売上状況やKPIを把握するためのダッシュボードをSaaS内に埋め込むニーズを想定します。 この機能により、店舗マネージャーやエリアマネージャーがログインした際、自分の店舗に関連する情報だけを表示することができます。

### ノートブックのパラメータ

署名付き埋め込みのソースとなるノートブックには、以下のパラメータが設定されているものとします。

* `tenant_id`:
  * ログインしているユーザーが所属するテナントID
  * 「テキスト入力」型パラメータ
* `store_id`:
  * データの表示対象となる店舗ID
  * 「テキスト選択」型パラメータで、 選択肢は `tenant_id` で指定されたテナント内の店舗IDを選択可能
* `date_range`:
  * データの集計期間
  * 「日付範囲」型パラメータで、デフォルト値は相対日付で前日から7日間が指定されている
* `product_category`:
  * データの集計対象を絞り込むための商品カテゴリ
  * 「テキスト複数選択」型パラメータで、未選択の場合は全ての商品カテゴリを表示するようにSQL上で条件指定している

### 設定例A: 署名付き埋め込みのフォームを利用する場合

#### 前提となるノートブックの設計

* `tenant_id` を固定することで、ユーザーがアクセス可能なデータのセキュリティを担保できている
  * データを抽出する際のSQLには、 `tenant_id` がフィルタ条件として必ず指定されている
  * 例えば、店舗データを抽出する際も、 `store_id` だけでなく `tenant_id` もフィルタ条件に指定され、テナントが異なる店舗のデータは抽出できないようになっている
* `date_range` と `product_category` については、任意の値が指定可能という設計である

#### パラメータの設定

* `tenant_id`: **サーバーサイドパラメータの固定値**
* `store_id`: サーバサイドパラメータの初期値
* `date_range`: クライアントサイドパラメータ
* `product_category`: クライアントサイドパラメータ

#### 表示までの流れ

1. サーバーサイドでトークンを発行
   * ユーザーの所属する `tenant_id` をサーバーサイドパラメータの固定値として指定
   * `tenant_id` に紐づく `store_id` の中で、初期状態として表示する `store_id` をサーバーサイドパラメータの初期値として指定
2. フロントエンドでの初期描画処理
   * `SET_TOKEN` メッセージの送信時に、以下のクライアントサイドパラメータを一緒に送信します
     * `date_range` は相対日付の再計算を行うため、デフォルト値にリセットするように指定
     * `product_category` は空配列を初期値として指定
3. ユーザーによるダッシュボードの操作
   * ユーザーは `store_id`, `date_range`, `product_category` をダッシュボードのフォーム上から変更することができます

### 設定例B: SaaS側のフロントエンドでパラメータを管理する場合

#### 前提となるノートブックの設計

「設定例A」と同様の設計とします

#### パラメータの設定

* `tenant_id`: **サーバーサイドパラメータの固定値**
* `store_id`: クライアントサイドパラメータ
* `date_range`: クライアントサイドパラメータ
* `product_category`: クライアントサイドパラメータ

#### 表示までの流れ

1. サーバーサイドでトークンを発行
   * ユーザーの所属する `tenant_id` をサーバーサイドパラメータの固定値として指定
2. フロントエンドでの初期描画処理
   * `SET_TOKEN` メッセージの送信時に、以下のクライアントサイドオプションを一緒に送信します
     * パラメータはSaaS側で管理するため、パラメータフォームを非表示にするオプション(`displayOptions.hideParamsForm = true`)を指定
     * `store_id`, `date_range`, `product_category` には、SaaS側で管理している値を指定します
3. ユーザーによるダッシュボードの操作
   * SaaS側で管理している条件の変更等により、ダッシュボードの表示条件を変更する場合、次の手順を踏みます
   * 初期描画処理で利用したトークンを**再利用して**、更新されたクライアントサイドオプションと一緒に `SET_TOKEN` メッセージを再送信します
     * `SET_TOKEN` メッセージを再送信することで、新しく送信されたクライアントサイドオプションにより、ダッシュボードの再描画が行われます
     * この時に送信するクライアントサイドパラメータは、差分ではなく、全件（`store_id`, `date_range`, `product_category`）を送信する必要があります
     * 同一のユーザーが、同一のサーバーサイドパラメータの固定値を利用する場合、トークンの再利用が可能です（有効期限には注意してください）

### 設定例C: サーバーサイドパラメータの固定値を更新する場合

#### 前提となるノートブックの設計

* `tenant_id` と `store_id` の両方を固定することで、ユーザーがアクセス可能なデータのセキュリティを担保できている
  * 「設定例A」の場合と異なり、 `store_id` をサーバーサイドで固定する必要がある場合を想定します
* `date_range` と `product_category` については、「設定例A」と同様に、任意の値が指定可能という設計である

#### パラメータの設定

* `tenant_id`: **サーバーサイドパラメータの固定値**
* `store_id`: **サーバーサイドパラメータの固定値**
* `date_range`: クライアントサイドパラメータ
* `product_category`: クライアントサイドパラメータ

#### 表示までの流れ

1. サーバーサイドでトークンを発行
   * ユーザーの所属する `tenant_id` と、初期状態として表示する `store_id` をサーバーサイドパラメータの固定値として指定
2. フロントエンドでの初期描画処理
   * `SET_TOKEN` メッセージの送信時に、以下のクライアントサイドパラメータを一緒に送信します
     * `date_range` は相対日付の再計算を行うため、デフォルト値にリセットするように指定
     * `product_category` は空配列を初期値として指定
3. ユーザーによるダッシュボードの操作
   * `store_id` はサーバーサイドパラメータの固定値のため、ダッシュボード上のフォームからは変更できず、SaaS側で `store_id` を管理し、対象店舗の変更フォームを用意する必要があります
   * ユーザーからの操作により、 `store_id` を変更してダッシュボードを再描画する場合、次の手順を踏みます
   * サーバーサイドに対して、新しい `store_id` を指定して**トークンを新しく発行**し、新しいトークンとクライアントサイドパラメータを一緒に `SET_TOKEN` メッセージを送信します
     * サーバーサイドパラメータの固定値を変更するためには、トークンの再発行が必要となります
     * クライアントサイドパラメータは、差分ではなく、全件（`date_range`, `product_category`）を送信する必要があります
       * ユーザーの操作により変更された `date_range` や `product_category` を保持したい場合、 iframe から送信される `PARAM_CHANGED` メッセージを記録しておき、再描画時に送信するようにします
   * `date_range` と `product_category` については、ユーザーがダッシュボード上のフォームから表示内容を変更することができます