# 画面設計書 62-SEO設定

## 概要

本ドキュメントは、Shopware 6 管理画面（Administration）におけるSEO設定画面の設計を記述したものです。検索エンジン最適化（SEO）に関連するURL テンプレートやシステム設定を管理するための管理者向け設定画面です。

### 本画面の処理概要

SEO設定画面は、ストアフロントのSEO対策を管理するための画面です。商品ページ、カテゴリページ、ランディングページなどのSEOフレンドリーなURLパターンを定義し、検索エンジンでの表示を最適化するための設定を行います。

**業務上の目的・背景**：検索エンジン最適化はECサイトの集客において重要な要素です。適切なURL構造は、検索エンジンがページ内容を理解しやすくなり、検索結果での順位向上につながります。本画面では、商品・カテゴリ・その他のページに対してカスタマイズ可能なURLテンプレートを設定し、販売チャネルごとに異なるURL構造を定義することができます。

**画面へのアクセス方法**：管理画面にログイン後、左メニューの「設定」 > 「コンテンツ」セクション > 「SEO」をクリックしてアクセスします。URL パスは `#/sw/settings/seo/index` です。

**主要な操作・処理内容**：
1. **SEO URLテンプレートの設定**：商品詳細ページ、カテゴリページ、ランディングページなどのURLパターンを設定
2. **販売チャネル別設定**：販売チャネルごとに異なるURLテンプレートを定義
3. **テンプレート変数の使用**：商品名、カテゴリ名などの動的変数をテンプレートに挿入
4. **URLプレビュー**：設定したテンプレートで生成されるURLをリアルタイムでプレビュー
5. **システム設定**：core.seo ドメインの各種システム設定の変更

**画面遷移**：
- 遷移元：設定一覧画面（sw-settings-index）
- 遷移先：なし（設定画面のため）

**権限による表示制御**：
- `system.system_config`：SEO設定へのアクセスおよび編集が可能

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 64 | サイトマップ表示 | 補助機能 | SEO URL・メタ情報の設定 |

## 画面種別

設定

## URL/ルーティング

| 項目 | 値 |
|------|---|
| モジュール名 | sw-settings-seo |
| メインルート | sw.settings.seo.index |
| URLパス | #/sw/settings/seo/index |

## 入出力項目

### SEO URLテンプレート設定

| 項目名 | 項目ID | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| ルート名 | routeName | String | Yes | 対象ページのルート識別子（frontend.detail.page等） |
| テンプレート | template | String | No | SEO URLのパターン（Twigテンプレート形式） |
| 販売チャネルID | salesChannelId | UUID | No | 対象の販売チャネル（nullの場合はデフォルト） |
| エンティティ名 | entityName | String | Yes | 対象エンティティ（product, category等） |

### システム設定（core.seo ドメイン）

| 項目名 | 設定キー | 型 | 説明 |
|--------|---------|-----|------|
| 重複URLリダイレクト | core.seo.redirectToCanonicalUrl | Boolean | 重複URLを正規URLにリダイレクト |
| その他 | core.seo.* | 各種 | sw-system-config コンポーネントで自動表示 |

## 表示項目

### SEO URLテンプレートカード

| セクション | 表示項目 | 説明 |
|------------|----------|------|
| ヘッダー | 販売チャネル選択 | ドロップダウンで販売チャネルを選択 |
| テンプレート一覧 | ルート名ラベル | 各ページタイプの名称（商品詳細、カテゴリ等） |
| テンプレート一覧 | テンプレート入力フィールド | URLパターンの入力欄 |
| テンプレート一覧 | 変数選択ドロップダウン | 使用可能な変数の選択 |
| テンプレート一覧 | プレビュー | 生成されるURLのプレビュー表示 |
| テンプレート一覧 | エラーメッセージ | テンプレートエラー時のメッセージ |

### システム設定セクション

| セクション | 表示項目 | 説明 |
|------------|----------|------|
| システム設定 | 設定項目 | core.seo ドメインの設定項目（sw-system-config で自動生成） |

