# 画面設計書 57-ルール設定

## 概要

本ドキュメントは、Shopware 6 管理画面におけるルール設定（sw-settings-rule）画面の設計書です。ECサイトで使用するビジネスルールの登録・編集・管理を行う画面について記述します。

### 本画面の処理概要

**業務上の目的・背景**：ECサイトにおいて、様々なビジネスロジック（配送方法の利用可能条件、支払方法の制限、プロモーションの適用条件など）を柔軟に定義するためのルールエンジンを提供します。本画面では、条件の組み合わせ（AND/OR）を視覚的に構築し、複雑なビジネスルールをコードなしで設定できます。

**画面へのアクセス方法**：管理画面にログイン後、左メニューの「設定」 > 「ルールビルダー」をクリックして一覧画面にアクセスします。一覧画面から新規作成ボタンまたは既存のルール名をクリックして詳細画面に遷移します。

**主要な操作・処理内容**：
1. ルール一覧の表示・検索・ソート・フィルタリング
2. 新規ルールの作成（ルール名、優先度、説明、条件の設定）
3. 既存ルールの編集
4. 条件ツリーの構築（AND/OR/XORグループ、各種条件タイプ）
5. ルールの複製
6. ルールの削除
7. ルールの割り当て管理

**画面遷移**：設定メニュー → ルール一覧画面 → ルール詳細画面（基本設定タブ/割り当てタブ）。詳細画面から一覧画面への戻り遷移も可能です。

**権限による表示制御**：`rule.viewer`権限で閲覧可能、`rule.editor`権限で編集可能、`rule.creator`権限で新規作成可能、`rule.deleter`権限で削除可能です。権限がない場合、該当するボタンやアクションは無効化されます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 36 | プロモーション管理 | 参照元 | プロモーション適用条件 |
| 54 | 配送設定 | 参照元 | 配送方法の利用可能条件 |
| 55 | 支払設定 | 参照元 | 支払方法の利用可能条件 |

## 画面種別

一覧 / 詳細 / 登録 / 編集

## URL/ルーティング

| 画面 | URL | コンポーネント |
|------|-----|---------------|
| ルール一覧 | `#/sw/settings/rule/index` | sw-settings-rule-list |
| ルール詳細（基本設定） | `#/sw/settings/rule/detail/:id/base` | sw-settings-rule-detail-base |
| ルール詳細（割り当て） | `#/sw/settings/rule/detail/:id/assignments` | sw-settings-rule-detail-assignments |
| ルール新規作成 | `#/sw/settings/rule/create/base` | sw-settings-rule-detail-base |

## 入出力項目

### 一覧画面

| 項目名 | 項目ID | 型 | 入力/出力 | 必須 | 説明 |
|--------|--------|-----|----------|------|------|
| 名前 | name | string | 入出力 | ○ | ルールの表示名 |
| 優先度 | priority | int | 入出力 | - | ルールの優先度 |
| 説明 | description | string | 出力 | - | ルールの説明 |
| 更新日 | updatedAt | datetime | 出力 | - | 最終更新日時 |
| 作成日 | createdAt | datetime | 出力 | - | 作成日時 |
| ステータス | invalid | boolean | 出力 | - | 無効な条件を含むかどうか |
| タグ | tags | relation | 出力 | - | 関連するタグ |

### 詳細画面 - 基本設定

| 項目名 | 項目ID | 型 | 入力/出力 | 必須 | 説明 |
|--------|--------|-----|----------|------|------|
| 名前 | name | string | 入力 | ○ | ルールの表示名 |
| 優先度 | priority | int | 入力 | ○ | ルールの優先度 |
| 説明 | description | text | 入力 | - | ルールの説明 |
| タグ | tags | relation | 入力 | - | 関連するタグ |
| 条件 | conditions | relation | 入力 | ○ | 条件ツリー |

## 表示項目

### 一覧画面

| 項目名 | 説明 |
|--------|------|
| ルール名 | ルールの表示名（詳細画面へのリンク） |
| 優先度 | ルールの優先度（数値） |
| 説明 | ルールの説明文 |
| 更新日 | 最終更新日時 |
| 作成日 | 作成日時 |
| ステータス | 有効/無効の状態（無効な条件を含む場合はバッジ表示） |
| タグ | 関連するタグのラベル |

### 詳細画面

| 項目名 | 説明 |
|--------|------|
| 基本設定タブ | ルール名、優先度、説明、タグ、条件ツリー |
| 割り当てタブ | ルールが使用されているエンティティ一覧 |

## イベント仕様

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

