# 画面設計書 65-ユーザー・権限管理

## 概要

本ドキュメントは、Shopware 6 管理画面（Administration）におけるユーザー・権限管理画面の設計を記述したものです。管理者ユーザーとロール（役割）の作成・編集・削除を行う管理画面です。

### 本画面の処理概要

ユーザー・権限管理画面は、Shopware管理画面にアクセスできるユーザーアカウントと、その権限を定義するロール（役割）を管理する画面です。ロールベースのアクセス制御（RBAC）により、ユーザーごとに異なる操作権限を付与できます。

**業務上の目的・背景**：ECサイトの運営には複数の担当者が関わることが一般的です。商品管理担当、注文処理担当、システム管理者など、役割に応じて適切な権限を付与することで、セキュリティを確保しながら効率的な運用が可能になります。本画面では、管理者ユーザーの作成・編集、ロールの定義、権限の割り当てを行います。

**画面へのアクセス方法**：管理画面にログイン後、左メニューの「設定」 > 「システム」セクション > 「ユーザーと権限」をクリックしてアクセスします。URL パスは `#/sw/users/permissions/index` です。

**主要な操作・処理内容**：
1. **ユーザー一覧表示**：管理者ユーザーの一覧を表示
2. **ユーザーの作成・編集・削除**：管理者ユーザーアカウントの管理
3. **ロール一覧表示**：アクセス権限ロールの一覧を表示
4. **ロールの作成・編集・削除**：ロールの定義と権限設定
5. **システム設定の保存**：ユーザー関連のシステム設定を保存
6. **SSO連携**：シングルサインオン（SSO）ユーザーの管理

**画面遷移**：
- 遷移元：設定一覧画面（sw-settings-index）
- 遷移先：
  - ユーザー詳細画面（sw-users-permissions-user-detail）
  - ユーザー作成画面（sw-users-permissions-user-create）
  - ロール詳細画面（sw-users-permissions-role-detail）
  - SSOユーザー詳細画面（sw-sso-users-permission-user-detail）

**権限による表示制御**：
- `users_and_permissions.viewer`：閲覧のみ可能
- `users_and_permissions.editor`：編集が可能（保存ボタン有効）
- `users_and_permissions.creator`：新規作成が可能
- `users_and_permissions.deleter`：削除が可能

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 6 | 顧客なりすましログイン | 補助機能 | 管理者ユーザーとロールの管理 |

## 画面種別

一覧・管理

## URL/ルーティング

| 項目 | 値 |
|------|---|
| モジュール名 | sw-users-permissions |
| 一覧ルート | sw.users.permissions.index |
| ユーザー詳細ルート | sw.users.permissions.user.detail |
| ユーザー作成ルート | sw.users.permissions.user.create |
| ロール詳細ルート | sw.users.permissions.role.detail |
| SSOユーザー詳細ルート | sw.users.permissions.user.sso.detail |
| URLパス（一覧） | #/sw/users/permissions/index |

## 入出力項目

### ユーザー情報

| 項目名 | 項目ID | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| ユーザー名 | username | String | Yes | ログインユーザー名 |
| メールアドレス | email | String | Yes | ユーザーのメールアドレス |
| パスワード | password | String | Yes（作成時） | ログインパスワード |
| 名 | firstName | String | Yes | ユーザーの名 |
| 姓 | lastName | String | Yes | ユーザーの姓 |
| 有効 | active | Boolean | No | アカウントの有効/無効 |
| ロール | aclRoles | Array | No | 割り当てられたロール |
| 言語 | localeId | UUID | No | 管理画面の表示言語 |
| タイムゾーン | timeZone | String | No | ユーザーのタイムゾーン |

### ロール情報

| 項目名 | 項目ID | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| ロール名 | name | String | Yes | ロールの名称 |
| 説明 | description | String | No | ロールの説明 |
| 権限 | privileges | Array | No | 付与される権限リスト |

## 表示項目

### ユーザー一覧カード

| セクション | 表示項目 | 説明 |
|------------|----------|------|
| ヘッダー | ユーザー追加ボタン | 新規ユーザー作成画面への遷移 |
| 一覧 | ユーザー名 | ログインユーザー名 |
| 一覧 | 名前 | 姓名 |
| 一覧 | メールアドレス | ユーザーのメールアドレス |
| 一覧 | ロール | 割り当てられたロール |
| 一覧 | 有効状態 | アカウントの有効/無効 |
| 一覧 | アクション | 編集・削除ボタン |

### ロール一覧カード

| セクション | 表示項目 | 説明 |
|------------|----------|------|
| ヘッダー | ロール追加ボタン | 新規ロール作成画面への遷移 |
| 一覧 | ロール名 | ロールの名称 |
| 一覧 | 説明 | ロールの説明 |
| 一覧 | アクション | 編集・削除ボタン |

### 設定カード

