# バッチ設計書 7-create-super-admin-role

## 概要

本ドキュメントはMedusaフレームワークのcreate-super-admin-roleマイグレーションスクリプトについて、その設計内容を記述したバッチ設計書です。本スクリプトは全管理者ユーザーにスーパー管理者ロールを割り当てるマイグレーション処理を実行します。

### 本バッチの処理概要

create-super-admin-roleは、既存のすべての管理者ユーザーに事前定義されたスーパー管理者ロール（`role_super_admin`）を割り当てるマイグレーションスクリプトです。RBAC（Role-Based Access Control）機能が有効な場合のみ実行されます。

**業務上の目的・背景**：Medusaでは、RBAC Feature Flagを有効にすることで、ロールベースのアクセス制御が利用可能になります。RBACを新規に有効化した場合、既存の管理者ユーザーにはロールが割り当てられていません。このスクリプトは、すべての既存管理者ユーザーにスーパー管理者ロールを割り当てることで、RBAC有効化後も管理者が全機能にアクセスできることを保証します。これにより、RBAC導入時のダウンタイムや管理者のアクセス不能状態を防ぎます。

**バッチの実行タイミング**：`db:migrate:scripts`コマンドの実行時に、RBAC Feature Flagが有効な場合のみ実行されます。手動でのCLI実行が必要です。

**主要な処理内容**：
1. USER, AUTH, RBACモジュールのインストール確認
2. 全管理者ユーザーを取得
3. スーパー管理者ロール（`role_super_admin`）を取得
4. ロールのポリシーを検証
5. 各ユーザーにスーパー管理者ロールをリンク

**前後の処理との関連**：`db:migrate`コマンドの後に`db:migrate:scripts`経由で実行されます。USER, AUTH, RBACモジュールがインストールされており、RBAC Feature Flagが有効である必要があります。

**影響範囲**：UserモジュールとRBACモジュール間のリンクテーブルが更新されます。すべての管理者ユーザーが影響を受けます。

## バッチ種別

マイグレーションスクリプト / 権限設定

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（マイグレーション時） |
| 実行時刻 | 手動実行 |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | `db:migrate:scripts`コマンド |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| USERモジュールインストール | `MedusaModule.isInstalled(Modules.USER)`がtrue |
| AUTHモジュールインストール | `MedusaModule.isInstalled(Modules.AUTH)`がtrue |
| RBACモジュールインストール | `MedusaModule.isInstalled(Modules.RBAC)`がtrue |
| RBAC Feature Flag有効 | `FeatureFlag.isFeatureEnabled("rbac")`がtrue |
| データベース接続 | 有効なデータベース接続が確立されていること |

### 実行可否判定

- いずれかのモジュールが未インストールの場合はスキップ（エラーなし）
- RBAC Feature Flagが無効の場合は`defineFileConfig`によりスキップ
- マイグレーションスクリプトテーブルで実行済みとして記録されている場合はスキップ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| container | MedusaContainer | Yes | - | Medusaの依存性注入コンテナ（ExecArgs経由） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| user | DB | 全管理者ユーザー |
| rbac_role | DB | スーパー管理者ロール |
| rbac_role_policy | DB | ロールに紐づくポリシー |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| user_rbac_role（リンクテーブル） | DB | ユーザーとロールのリンク |

### 出力ファイル仕様

ファイル出力なし

## 処理フロー

### 処理シーケンス

```
1. モジュールインストール確認
   └─ USER, AUTH, RBACモジュールの存在チェック
2. 全ユーザー取得
   └─ userModuleService.listUsers({})で全ユーザー取得
3. スーパー管理者ロール取得
   └─ rbacModuleService.listRbacRoles({id: "role_super_admin"})
4. ロール存在確認
   └─ 存在しない場合はエラー
5. ポリシー検証
   └─ rbacModuleService.listRbacRolePolicies({role_id})
   └─ ポリシーがない場合は警告ログ
6. 各ユーザーにロールをリンク
   └─ link.create()でユーザーとロールをリンク
7. 結果サマリー出力
```

### フローチャート

