# 画面設計書 55-支払設定

## 概要

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

### 本画面の処理概要

**業務上の目的・背景**：ECサイトにおいて、顧客に多様な支払オプションを提供することは販売機会の最大化に不可欠です。本画面では、支払方法の基本情報、利用可能条件（ルール）、対象の販売チャネル、有効/無効状態を管理することで、柔軟な支払環境を構築できます。

**画面へのアクセス方法**：管理画面にログイン後、左メニューの「設定」 > 「支払方法」をクリックして一覧画面にアクセスします。一覧画面から既存の支払方法名をクリックして詳細画面に遷移します。

**主要な操作・処理内容**：
1. 支払方法一覧の表示・検索・ソート
2. 既存支払方法の編集（名前、説明、ロゴ、利用可能ルール）
3. 支払方法の有効/無効切り替え
4. 支払方法の並び替え（ドラッグ&ドロップ）
5. 技術名の設定（プラグイン/アプリ以外の場合）
6. 支払方法の削除

**画面遷移**：設定メニュー → 支払方法一覧画面（overview） → 支払方法詳細画面。詳細画面から一覧画面への戻り遷移も可能です。

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 37 | チェックアウト | 参照元 | 支払方法の選択 |

## 画面種別

一覧 / 詳細 / 編集

## URL/ルーティング

| 画面 | URL | コンポーネント |
|------|-----|---------------|
| 支払方法一覧 | `#/sw/settings/payment/overview` | sw-settings-payment-overview |
| 支払方法詳細 | `#/sw/settings/payment/detail/:id` | sw-settings-payment-detail |
| 支払方法新規作成 | `#/sw/settings/payment/create` | sw-settings-payment-create |

## 入出力項目

### 一覧画面

| 項目名 | 項目ID | 型 | 入力/出力 | 必須 | 説明 |
|--------|--------|-----|----------|------|------|
| 名前 | name | string | 出力 | - | 支払方法の表示名 |
| 有効 | active | boolean | 出力 | - | 有効/無効状態 |
| 位置 | position | int | 入力 | - | 表示順序（ドラッグで変更） |
| プラグイン | plugin | relation | 出力 | - | 関連するプラグイン |

### 詳細画面

| 項目名 | 項目ID | 型 | 入力/出力 | 必須 | 説明 |
|--------|--------|-----|----------|------|------|
| 名前 | name | string | 入力 | ○ | 支払方法の表示名 |
| 技術名 | technicalName | string | 入力 | 条件付 | 技術的識別名（プラグイン/アプリ以外で必須） |
| 有効 | active | boolean | 入力 | - | 有効/無効状態 |
| ロゴ | mediaId | uuid | 入力 | - | 支払方法のロゴ画像 |
| 説明 | description | text | 入力 | - | 支払方法の説明 |
| 利用可能ルール | availabilityRuleId | uuid | 入力 | - | 利用可能条件を定義するルール |

## 表示項目

### 一覧画面

| 項目名 | 説明 |
|--------|------|
| 支払方法名 | 支払方法の表示名（詳細画面へのリンク） |
| アクティブ | 有効/無効状態（トグル） |
| プラグイン | 関連するプラグイン名（存在する場合） |
| アクション | 編集・削除ボタン |

### 詳細画面

| 項目名 | 説明 |
|--------|------|
| 基本情報 | 名前、技術名、有効状態、ロゴ、説明 |
| 利用可能ルール | 支払方法の利用可能条件を定義するルール選択 |
| カスタムフィールド | カスタムフィールドセットが定義されている場合に表示 |

## イベント仕様

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

ユーザーが「保存」ボタンを押下すると、入力された支払方法情報がバリデーションされ、paymentMethodリポジトリを通じてAPIに保存リクエストが送信されます。保存成功時は成功通知が表示され、ローディング状態が解除されます。

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

ユーザーが「キャンセル」ボタンを押下すると、変更を破棄して支払方法一覧画面に遷移します。

### 3-削除ボタン押下

一覧画面または詳細画面で削除を実行すると、削除確認モーダルが表示されます。確認後、paymentMethodリポジトリのdeleteメソッドを通じて支払方法が削除されます。ただし、注文取引、販売チャネル、顧客に関連付けられている場合は削除できません。

### 4-ルール選択・保存

利用可能ルールを選択すると、availabilityRuleIdが更新されます。ルール作成ボタンからルールを新規作成することも可能です。

### 5-ルール解除

「ルールを解除」を実行すると、availabilityRuleIdがnullに設定されます。

### 6-メディアアップロード

ロゴ画像をドラッグ&ドロップまたはファイル選択でアップロードします。メディアサイドバーからも選択可能です。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | payment_method | INSERT/UPDATE | 支払方法情報の新規作成または更新 |
| 保存ボタン押下 | payment_method_translation | INSERT/UPDATE | 支払方法の翻訳情報 |
| 削除ボタン押下 | payment_method | DELETE | 支払方法の削除 |

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