| セクション | 表示項目 | 説明 |
|------------|----------|------|
| システム設定 | 設定項目 | sw-system-config コンポーネントで自動生成 |

## イベント仕様

### 1-ユーザー追加ボタン押下

**トリガー**: ユーザー一覧カードの「追加」ボタンクリック

**処理フロー**:
1. ユーザー作成画面（sw.users.permissions.user.create）に遷移

### 2-ユーザー編集

**トリガー**: ユーザー一覧の行クリックまたは編集アイコンクリック

**処理フロー**:
1. ユーザー詳細画面（sw.users.permissions.user.detail）に遷移
2. パラメータとしてユーザーIDを渡す

### 3-ユーザー削除

**トリガー**: ユーザー一覧の削除アイコンクリック

**処理フロー**:
1. 削除確認ダイアログを表示
2. 確認後、userRepository.delete() で削除
3. 一覧を再読み込み

### 4-ロール追加ボタン押下

**トリガー**: ロール一覧カードの「追加」ボタンクリック

**処理フロー**:
1. ロール詳細画面（sw.users.permissions.role.detail）に遷移（新規作成モード）

### 5-ロール編集

**トリガー**: ロール一覧の行クリックまたは編集アイコンクリック

**処理フロー**:
1. ロール詳細画面（sw.users.permissions.role.detail）に遷移
2. パラメータとしてロールIDを渡す

### 6-保存ボタン押下

**トリガー**: 「保存」ボタンクリック

**処理フロー**:
1. `onSave` メソッドが実行される
2. `configuration.$refs.systemConfig.saveAll()` でシステム設定を保存
3. 成功時: ボタンが成功状態に変化
4. 失敗時: エラー通知を表示

### 7-一覧再読み込み

**トリガー**: ロール一覧から get-list イベント発火

**処理フロー**:
1. `reloadUserListing` メソッドが実行される
2. ユーザー一覧とロール一覧の両方を再取得

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| ユーザー作成 | user | INSERT | 新規ユーザーレコード作成 |
| ユーザー更新 | user | UPDATE | ユーザー情報の更新 |
| ユーザー削除 | user | DELETE | ユーザーレコード削除 |
| ロール作成 | acl_role | INSERT | 新規ロールレコード作成 |
| ロール更新 | acl_role | UPDATE | ロール情報・権限の更新 |
| ロール削除 | acl_role | DELETE | ロールレコード削除 |
| アクセスキー作成 | user_access_key | INSERT | APIアクセスキー作成 |
| システム設定保存 | system_config | UPDATE/INSERT | 関連システム設定の保存 |

### テーブル別更新項目詳細

#### user

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT/UPDATE | username | 入力値 | ログインユーザー名 |
| INSERT/UPDATE | email | 入力値 | メールアドレス |
| INSERT/UPDATE | password | ハッシュ化された値 | パスワード（作成時必須） |
| INSERT/UPDATE | first_name | 入力値 | 名 |
| INSERT/UPDATE | last_name | 入力値 | 姓 |
| INSERT/UPDATE | active | true/false | 有効フラグ |
| INSERT/UPDATE | locale_id | UUID | 言語設定 |
| INSERT/UPDATE | time_zone | タイムゾーン文字列 | タイムゾーン |

#### acl_role

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT/UPDATE | name | 入力値 | ロール名 |
| INSERT/UPDATE | description | 入力値 | 説明 |
| INSERT/UPDATE | privileges | JSON配列 | 権限リスト |

## メッセージ仕様

| 種別 | メッセージキー | メッセージ内容 | 表示条件 |
|------|--------------|--------------|---------|
| エラー | （動的） | API エラーメッセージ | 保存失敗時 |
| 確認 | （動的） | 削除確認メッセージ | ユーザー/ロール削除時 |

## 例外処理

| 例外状態 | 対応処理 | 画面表示 |
|---------|---------|---------|
| 権限不足（閲覧） | 画面アクセス不可 | 設定メニューに表示されない |
| 権限不足（編集） | 保存ボタン無効化 | 保存ボタンが無効状態 |
| 権限不足（作成） | 追加ボタン非表示 | 追加ボタンが表示されない |
| API通信エラー | エラー通知表示 | エラーメッセージを通知で表示 |
| 自分自身の削除 | 削除不可 | エラーメッセージを表示 |

## 備考

- 管理者ユーザーは最低1人は必要です（最後の管理者は削除できません）
- 自分自身のアカウントは削除できません
- パスワードは作成時のみ必須で、編集時は空欄の場合変更されません
- SSOユーザーは別の詳細画面で管理されます
- ロールの権限設定は詳細画面で行います

---

## コードリーディングガイド

本画面を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