ユーザーが「保存」ボタンを押下すると、入力されたルール情報と条件ツリーがバリデーションされ、ruleリポジトリと条件リポジトリを通じてAPIに保存リクエストが送信されます。日付範囲条件のバリデーション（fromDate <= toDate）も実行されます。

### 2-キャンセルボタン押下

ユーザーが「キャンセル」ボタンを押下すると、変更を破棄してルール一覧画面に遷移します。未保存の変更がある場合は確認モーダルが表示されます。

### 3-複製ボタン押下

詳細画面または一覧画面で複製を実行すると、現在のルールがコピーされ、新しいルールが作成されます。名前には「コピー」が追加されます。

### 4-条件追加

条件ツリー内で「条件を追加」ボタンをクリックすると、条件選択モーダルが表示されます。条件タイプを選択し、必要なパラメータを入力します。

### 5-条件グループ追加

条件ツリー内で「AND/OR/XORグループを追加」ボタンをクリックすると、新しい条件グループが追加されます。グループタイプ（AND/OR/XOR）を選択できます。

### 6-条件削除

条件または条件グループの削除アイコンをクリックすると、該当する条件が条件ツリーから削除されます。deletedIdsに追加され、保存時にDBから削除されます。

### 7-フィルター適用

一覧画面で条件フィルター、グループフィルター、割り当てフィルター、タグフィルターを使用して、ルール一覧を絞り込むことができます。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | rule | INSERT/UPDATE | ルール情報の新規作成または更新 |
| 保存ボタン押下 | rule_condition | INSERT/UPDATE/DELETE | 条件ツリーの同期 |
| 保存ボタン押下 | rule_tag | INSERT/DELETE | タグの関連付け |
| 複製ボタン押下 | rule | INSERT | ルールの複製 |
| 複製ボタン押下 | rule_condition | INSERT | 条件の複製 |
| 削除ボタン押下 | rule | DELETE | ルールの削除 |

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

#### rule

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT/UPDATE | id | UUIDv4 | 新規作成時は自動生成 |
| INSERT/UPDATE | name | 入力値 | ルール名 |
| INSERT/UPDATE | priority | 入力値 | 優先度 |
| INSERT/UPDATE | description | 入力値 | 説明 |
| INSERT/UPDATE | invalid | 計算値 | 無効な条件を含むかどうか |

#### rule_condition

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT/UPDATE | id | UUIDv4 | 新規作成時は自動生成 |
| INSERT/UPDATE | rule_id | 親ルールのID | 外部キー |
| INSERT/UPDATE | parent_id | 親条件のID | 外部キー（グループ構造用） |
| INSERT/UPDATE | type | 条件タイプ | 条件の種類 |
| INSERT/UPDATE | value | JSON形式 | 条件のパラメータ値 |
| INSERT/UPDATE | position | 数値 | 条件の並び順 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|------------|------|--------------|----------|
| messageSaveSuccess | 成功 | ルール「{name}」が正常に保存されました | 保存成功時 |
| messageSaveError | エラー | ルールの保存中にエラーが発生しました | 保存失敗時 |
| INVALID_DATE_RANGE | エラー | 日付範囲が無効です（開始日は終了日以前である必要があります） | 日付範囲条件エラー時 |
| restrictedAssignment | 警告 | このルールは割り当てにより制限されています | ルール認識違反時 |

## 例外処理

| 例外ケース | 処理内容 |
|-----------|---------|
| ルールが見つからない | エラー通知を表示し、一覧画面にリダイレクト |
| 権限不足 | 該当するアクションボタンを無効化し、ツールチップで警告表示 |
| 通信エラー | エラー通知を表示し、ローディング状態を解除 |
| バリデーションエラー | 該当項目にエラー表示し、保存を中止 |
| 日付範囲エラー | INVALID_DATE_RANGEエラーを表示 |
| ルール認識違反 | equalsAnyViolationTooltipメッセージを表示 |
| 未保存変更離脱 | isDisplayingSaveChangesWarningモーダルを表示 |

## 備考

- 条件ツリーはネストされたAND/OR/XORグループで構成されます
- 条件タイプはruleConditionDataProviderServiceから提供されます
- ルール認識（Rule Awareness）により、割り当てられたエンティティに応じて使用可能な条件が制限されます
- 日付範囲条件（dateRange）はfromDate <= toDateのバリデーションが必要です
- アプリスクリプト条件（app_script_condition）を使用したカスタム条件も設定可能です
- 複製時はcreatedAtがnullに設定され、APIが新しい日付を設定します

---

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

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

### 推奨読解順序

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

