# 通知設計書 41-SEPA Confirmation

## 概要

本ドキュメントは、ShopwareにおけるSEPA（Single Euro Payments Area）決済確認メールの通知仕様を定義する設計書である。SEPA口座振替決済を選択した顧客に対して、決済確認の詳細情報を含むメール通知を送信する機能について記載する。

### 本通知の処理概要

本通知は、SEPA（単一ユーロ決済圏）口座振替決済を選択した顧客に対して送信される確認メールである。SEPA決済は欧州における銀行口座振替の標準化された方式であり、顧客の銀行口座から直接引き落としを行う決済手段として広く利用されている。

**業務上の目的・背景**：SEPA口座振替決済は、顧客の銀行口座から直接引き落としを行う決済方式であるため、法的要件として決済の詳細（引き落とし金額、口座情報、マンデート参照番号等）を顧客に書面で通知する必要がある。この通知は、EU決済サービス指令（PSD2）に準拠し、消費者保護の観点から顧客に決済内容を明確に伝えることを目的としている。

**通知の送信タイミング**：SEPA決済が確定した時点、具体的には注文完了時にSEPA決済方法が選択されている場合に送信される。Flowビルダーを通じて、注文イベント（checkout.order.placed）に連動して自動送信されるよう設定可能である。

**通知の受信者**：決済を行った顧客本人のメールアドレスに送信される。顧客の注文情報に紐づくメールアドレスが使用される。

**通知内容の概要**：引き落とし予定金額、SEPA口座振替の詳細（IBAN、BIC等のマスク表示）、マンデート参照番号、引き落とし予定日、キャンセルや異議申し立てに関する情報などが含まれる。

**期待されるアクション**：顧客は通知内容を確認し、引き落としに備えて口座残高を確保する。内容に誤りがある場合は、定められた期間内に異議申し立てを行うことができる。

## 通知種別

メール通知

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 非同期（Flowビルダー経由） |
| 優先度 | 高（法的要件のため） |
| リトライ | 有・3回 |

### 送信先決定ロジック

注文に紐づく顧客のメールアドレスを使用する。顧客エンティティのemail属性、または注文時に入力されたメールアドレスが使用される。

## 通知テンプレート

### メール通知の場合

| 項目 | 内容 |
|-----|------|
| 送信元アドレス | システム設定 `core.basicInformation.email` |
| 送信元名称 | 販売チャネル設定のショップ名 |
| 件名 | SEPA決済確認（カスタマイズ可能） |
| 形式 | HTML/テキスト |

### 本文テンプレート

```twig
<div style="font-family:arial; font-size:12px;">
    <p>
        SEPA口座振替のご確認<br/>
        <br/>
        注文番号: {{ order.orderNumber }}<br/>
        引き落とし金額: {{ order.amountTotal|currency(order.currency.isoCode) }}<br/>
        <br/>
        SEPA口座振替の詳細については、ご利用の金融機関にお問い合わせください。<br/>
    </p>
</div>
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| SEPA Mandate | PDF | オプション | SEPA委任状のコピー（設定に応じて添付） |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| order | 注文エンティティ | order テーブル | Yes |
| order.orderNumber | 注文番号 | order.order_number | Yes |
| order.amountTotal | 合計金額 | order.amount_total | Yes |
| order.currency | 通貨情報 | currency テーブル | Yes |
| salesChannel | 販売チャネル情報 | sales_channel テーブル | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| Flowアクション | checkout.order.placed | 決済方法がSEPA | 注文完了時にSEPA決済が選択されている場合 |
| Flowアクション | order_transaction.state.paid | 決済方法がSEPA | 決済完了時（オプション） |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 決済方法がSEPA以外 | SEPA口座振替以外の決済方法の場合は送信しない |
| テストモード | ステージング環境では送信を抑制可能 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[注文完了イベント発生] --> B{決済方法がSEPA?}
    B -->|Yes| C[Flowトリガー発火]
    B -->|No| D[送信スキップ]
    C --> E[SendMailAction実行]
    E --> F[テンプレート取得]
    F --> G[変数展開]
    G --> H[メール送信]
    H --> I{送信結果}
    I -->|成功| J[送信ログ記録]
    I -->|失敗| K[リトライ処理]
    J --> L[終了]
    K --> L
    D --> L
```

## データベース参照・更新仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| order | 注文情報取得 | 決済金額、注文番号等 |
| order_customer | 顧客情報取得 | メールアドレス取得 |
| payment_method | 決済方法判定 | SEPA決済の判定 |
| mail_template | テンプレート取得 | sepa_confirmation |
| mail_template_type | テンプレートタイプ | technical_name = 'sepa_confirmation' |

### テーブル別参照項目詳細