ユーザーとロールのエンティティ構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | UserDefinition | `src/Core/Framework/Api/Acl/Role/UserDefinition.php` | ユーザーエンティティの定義 |
| 1-2 | AclRoleDefinition | `src/Core/Framework/Api/Acl/Role/AclRoleDefinition.php` | ロールエンティティの定義 |

**読解のコツ**: Shopware 6 の権限管理は ACL（Access Control List）ベースで、user と acl_role テーブルが関連しています。

#### Step 2: エントリーポイントを理解する

処理の起点となるモジュール登録とルーティングを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.js | `src/Administration/Resources/app/administration/src/module/sw-users-permissions/index.js` | モジュール登録とルート定義 |

**主要処理フロー**:
1. **7-60行目**: コンポーネントの遅延ロード登録（多数のコンポーネント）
2. **65-147行目**: `Module.register` でモジュールを登録
3. **77-138行目**: ルート定義（index, user.detail, user.create, role.detail等）
4. **141-146行目**: 設定メニューへの項目追加（systemグループ）

#### Step 3: ページコンポーネントを理解する

メインページコンポーネントの構造を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sw-users-permissions/index.js | `src/Administration/Resources/app/administration/src/module/sw-users-permissions/page/sw-users-permissions/index.js` | ページのメインロジック |
| 3-2 | sw-users-permissions.html.twig | `src/Administration/Resources/app/administration/src/module/sw-users-permissions/page/sw-users-permissions/sw-users-permissions.html.twig` | テンプレート構造 |

**主要処理フロー**:
- **35-43行目**: `reloadUserListing` でユーザー・ロール一覧の再取得
- **49-63行目**: `onSave` でシステム設定の保存
- **37-47行目（テンプレート）**: ユーザー一覧、ロール一覧、設定コンポーネントの配置

#### Step 4: 権限設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | acl/index.js | `src/Administration/Resources/app/administration/src/module/sw-users-permissions/acl/index.js` | 権限マッピング定義 |

**主要処理フロー**:
- **9-22行目**: viewer ロールの権限（read権限）
- **24-38行目**: editor ロールの権限（update/create権限）
- **40-48行目**: creator ロールの権限（create権限）
- **50-58行目**: deleter ロールの権限（delete権限）

### プログラム呼び出し階層図

```
sw-users-permissions (Page)
    │
    ├─ sw-users-permissions-user-listing (Component)
    │      └─ userRepository
    │             └─ CRUD操作
    │
    ├─ sw-users-permissions-role-listing (Component)
    │      └─ aclRoleRepository
    │             └─ CRUD操作
    │
    └─ sw-users-permissions-configuration (Component)
           └─ sw-system-config
                  └─ SystemConfigService
```

### データフロー図

```
[入力]                      [処理]                         [出力]

ユーザー情報入力    ───▶   sw-users-permissions-      ───▶  user テーブル
                           user-detail
                                   │
                                   └─▶ userRepository.save()

ロール情報入力      ───▶   sw-users-permissions-      ───▶  acl_role テーブル
                           role-detail
                                   │
                                   └─▶ aclRoleRepository.save()

システム設定        ───▶   sw-system-config           ───▶  system_config テーブル
                           .saveAll()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.js | `src/Administration/Resources/app/administration/src/module/sw-users-permissions/index.js` | ソース | モジュール登録・ルート定義 |
| sw-users-permissions/index.js | `src/Administration/Resources/app/administration/src/module/sw-users-permissions/page/sw-users-permissions/index.js` | ソース | メインページロジック |
| sw-users-permissions.html.twig | `src/Administration/Resources/app/administration/src/module/sw-users-permissions/page/sw-users-permissions/sw-users-permissions.html.twig` | テンプレート | メインページテンプレート |
| sw-users-permissions-user-listing/index.js | `src/Administration/Resources/app/administration/src/module/sw-users-permissions/components/sw-users-permissions-user-listing/index.js` | ソース | ユーザー一覧コンポーネント |
| sw-users-permissions-role-listing/index.js | `src/Administration/Resources/app/administration/src/module/sw-users-permissions/components/sw-users-permissions-role-listing/index.js` | ソース | ロール一覧コンポーネント |
| sw-users-permissions-user-detail/index.js | `src/Administration/Resources/app/administration/src/module/sw-users-permissions/page/sw-users-permissions-user-detail/index.js` | ソース | ユーザー詳細ページ |
| sw-users-permissions-role-detail/index.js | `src/Administration/Resources/app/administration/src/module/sw-users-permissions/page/sw-users-permissions-role-detail/index.js` | ソース | ロール詳細ページ |
| sw-users-permissions-permissions-grid/index.js | `src/Administration/Resources/app/administration/src/module/sw-users-permissions/components/sw-users-permissions-permissions-grid/index.js` | ソース | 権限グリッドコンポーネント |
| acl/index.js | `src/Administration/Resources/app/administration/src/module/sw-users-permissions/acl/index.js` | ソース | 権限定義 |