ルールエンティティと条件ツリーの構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | RuleDefinition.php | `src/Core/Content/Rule/` | ルールエンティティの定義 |
| 1-2 | RuleConditionDefinition.php | `src/Core/Content/Rule/Aggregate/RuleCondition/` | 条件エンティティの定義 |

**読解のコツ**: 条件はparent_idを持つ再帰的なツリー構造になっています。

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

モジュール登録とルーティング設定を確認します。

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

**主要処理フロー**:
1. **39-123行目**: Module.registerでモジュール登録
2. **49-115行目**: routes定義（index, detail（子ルート含む）, create）
3. **117-122行目**: settingsItem定義（設定メニューへの追加、automationグループ）

#### Step 3: 一覧画面コンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-rule/page/sw-settings-rule-list/index.js` | 一覧画面のロジック |

**主要処理フロー**:
- **59-69行目**: conditionFilterOptions - 条件タイプフィルター
- **71-89行目**: groupFilterOptions - 条件グループフィルター
- **91-102行目**: associationFilterOptions - 割り当てフィルター
- **139-157行目**: listCriteria - ルール一覧取得条件
- **185-204行目**: getList() - ルール一覧の取得
- **253-305行目**: getRuleColumns() - グリッドカラム定義

#### Step 4: 詳細画面コンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-rule/page/sw-settings-rule-detail/index.js` | 詳細画面のロジック |

**主要処理フロー**:
- **231-244行目**: loadConditionData() - 条件データの読み込み
- **246-249行目**: createRule() - 新規ルール作成
- **251-263行目**: loadEntityData() - ルールデータの読み込み
- **336-362行目**: loadConditions() - 条件ツリーの読み込み
- **442-448行目**: validateDateRange() - 日付範囲バリデーション
- **450-502行目**: onSave() - 保存処理
- **526-535行目**: syncConditions() - 条件ツリーの同期

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

```
sw-settings-rule (モジュール)
    │
    ├─ sw-settings-rule-list (一覧画面)
    │      ├─ ruleRepository.search() - 一覧取得
    │      ├─ ruleRepository.clone() - 複製
    │      ├─ フィルター処理 (条件/グループ/割り当て/タグ)
    │      └─ inline-edit → ruleRepository.save()
    │
    └─ sw-settings-rule-detail (詳細画面)
           │
           ├─ sw-settings-rule-detail-base (基本設定タブ)
           │      ├─ ruleRepository.search() - 詳細取得
           │      ├─ conditionRepository.search() - 条件ツリー取得
           │      ├─ ruleConditionDataProviderService - 条件タイプ取得
           │      ├─ validateRuleAwareness() - ルール認識チェック
           │      ├─ validateDateRange() - 日付範囲バリデーション
           │      ├─ ruleRepository.save() - 保存
           │      └─ conditionRepository.sync() - 条件同期
           │
           └─ sw-settings-rule-detail-assignments (割り当てタブ)
                  └─ 各割り当てエンティティの一覧表示
```

### データフロー図

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

ルールフォーム ─────▶ sw-settings-rule-detail ────────▶ rule テーブル
                              │
条件ツリー入力 ────▶          ├─▶ validateRuleAwareness()
                              │     └─▶ 割り当て制約チェック
                              │
                              ├─▶ validateDateRange()
                              │     └─▶ 日付条件バリデーション
                              │
                              └─▶ ruleRepository.save()
                                  └─▶ conditionRepository.sync()
                                        │
                                        ▼
                              Admin API (/api/rule)
                                        │
                                        ▼
                              RuleRepository (PHP)
                                        │
                                        ├─▶ rule
                                        ├─▶ rule_condition
                                        └─▶ rule_tag
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-rule/index.js` | ソース | モジュール定義 |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-rule/page/sw-settings-rule-list/index.js` | ソース | 一覧画面ロジック |
| sw-settings-rule-list.html.twig | `src/Administration/Resources/app/administration/src/module/sw-settings-rule/page/sw-settings-rule-list/sw-settings-rule-list.html.twig` | テンプレート | 一覧画面UI |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-rule/page/sw-settings-rule-detail/index.js` | ソース | 詳細画面ロジック |
| sw-settings-rule-detail.html.twig | `src/Administration/Resources/app/administration/src/module/sw-settings-rule/page/sw-settings-rule-detail/sw-settings-rule-detail.html.twig` | テンプレート | 詳細画面UI |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-rule/view/sw-settings-rule-detail-base/index.js` | ソース | 基本設定タブ |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-rule/view/sw-settings-rule-detail-assignments/index.js` | ソース | 割り当てタブ |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-rule/acl/index.js` | ソース | 権限定義 |