#### mail_template_type

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| id | テンプレートタイプID | technical_name = 'sepa_confirmation' |
| technical_name | 技術名 | 定数参照 |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| log_entry | INSERT | 送信ログ記録（Monolog経由） |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 送信失敗 | SMTPサーバー接続エラー | リトライ後、エラーログ記録 |
| テンプレートエラー | Twigレンダリング失敗 | MailErrorEvent発火、エラーログ |
| 宛先不正 | メールアドレス形式不正 | バリデーションエラー |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 3回 |
| リトライ間隔 | 指数バックオフ |
| リトライ対象エラー | 一時的な送信エラー |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | システム設定に依存 |
| 1日あたり上限 | 制限なし |

### 配信時間帯

制限なし（法的要件により即座に送信）

## セキュリティ考慮事項

- SEPA口座情報（IBAN、BIC）はマスク処理して表示
- メール内容は暗号化されていないため、詳細な口座情報は含めない
- 個人情報保護法（GDPR）に準拠した情報取り扱い

## 備考

- SEPA決済はヨーロッパ圏で主に使用される決済方式
- MailTemplateTypes::MAILTYPE_SEPA_CONFIRMATION 定数で定義
- Flowビルダーで送信条件をカスタマイズ可能

---

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

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

### 推奨読解順序

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

SEPA確認メールで使用されるテンプレートタイプ定数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | MailTemplateTypes.php | `src/Core/Content/MailTemplate/MailTemplateTypes.php` | MAILTYPE_SEPA_CONFIRMATION定数（50行目）の定義を確認 |

**読解のコツ**: PHPの定数定義ファイルで、各メールテンプレートタイプの技術名が定義されている。sepa_confirmationが本通知の技術名。

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

メール送信の起点となるFlowアクションを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | SendMailAction.php | `src/Core/Content/Flow/Dispatching/Action/SendMailAction.php` | handleFlow()メソッド（86行目〜）でメール送信処理が実行される |

**主要処理フロー**:
1. **86-95行目**: Flow設定の取得とスキップ条件チェック
2. **100-111行目**: MailAwareデータの存在チェックとテンプレートID取得
3. **113-117行目**: メールテンプレートの取得
4. **126-134行目**: 受信者の決定
5. **175行目**: send()メソッド呼び出しでメール送信実行

#### Step 3: メール送信処理を理解する

実際のメール送信ロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | MailService.php | `src/Core/Content/Mail/Service/MailService.php` | send()メソッド（62行目〜）でイベント発火とメール送信 |

**主要処理フロー**:
- **64-68行目**: MailBeforeValidateEvent発火
- **73行目**: バリデーション実行
- **75行目**: メール作成
- **103-107行目**: MailBeforeSentEvent発火
- **110行目**: メール送信実行
- **123-129行目**: MailSentEvent発火

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

```
Flow Engine (trigger: checkout.order.placed)
    │
    ├─ SendMailAction::handleFlow()
    │      │
    │      ├─ getMailTemplate() - テンプレート取得
    │      │
    │      ├─ getRecipients() - 受信者決定
    │      │
    │      └─ send()
    │             │
    │             └─ MailService::send()
    │                    │
    │                    ├─ MailBeforeValidateEvent dispatch
    │                    │
    │                    ├─ createMail() - メール作成
    │                    │
    │                    ├─ MailBeforeSentEvent dispatch
    │                    │
    │                    ├─ MailSender::send() - 実送信
    │                    │
    │                    └─ MailSentEvent dispatch
```

### データフロー図

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

Order Entity ──────────────▶ SendMailAction ──────────────────▶ SEPA Confirmation Email
  │                               │
  ├─ orderNumber                  ├─ テンプレート取得
  ├─ amountTotal                  ├─ 変数展開
  └─ customer.email               └─ メール送信
                                      │
                                      ▼
                                 MailService
                                      │
                                      ├─ MailBeforeValidateEvent
                                      ├─ MailBeforeSentEvent
                                      └─ MailSentEvent
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| MailTemplateTypes.php | `src/Core/Content/MailTemplate/MailTemplateTypes.php` | ソース | テンプレートタイプ定数定義 |
| SendMailAction.php | `src/Core/Content/Flow/Dispatching/Action/SendMailAction.php` | ソース | Flowメール送信アクション |
| MailService.php | `src/Core/Content/Mail/Service/MailService.php` | ソース | メール送信サービス |
| Migration1536233560BasicData.php | `src/Core/Migration/V6_3/Migration1536233560BasicData.php` | マイグレーション | SEPA確認テンプレートタイプ登録 |
| Migration1617000878AddTemplateDataToMailTemplateType.php | `src/Core/Migration/V6_4/Migration1617000878AddTemplateDataToMailTemplateType.php` | マイグレーション | テンプレートデータ追加 |