## イベント仕様

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

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

**処理フロー**:
1. `onClickSave` メソッドが実行される
2. `seoUrlTemplateCard.onClickSave()` でURLテンプレートを保存
3. `systemConfig.saveAll()` でシステム設定を保存
4. 成功時: 成功通知を表示
5. 失敗時: エラー通知を表示

**データフロー**:
```
ユーザー入力 → seoUrlTemplates → Repository.sync() → API → Database
                                   ↓
            systemConfig → SystemConfigService → API → Database
```

### 2-販売チャネル変更

**トリガー**: 販売チャネルドロップダウンの値変更

**処理フロー**:
1. `onSalesChannelChanged` が実行される
2. `fetchSeoUrlTemplates(salesChannelId)` で対象販売チャネルのテンプレートを取得
3. デフォルトテンプレートからの継承処理を実行
4. 各テンプレートのプレビューを更新

### 3-テンプレート入力

**トリガー**: テンプレートフィールドへの入力

**処理フロー**:
1. `onInput` が実行される
2. デバウンス処理（400ms）でプレビュー更新
3. `fetchSeoUrlPreview` でAPIからプレビュー取得
4. エラー時はエラーメッセージを表示

### 4-変数選択

**トリガー**: 変数ドロップダウンで変数を選択

**処理フロー**:
1. `onSelectInput` が実行される
2. 選択された変数をテンプレートに追加（`{{ 変数名 }}` 形式）
3. プレビューを更新

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| URLテンプレート保存 | seo_url_template | SYNC (INSERT/UPDATE/DELETE) | URLテンプレートの同期 |
| システム設定保存 | system_config | UPDATE/INSERT | core.seo.* 設定の保存 |

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

#### seo_url_template

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT/UPDATE | route_name | ルート名文字列 | ページタイプの識別子 |
| INSERT/UPDATE | template | URLパターン文字列 | Twig形式のテンプレート |
| INSERT/UPDATE | sales_channel_id | UUID | 対象販売チャネル |
| INSERT/UPDATE | entity_name | エンティティ名 | product, category等 |
| SELECT | sales_channel_id | パラメータ指定 | 販売チャネルでフィルタ |
| DELETE | template | null | テンプレートがnullの場合削除 |

#### system_config

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE/INSERT | configuration_key | core.seo.* | 設定キー |
| UPDATE/INSERT | configuration_value | 各種設定値 | JSON形式 |

## メッセージ仕様

| 種別 | メッセージキー | メッセージ内容 | 表示条件 |
|------|--------------|--------------|---------|
| 成功 | sw-seo-url-template-card.general.messageSaveSuccess | 設定が保存されました | 保存成功時 |
| エラー | sw-seo-url-template-card.general.messageSaveError | 設定の保存に失敗しました | 保存失敗時またはバリデーションエラー時 |
| エラー | （動的） | テンプレート構文エラーの詳細 | テンプレートにエラーがある場合 |

## 例外処理

| 例外状態 | 対応処理 | 画面表示 |
|---------|---------|---------|
| 権限不足 | 画面アクセス不可 | 設定メニューに表示されない |
| API通信エラー | エラー通知表示 | 「設定の保存に失敗しました」メッセージ |
| テンプレート構文エラー | プレビューAPIがエラーを返す | エラーメッセージをフィールド下に表示 |
| 対象エンティティなし | 警告表示 | プレビュー生成不可のメッセージ |
| Headless販売チャネル | 一部機能制限 | SEOテンプレートが不要な旨を表示 |

## 備考

- SEO URLテンプレートはTwig形式で記述します
- 販売チャネルごとに異なるURLパターンを設定できます
- デフォルト設定（販売チャネルID=null）は全販売チャネルの基本設定となります
- Headless販売チャネルの場合、SEO URLは使用されません
- テンプレート変数はエンティティごとに利用可能なものが異なります

---

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

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

### 推奨読解順序

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

まず、SEO URL テンプレートで使用されるエンティティ構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | SeoUrlTemplateDefinition | `src/Core/Content/Seo/SeoUrlTemplate/SeoUrlTemplateDefinition.php` | SEO URLテンプレートエンティティの定義 |