#### payment_method

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT/UPDATE | id | UUIDv4 | 新規作成時は自動生成 |
| INSERT/UPDATE | name | 入力値 | 支払方法名 |
| INSERT/UPDATE | technical_name | 入力値 | 技術的識別名 |
| INSERT/UPDATE | active | 入力値 | 有効/無効フラグ |
| INSERT/UPDATE | media_id | 選択値 | ロゴメディアへの外部キー |
| INSERT/UPDATE | availability_rule_id | 選択値 | 利用可能ルールへの外部キー |
| INSERT/UPDATE | position | 入力値 | 表示順序 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|------------|------|--------------|----------|
| messageSaveSuccess | 成功 | 支払方法が正常に保存されました | 保存成功時 |
| messageSaveError | エラー | 支払方法「{name}」の保存中にエラーが発生しました | 保存失敗時 |
| privileges.tooltip.warning | 警告 | この操作を実行する権限がありません | 権限不足時 |

## 例外処理

| 例外ケース | 処理内容 |
|-----------|---------|
| 支払方法が見つからない | エラー通知を表示し、一覧画面にリダイレクト |
| 権限不足 | 該当するアクションボタンを無効化し、ツールチップで警告表示 |
| 通信エラー | エラー通知を表示し、ローディング状態を解除 |
| バリデーションエラー | 該当項目にエラー表示し、保存を中止 |
| 使用中の支払方法削除 | forbidDeleteフラグにより削除ボタンを無効化 |
| 注文取引との関連 | 削除不可（orderTransactions.length !== 0） |
| 販売チャネルとの関連 | 削除不可（salesChannels.length !== 0） |
| 顧客との関連 | 削除不可（customers.length !== 0） |

## 備考

- 技術名（technicalName）はプラグインまたはアプリによって提供される支払方法では自動設定されます
- 技術名が自動設定されている場合（technicalNameIsProvided = true）、編集画面で技術名フィールドは読み取り専用となります
- 支払方法は以下の条件に該当する場合、削除できません：
  - 注文取引（orderTransactions）に関連付けられている
  - 販売チャネル（salesChannels）に関連付けられている
  - 販売チャネルのデフォルト支払方法として設定されている
  - 顧客（customers）に関連付けられている
- カスタムフィールドセットが定義されている場合、詳細画面にカスタムフィールドセクションが表示されます

---

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

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

### 推奨読解順序

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

支払方法エンティティとその関連データの構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | PaymentMethodDefinition.php | `src/Core/Checkout/Payment/` | 支払方法エンティティの定義 |
| 1-2 | RuleDefinition.php | `src/Core/Content/Rule/` | ルールエンティティとの関連 |

**読解のコツ**: 支払方法は利用可能ルール（availabilityRuleId）との関連が重要です。

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

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

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

**主要処理フロー**:
1. **Module.register**: モジュール登録
2. **routes**: overview, detail, createの定義
3. **settingsItem**: 設定メニューへの追加（shopグループ）

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

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

**主要処理フロー**:
- **paymentMethodCriteria**: 支払方法一覧取得条件
- **pluginsPaymentMethods/otherPaymentMethods**: プラグイン提供とその他の支払方法の分類
- **getList()**: 支払方法一覧の取得
- **sortableGroupChange()**: ドラッグ&ドロップによる並び替え

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

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

**主要処理フロー**:
- **163-168行目**: createdComponent() - 初期化処理
- **190-207行目**: loadEntityData() - 支払方法データの読み込み
- **220-238行目**: onSave() - 保存処理
- **170-177行目**: onSaveRule() - ルール選択処理
- **131-139行目**: forbidDelete - 削除可否判定

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

```
sw-settings-payment (モジュール)
    │
    ├─ sw-settings-payment-overview (一覧画面)
    │      ├─ paymentMethodRepository.search() - 一覧取得
    │      ├─ pluginsPaymentMethods/otherPaymentMethods 分類
    │      └─ paymentMethodRepository.save() - 並び替え保存
    │
    └─ sw-settings-payment-detail (詳細画面)
           ├─ paymentMethodRepository.search() - 詳細取得（関連含む）
           ├─ paymentMethodRepository.create() - 新規作成
           ├─ paymentMethodRepository.save() - 保存
           ├─ paymentMethodRepository.delete() - 削除
           └─ ruleRepository - ルール選択
```

### データフロー図

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

支払方法フォーム ────▶ sw-settings-payment-detail ───▶ payment_method テーブル
                              │
ルール選択 ────────▶          ├─▶ バリデーション
                              │     └─▶ forbidDelete チェック
                              │
                              └─▶ paymentMethodRepository.save()
                                        │
                                        ▼
                              Admin API (/api/payment-method)
                                        │
                                        ▼
                              PaymentMethodRepository (PHP)
                                        │
                                        ├─▶ payment_method
                                        └─▶ payment_method_translation
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-payment/index.js` | ソース | モジュール定義 |
| index.ts | `src/Administration/Resources/app/administration/src/module/sw-settings-payment/page/sw-settings-payment-overview/index.ts` | ソース | 一覧画面ロジック |
| sw-settings-payment-overview.html.twig | `src/Administration/Resources/app/administration/src/module/sw-settings-payment/page/sw-settings-payment-overview/sw-settings-payment-overview.html.twig` | テンプレート | 一覧画面UI |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-payment/page/sw-settings-payment-detail/index.js` | ソース | 詳細画面ロジック |
| sw-settings-payment-detail.html.twig | `src/Administration/Resources/app/administration/src/module/sw-settings-payment/page/sw-settings-payment-detail/sw-settings-payment-detail.html.twig` | テンプレート | 詳細画面UI |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-payment/acl/index.js` | ソース | 権限定義 |
