# 通知設計書 36-Document Invoice

## 概要

本ドキュメントは、Shopwareにおける請求書（Invoice）ドキュメントを顧客に送付する際のメール通知の設計仕様を定義する。

### 本通知の処理概要

本通知は、注文の請求書ドキュメントが生成され、顧客にメールで送付される際に使用される通知である。管理画面から手動でドキュメントを送信する場合に利用される。

**業務上の目的・背景**：請求書は商取引において最も重要な法的書類の一つであり、支払いの根拠となる。電子的に請求書を送付することで、迅速な請求処理と顧客への情報提供が可能となる。また、顧客は請求書を会計処理や経費精算に利用できる。

**通知の送信タイミング**：管理画面の注文詳細ページで、管理者が「ドキュメントを送信」アクションを実行した際にメールが送信される。具体的には `sw-order-send-document-modal` コンポーネントで送信処理が行われる。

**通知の受信者**：注文を行った顧客のメールアドレス（`order.orderCustomer.email`）宛に送信される。管理画面から送信先を変更することも可能。

**通知内容の概要**：顧客の敬称・氏名、注文番号、請求書の添付ファイル、アクセシビリティ対応ドキュメント（a11yDocuments）へのリンク（存在する場合）が含まれる。

**期待されるアクション**：顧客は通知を受け取り、添付された請求書を確認する。支払いが必要な場合は請求書に基づいて支払いを行い、経費精算や会計処理に利用することが期待される。

## 通知種別

メール通知

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（管理画面からの手動送信） |
| 優先度 | 高 |
| リトライ | メール送信サービスの設定に依存 |

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

1. デフォルトでは注文顧客のメールアドレスが使用される
2. 管理画面のドキュメント送信モーダルで受信者を変更可能
3. 送信時に `mailService.sendMailTemplate` APIが使用される

## 通知テンプレート

### メール通知の場合

| 項目 | 内容 |
|-----|------|
| 送信元アドレス | 販売チャネル設定による |
| 送信元名称 | `{{ salesChannel.name }}` |
| 件名（英語） | New document for your order |
| 件名（ドイツ語） | Neues Dokument für Ihre Bestellung |
| 形式 | HTML/テキスト両対応 |

### 本文テンプレート

```html
<div style="font-family:arial; font-size:12px;">

    {% if order.orderCustomer.salutation %}{{ order.orderCustomer.salutation.translated.letterName ~ ' ' }}{% endif %}{{ order.orderCustomer.firstName }} {{ order.orderCustomer.lastName }},<br>
    <br>
    Attached to this email you will find the invoice for your order with the number: {{ order.orderNumber }}<br>
    <br>
    If you have any questions, do not hesitate to contact us.
    <br><br>

    {% if a11yDocuments %}
        For better accessibility we also provide an HTML version of the documents here:<br><br>
        {% for a11y in a11yDocuments %}
            {% set documentLink = rawUrl(
                'frontend.account.order.single.document.a11y',
                {
                    documentId: a11y.documentId,
                    deepLinkCode: a11y.deepLinkCode,
                    fileType: a11y.fileExtension,
                },
                salesChannel.domains|first.url
            )%}

            - <a href="{{ documentLink }}" target="_blank">{{ documentLink }}</a> <br>
        {% endfor %}<br>

        For data protection reasons the HTML version requires a login. <br><br>
        In case of a guest order, you can use your email address and postal code of the billing address.<br>
    {% endif %}
</div>
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| 請求書 | PDF | 常時 | 注文の請求書ドキュメント |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| order | 注文エンティティ | order テーブル | Yes |
| order.orderNumber | 注文番号 | order.order_number | Yes |
| order.orderCustomer | 注文顧客情報 | order_customer テーブル | Yes |
| salesChannel | 販売チャネル | sales_channel テーブル | Yes |
| document | ドキュメントエンティティ | document テーブル | Yes |
| a11yDocuments | アクセシビリティドキュメント | 動的生成 | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 画面操作 | ドキュメント送信ボタンクリック | 請求書ドキュメントが存在 | 管理画面の注文詳細でドキュメント送信時 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| ドキュメント未生成 | 請求書ドキュメントが生成されていない場合 |
| メールテンプレート未設定 | 対応するメールテンプレートが存在しない場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[管理画面でドキュメント送信ボタンクリック] --> B[sw-order-send-document-modal表示]
    B --> C[テンプレート選択/プレビュー]
    C --> D[送信ボタンクリック]
    D --> E[mailService.sendMailTemplate呼び出し]
    E --> F[請求書PDF添付処理]
    F --> G[AbstractMailService.send]
    G --> H{送信結果}
    H -->|成功| I[成功通知表示]
    H -->|失敗| J[エラー通知表示]
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| order | 注文情報取得 | 主要な注文データ |
| document | ドキュメント情報 | 添付ファイル |
| document_type | ドキュメントタイプ | invoice |
| mail_template | メールテンプレート | テンプレート本文 |
| mail_template_type | テンプレートタイプ | invoice_mail |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 送信失敗 | SMTPサーバー接続エラー等 | エラー通知表示 |
| ドキュメント取得エラー | PDFファイルが存在しない | エラー通知表示 |

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

- 請求書には顧客情報・金額情報が含まれるため、正しい宛先への送信が重要
- アクセシビリティドキュメントへのアクセスはログインまたはゲスト認証が必要

## 備考

- 本テンプレートタイプの技術名は `invoice_mail`
- MailTemplateTypesクラスで `MAILTYPE_DOCUMENT_INVOICE` として定義（行18）
- ドキュメントタイプマッピング: `invoice` -> `invoice_mail`

---

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | MailTemplateTypes.php | `src/Core/Content/MailTemplate/MailTemplateTypes.php` | テンプレートタイプの定数（行18: MAILTYPE_DOCUMENT_INVOICE = 'invoice_mail'） |

#### Step 2: 管理画面コンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.js | `src/Administration/Resources/app/administration/src/module/sw-order/component/sw-order-send-document-modal/index.js` | ドキュメント送信モーダルの実装（行116: invoice -> invoice_mail） |

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

```
sw-order-send-document-modal（管理画面コンポーネント）
    │
    └─ onSendDocument()
           │
           └─ mailService.sendMailTemplate()
                  │
                  └─ AbstractMailService::send()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| MailTemplateTypes.php | `src/Core/Content/MailTemplate/MailTemplateTypes.php` | ソース | テンプレートタイプ定義 |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-order/component/sw-order-send-document-modal/index.js` | ソース | ドキュメント送信モーダル |
| en-html.html.twig | `src/Core/Migration/Fixtures/mails/invoice_mail/en-html.html.twig` | テンプレート | 英語HTMLテンプレート |
| de-html.html.twig | `src/Core/Migration/Fixtures/mails/invoice_mail/de-html.html.twig` | テンプレート | ドイツ語HTMLテンプレート |