**読解のコツ**: Shopware 6 の DAL では、`Definition` クラスでエンティティのフィールドと関連を定義します。

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

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

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

**主要処理フロー**:
1. **6-9行目**: コンポーネントの遅延ロード登録
2. **15-42行目**: `Module.register` でモジュールを登録
3. **25-34行目**: ルート定義（index）
4. **36-41行目**: 設定メニューへの項目追加（contentグループ）

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

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

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

**主要処理フロー**:
- **24-27行目**: `onClickSave` で保存処理（テンプレートカードとシステム設定）
- **46-48行目（テンプレート）**: `sw-seo-url-template-card` コンポーネント参照
- **51-55行目（テンプレート）**: `sw-system-config` で core.seo ドメインの設定表示

#### Step 4: SEO URLテンプレートカードコンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | sw-seo-url-template-card/index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-seo/component/sw-seo-url-template-card/index.js` | URLテンプレートのCRUD操作 |

**主要処理フロー**:
- **70-92行目**: `createdComponent` で初期化（リポジトリ作成、データ取得）
- **93-134行目**: `fetchSeoUrlTemplates` でテンプレート取得
- **135-152行目**: `createSeoUrlTemplatesFromDefaultRoutes` でデフォルトからの継承
- **200-231行目**: `onClickSave` で保存処理
- **281-311行目**: `fetchSeoUrlPreview` でプレビュー取得
- **317-320行目**: `onSalesChannelChanged` で販売チャネル切り替え

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

```
sw-settings-seo (Page)
    │
    ├─ sw-seo-url-template-card (Component)
    │      ├─ seoUrlTemplateRepository
    │      │      └─ Repository API (CRUD)
    │      │
    │      ├─ seoUrlTemplateService
    │      │      ├─ getContext() [変数取得]
    │      │      └─ preview() [プレビュー生成]
    │      │
    │      └─ salesChannelRepository
    │             └─ Repository API (販売チャネル一覧)
    │
    └─ sw-system-config (Component)
           └─ SystemConfigService
                  └─ core.seo ドメインの設定
```

### データフロー図

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

販売チャネル選択    ───▶   sw-seo-url-template-card   ───▶  seo_url_template
                                   │                        (テンプレート一覧)
                                   ▼
テンプレート入力    ───▶   seoUrlTemplateService      ───▶  プレビューURL表示
                           .preview()
                                   │
                                   ▼
保存ボタン押下      ───▶   seoUrlTemplateRepository   ───▶  seo_url_template
                           .sync()                         (INSERT/UPDATE/DELETE)
                                   │
                                   ▼
                           sw-system-config          ───▶  system_config
                           .saveAll()                      (core.seo.*)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-seo/index.js` | ソース | モジュール登録・ルート定義 |
| sw-settings-seo/index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-seo/page/sw-settings-seo/index.js` | ソース | ページメインロジック |
| sw-settings-seo.html.twig | `src/Administration/Resources/app/administration/src/module/sw-settings-seo/page/sw-settings-seo/sw-settings-seo.html.twig` | テンプレート | ページテンプレート |
| sw-seo-url-template-card/index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-seo/component/sw-seo-url-template-card/index.js` | ソース | URLテンプレート管理コンポーネント |
| sw-seo-url-template-card.html.twig | `src/Administration/Resources/app/administration/src/module/sw-settings-seo/component/sw-seo-url-template-card/sw-seo-url-template-card.html.twig` | テンプレート | URLテンプレートカードテンプレート |
| sw-seo-url/index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-seo/component/sw-seo-url/index.js` | ソース | SEO URL表示コンポーネント |
| sw-seo-main-category/index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-seo/component/sw-seo-main-category/index.js` | ソース | メインカテゴリ選択コンポーネント |
| store.ts | `src/Administration/Resources/app/administration/src/module/sw-settings-seo/component/sw-seo-url/store.ts` | ソース | SEO URL状態管理 |
