# 画面設計書 36-プロパティ管理

## 概要

本ドキュメントは、Shopware 6 管理画面（Administration）のプロパティ管理画面の設計仕様を定義します。この画面はプロパティグループ（サイズ、色など）とそのオプション値を管理するための機能を提供し、商品のバリアントやフィルタリング条件として使用されるプロパティを作成・編集します。

### 本画面の処理概要

**業務上の目的・背景**：プロパティ管理画面は、商品の属性（色、サイズ、素材など）を体系的に管理するための機能です。プロパティは商品バリアントの生成、商品フィルタ機能、商品比較機能などで使用されます。適切なプロパティ設定により、顧客が商品を絞り込みやすくなり、購買体験が向上します。

**画面へのアクセス方法**：左側メインナビゲーションの「カタログ」>「プロパティ」をクリックしてアクセスします。URLパスは `/admin#/sw/property/index` です。権限 `property.viewer` が必要です。

**主要な操作・処理内容**：
1. プロパティグループ一覧の表示：ページネーション付きでプロパティグループを一覧表示
2. プロパティグループ検索：キーワードによる検索
3. 並び替え：名前（デフォルト昇順）でソート
4. インライン編集：一覧上で直接グループ名、フィルタ可否を編集
5. オプション値のプレビュー：各グループの最初の5個のオプションを表示
6. プロパティグループ詳細編集：詳細ページでの編集
7. プロパティグループ削除：不要グループの削除（商品使用チェック付き）
8. 言語切替：表示言語の変更

**画面遷移**：プロパティグループ名をクリックするとプロパティグループ詳細編集画面に遷移します。「新規プロパティ」ボタンでプロパティグループ作成画面に遷移します。

**権限による表示制御**：
- `property.viewer`: プロパティ一覧の閲覧
- `property.editor`: インライン編集、オプション編集
- `property.creator`: 新規プロパティグループ作成ボタンの表示
- `property.deleter`: 削除ボタンの表示

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | プロパティ管理 | 主機能 | プロパティグループ・オプションの一覧表示・管理 |

## 画面種別

一覧

## URL/ルーティング

- **URLパス**: `/admin#/sw/property/index`
- **エイリアス**: `/admin#/sw/property`
- **ルート名**: `sw.property.index`
- **モジュール名**: `sw-property`
- **エンティティ**: `property_group`

### サブルート

| ルート名 | パス | コンポーネント | 説明 |
|---------|------|---------------|------|
| sw.property.create | `/create` | sw-property-create | 新規プロパティグループ作成 |
| sw.property.detail | `/detail/:id` | sw-property-detail | プロパティグループ詳細編集 |
| sw.property.option | `/detail/:groupId/option/:optionId` | sw-property-option-detail | オプション詳細編集 |

## 入出力項目

### 検索入力項目

| 項目名 | 項目ID | 入力形式 | 説明 |
|--------|--------|----------|------|
| 検索キーワード | term | テキスト | プロパティグループ名で検索 |

## 表示項目

### 一覧カラム

| 項目名 | property | 表示形式 | インライン編集 | デフォルト表示 | 説明 |
|--------|----------|----------|---------------|---------------|------|
| プロパティグループ名 | name | テキスト+リンク | 可（string） | Yes | 詳細へのリンク |
| オプション | options | チップリスト | - | Yes | 最初の5個のオプション値 |
| 説明 | description | テキスト | - | Yes | グループの説明 |
| フィルタ可 | filterable | チェックボックス | 可（boolean） | Yes | ストアフロントでのフィルタ表示 |

## イベント仕様

### 1-プロパティグループ一覧取得（getList）

画面表示時および検索・ページング変更時に実行：

1. `defaultCriteria` に基づいてクエリを構築
2. オプションのアソシエーションを追加（limit: 5）
3. 検索条件がある場合はクエリスコアを追加
4. 新しい検索キーワードの場合はソートをリセット
5. プロパティリポジトリで検索を実行
6. 結果を `propertyGroup` に格納、`total` を更新

### 2-プロパティグループ削除確認（onConfirmDelete）

削除確認時の処理：

1. 削除対象IDを取得
2. **商品使用チェック**：対象プロパティが商品で使用されているか確認
   - `options.groupId`、`properties.groupId`、`configuratorSettings.option.groupId` を検索
3. 使用中の場合：エラー通知を表示、削除中止
4. 未使用の場合：削除を実行、一覧を再取得

### 3-言語切替（onChangeLanguage）

表示言語を変更した際の処理：

1. `getList()` を呼び出して一覧を再取得

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 一覧表示 | property_group | SELECT | プロパティグループ一覧の取得 |
| 一覧表示 | property_group_option | SELECT | オプションプレビューの取得 |
| インライン編集 | property_group | UPDATE | プロパティグループ情報の更新 |
| 削除チェック | product | SELECT | 商品使用状況の確認 |
| 削除 | property_group | DELETE | プロパティグループの削除 |

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

