# 通知設計書 35-Document Delivery Note

## 概要

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

### 本通知の処理概要

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

**業務上の目的・背景**：納品書は商品の出荷と受け取りを証明する重要な書類であり、顧客に配送される商品の明細を提供する。電子的に納品書を送付することで、紙の書類に頼らず効率的に顧客へ情報を提供できる。また、顧客は受け取った商品と納品書を照合し、正確な配送が行われたことを確認できる。

**通知の送信タイミング**：管理画面の注文詳細ページで、管理者が「ドキュメントを送信」アクションを実行した際にメールが送信される。具体的には `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 delivery note 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 |
| order.orderCustomer.salutation | 敬称 | salutation テーブル | No |
| order.orderCustomer.firstName | 名 | order_customer.first_name | Yes |
| order.orderCustomer.lastName | 姓 | order_customer.last_name | Yes |
| salesChannel | 販売チャネル | sales_channel テーブル | Yes |
| salesChannel.name | 販売チャネル名 | sales_channel_translation.name | 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[ドキュメント添付処理]
    F --> G[AbstractMailService.send]
    G --> H{送信結果}
    H -->|成功| I[成功通知表示]
    H -->|失敗| J[エラー通知表示]
    I --> K[モーダルクローズ]
    J --> K
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| order | 注文情報取得 | 主要な注文データ |
| order_customer | 顧客情報取得 | 受信者情報 |
| document | ドキュメント情報 | 添付ファイル |
| document_type | ドキュメントタイプ | delivery_note |
| sales_channel | 販売チャネル | 送信元情報 |
| mail_template | メールテンプレート | テンプレート本文 |
| mail_template_type | テンプレートタイプ | delivery_mail |

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

#### document

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| id | ドキュメント識別 | document.id = :documentId |
| document_type_id | ドキュメントタイプ | 同上 |
| document_media_file_id | PDFファイル | 同上 |
| deep_link_code | アクセス用コード | 同上 |

#### mail_template

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| id | テンプレート識別 | mail_template_type.technical_name = 'delivery_mail' |
| content_html | HTML本文 | 同上 |
| content_plain | テキスト本文 | 同上 |
| subject | 件名 | 同上 |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| document | UPDATE | sent_at更新（ドキュメント送信済みフラグ） |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 送信失敗 | SMTPサーバー接続エラー等 | エラー通知表示、ログ記録 |
| テンプレートエラー | Twigテンプレートの変数エラー | エラー通知表示 |
| ドキュメント取得エラー | PDFファイルが存在しない | エラー通知表示 |
| 宛先不正 | メールアドレス形式不正 | バリデーションエラー表示 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（手動送信のため） |
| リトライ間隔 | なし |
| リトライ対象エラー | なし（ユーザーが再送信） |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | メールサービス設定による |
| 1日あたり上限 | メールサービス設定による |

### 配信時間帯

特に制限なし。管理者の操作時に即座に送信される。

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

- 納品書には顧客情報・注文情報が含まれるため、正しい宛先への送信が重要
- アクセシビリティドキュメントへのアクセスはログインまたはゲスト認証が必要
- ドキュメントのディープリンクコードは推測困難なランダム文字列を使用

## 備考

- 本テンプレートタイプの技術名は `delivery_mail`
- MailTemplateTypesクラスで `MAILTYPE_DOCUMENT_DELIVERY_NOTE` として定義
- Migration1632721037OrderDocumentMailTemplateで初期テンプレートが追加された
- 管理画面コンポーネント `sw-order-send-document-modal` で送信処理が実装されている
- ドキュメントタイプは `delivery_note` として定義

---

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

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

### 推奨読解順序

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

まず、メールテンプレートタイプの定義とドキュメントタイプを理解する。

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

**読解のコツ**: delivery_mailがドキュメント送信用テンプレートの技術名であることを理解する。

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

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

**主要処理フロー**:
- **行114-143**: setEmailTemplateAccordingToDocumentType()でドキュメントタイプに応じたテンプレートを自動選択
- **行115-119**: documentMailTemplateMappingでdelivery_note -> delivery_mailのマッピング定義
- **行192-243**: onSendDocument()でメール送信処理を実行
- **行245-255**: loadTheLinksForA11y()でアクセシビリティドキュメントリンクを生成

#### Step 3: マイグレーションを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Migration1632721037OrderDocumentMailTemplate.php | `src/Core/Migration/V6_4/Migration1632721037OrderDocumentMailTemplate.php` | テンプレート追加処理 |

**主要処理フロー**:
- **行40-45**: MAILTYPE_DOCUMENT_DELIVERY_NOTEのテンプレート定義
- **行100-117**: 翻訳データの登録

#### Step 4: メールテンプレートを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | en-html.html.twig | `src/Core/Migration/Fixtures/mails/delivery_mail/en-html.html.twig` | HTMLテンプレートの構造 |

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

```
sw-order-send-document-modal（管理画面コンポーネント）
    │
    ├─ setEmailTemplateAccordingToDocumentType()
    │      └─ mailTemplateRepository.search()
    │
    ├─ onMailTemplateChange()
    │      └─ mailService.buildRenderPreview()
    │
    └─ onSendDocument()
           │
           ├─ mailTemplateRepository.get()
           │
           └─ mailService.sendMailTemplate()
                  │
                  ├─ ドキュメント添付処理
                  │
                  └─ AbstractMailService::send()
```

### データフロー図

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

管理者操作            ───▶ sw-order-send-document-modal  ───▶ モーダル表示
(ドキュメント送信)
                              │
                              ▼
document (PDF)        ───▶ mailService.sendMailTemplate  ───▶ メール送信
order (注文データ)          │                                 (SMTP)
mail_template              │
                           ▼
                      ドキュメント添付
                      a11yドキュメントリンク生成
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| 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` | ソース | ドキュメント送信モーダル |
| Migration1632721037OrderDocumentMailTemplate.php | `src/Core/Migration/V6_4/Migration1632721037OrderDocumentMailTemplate.php` | マイグレーション | テンプレート追加 |
| en-html.html.twig | `src/Core/Migration/Fixtures/mails/delivery_mail/en-html.html.twig` | テンプレート | 英語HTMLテンプレート |
| en-plain.html.twig | `src/Core/Migration/Fixtures/mails/delivery_mail/en-plain.html.twig` | テンプレート | 英語テキストテンプレート |
| de-html.html.twig | `src/Core/Migration/Fixtures/mails/delivery_mail/de-html.html.twig` | テンプレート | ドイツ語HTMLテンプレート |
| de-plain.html.twig | `src/Core/Migration/Fixtures/mails/delivery_mail/de-plain.html.twig` | テンプレート | ドイツ語テキストテンプレート |