```mermaid
flowchart TD
    A[スクリプト開始] --> B{モジュール確認}
    B -->|不足| C[スキップ]
    B -->|OK| D[ユーザー取得]
    D --> E{ユーザー存在?}
    E -->|No| F[終了]
    E -->|Yes| G[スーパー管理者ロール取得]
    G --> H{ロール存在?}
    H -->|No| I[エラー]
    H -->|Yes| J[ポリシー検証]
    J --> K[ユーザーループ]
    K --> L[link.create]
    L --> M{成功?}
    M -->|Yes| N[成功カウント++]
    M -->|No| O[エラーカウント++]
    N --> P{次のユーザー?}
    O --> P
    P -->|Yes| K
    P -->|No| Q[結果サマリー出力]
    Q --> R[終了]
    C --> R
    F --> R
    I --> R
```

## データベース操作仕様

### 操作別データベース影響一覧

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ユーザー取得 | user | SELECT | 全管理者ユーザーを取得 |
| ロール取得 | rbac_role | SELECT | スーパー管理者ロールを取得 |
| ポリシー取得 | rbac_role_policy | SELECT | ロールのポリシーを取得 |
| リンク作成 | user_rbac_role | INSERT | ユーザーとロールのリンクを作成 |

### テーブル別操作詳細

#### user

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, email | 全件取得 | - |

#### rbac_role

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, name | id = "role_super_admin" | - |

#### rbac_role_policy

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | * | role_id = スーパー管理者ロールID | 検証用 |

#### user_rbac_role（リンクテーブル）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | user_id, rbac_role_id | 各ユーザーID, role_super_admin | link.create経由 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ロール未発見 | role_super_adminが存在しない | RBACモジュールのロード確認 |
| - | リンク作成失敗 | 個別ユーザーのリンク作成失敗 | エラーカウント、処理継続 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

- スーパー管理者ロールが見つからない場合はエラーログを出力してthrow
- 個別ユーザーのリンク作成失敗時は警告ログを出力して次のユーザーに進む
- 全体のエラー件数をサマリーで表示

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | ユーザー単位 |
| コミットタイミング | 各link.create成功時 |
| ロールバック条件 | 個別link.create失敗時 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 管理者ユーザー数に依存 |
| 目標処理時間 | ユーザー数に依存 |
| メモリ使用量上限 | 最小 |

## 排他制御

- マイグレーションスクリプトテーブルにより、同一スクリプトの重複実行を防止
- defineFileConfigによりFeature Flag無効時は実行自体をスキップ

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 情報ログ | 処理開始時 | `Starting super admin role assignment script...` |
| 情報ログ | ユーザー数確認時 | `Found ${users.length} users` |
| 情報ログ | 各ユーザー情報 | `${index + 1}. ${email} (${id})` |
| 情報ログ | ロール検索時 | `Looking for super admin role...` |
| 情報ログ | ロール発見時 | `Found super admin role: ${name} (${id})` |
| 情報ログ | ポリシー確認時 | `Super admin role has ${count} policies assigned` |
| 警告ログ | ポリシー未設定時 | `Super admin role has no policies assigned...` |
| 情報ログ | 処理中 | `Processing user: ${email}` |
| 情報ログ | 成功時 | `Assigned super admin role to user` |
| エラーログ | 失敗時 | `Failed to assign role to user ${id}` |
| 情報ログ | 完了時 | `Super admin role assignment completed successfully!` |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理失敗件数 | 発生時 | コンソールログ |
| ロール未発見 | 発生時 | コンソールログ |

## 備考

- スーパー管理者ロールID: `role_super_admin`
- defineFileConfigでRBAC Feature Flag（`rbac`）が無効の場合はスキップ
- 処理成功後の推奨手順:
  1. Medusaサーバーを再起動
  2. 管理者ユーザーでログインしてテスト
  3. 全管理者エンドポイントへのアクセスを確認
- リンク作成はlink.createを使用（Modules.USERのuser_idとModules.RBACのrbac_role_id）
- 絵文字付きログ出力でユーザーフレンドリーな進捗表示
- 実装箇所: `packages/medusa/src/migration-scripts/create-super-admin-role.ts`