#### property_group

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, name, description, filterable | ページネーション、ソート条件 | 一覧取得 |
| UPDATE | name, filterable | インライン編集値 | インライン編集時 |

## メッセージ仕様

| メッセージID | 種別 | 表示条件 | メッセージ内容 |
|-------------|------|----------|--------------|
| sw-property.list.errorDelete | エラー | 商品使用中で削除不可 | このプロパティは商品で使用されているため削除できません |
| global.default.error | エラー | 削除失敗 | エラーが発生しました |

## 例外処理

| 例外種別 | 発生条件 | 処理内容 |
|---------|---------|---------|
| 検索結果なし | 条件に一致するプロパティなし | 空の状態を表示 |
| 削除制約エラー | 商品に使用されているプロパティ | カスタムエラーメッセージ表示 |
| インライン編集エラー | バリデーション失敗 | エラー通知表示 |

## 備考

- デフォルトソートは名前の昇順（ASC）
- オプションのプレビューは最初の5件のみ表示
- 削除前に商品使用チェックを実施（製品設定、プロパティ、バリアント設定）
- `useNaturalSorting` は名前カラムのみ適用

---

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

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

### 推奨読解順序

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

プロパティグループとオプションの構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | default-search-configuration.js | `src/Administration/Resources/app/administration/src/module/sw-property/default-search-configuration.js` | 検索対象フィールドの設定 |

**読解のコツ**: プロパティは `property_group`（グループ）と `property_group_option`（オプション値）の2階層構造です。グループが「サイズ」、オプションが「S」「M」「L」のような関係です。

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

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

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

**主要処理フロー**:
1. **20行目**: `Module.register('sw-property', {...})` でモジュール登録
2. **32-42行目**: `routes.index` で一覧ページのルーティング定義
3. **40行目**: `meta.privilege: 'property.viewer'` で閲覧権限を設定
4. **66-74行目**: `routes.option` でオプション詳細のルーティング定義
5. **76-85行目**: ナビゲーションメニューの定義

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

プロパティ一覧ページのメインロジックを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.js | `src/Administration/Resources/app/administration/src/module/sw-property/page/sw-property-list/index.js` | 一覧表示のdata、computed、methodsの実装 |

**主要処理フロー**:
- **25-33行目**: `data()` で状態変数を定義
- **43-45行目**: `propertyRepository` でプロパティリポジトリを取得
- **47-56行目**: `defaultCriteria` でクエリ条件を構築（オプションを5件取得）
- **76-90行目**: `usePropertyCriteria` で商品使用チェック用クエリを作成
- **92-114行目**: `onConfirmDelete` で削除確認処理（商品使用チェック含む）
- **120-147行目**: `getList()` でプロパティデータを取得
- **149-177行目**: `getPropertyColumns()` で一覧カラムを定義

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

```
sw-property (モジュール)
    |
    +-- sw-property-list (一覧ページコンポーネント)
           |
           +-- getList()
           |      +-- addQueryScores()
           |      +-- propertyRepository.search(criteria)
           |
           +-- onDelete(id)
           |      +-- showDeleteModal = id
           |
           +-- onConfirmDelete(id)
           |      +-- productRepository.searchIds(usePropertyCriteria)
           |      +-- [商品使用中] → createNotificationError()
           |      +-- [未使用] → propertyRepository.delete()
           |                      → getList()
           |
           +-- onChangeLanguage()
                  +-- getList()
```

### データフロー図

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

検索キーワード  ───▶      sw-property-list           ───▶   プロパティ一覧表示
ページ番号                ・defaultCriteria構築              オプションプレビュー
                          ・propertyRepository.search()

削除ボタン     ───▶       onConfirmDelete             ───▶   削除結果
                          ・productRepository.searchIds()     または
                          ・[未使用] propertyRepository.delete()  エラー通知
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.js | `src/Administration/Resources/app/administration/src/module/sw-property/index.js` | ソース | モジュール登録・ルーティング定義 |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-property/page/sw-property-list/index.js` | ソース | 一覧ページのメインロジック |
| sw-property-list.html.twig | `src/Administration/Resources/app/administration/src/module/sw-property/page/sw-property-list/sw-property-list.html.twig` | テンプレート | 一覧ページのHTMLテンプレート |
| sw-property-detail | `src/Administration/Resources/app/administration/src/module/sw-property/page/sw-property-detail/` | ソース | 詳細ページコンポーネント |
| sw-property-option-detail | `src/Administration/Resources/app/administration/src/module/sw-property/component/sw-property-option-detail/` | ソース | オプション詳細コンポーネント |
| sw-property-option-list | `src/Administration/Resources/app/administration/src/module/sw-property/component/sw-property-option-list/` | ソース | オプション一覧コンポーネント |
