# 通知設計書 38-Document Cancellation Invoice

## 概要

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

### 本通知の処理概要

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

**業務上の目的・背景**：キャンセル請求書は、発行済みの請求書を取り消す際に発行される重要な会計書類である。特にドイツ・EU圏の会計法規では、請求書の訂正は元の請求書の取り消し（Storno）と新規請求書の発行によって行う必要がある場合が多い。顧客と会計上の整合性を保つために、キャンセル請求書の適切な送付は重要である。

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

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

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

**期待されるアクション**：顧客は通知を受け取り、添付されたキャンセル請求書を確認する。元の請求書が取り消されたことを認識し、会計処理に反映することが期待される。

## 通知種別

メール通知

## 送信仕様

### 基本情報

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

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

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

## 通知テンプレート

### メール通知の場合

| 項目 | 内容 |
|-----|------|
| 送信元アドレス | 販売チャネル設定による |
| 送信元名称 | `{{ 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 cancellation 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(...) %}
            - <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[テンプレート自動選択: cancellation_mail]
    C --> D[送信ボタンクリック]
    D --> E[mailService.sendMailTemplate呼び出し]
    E --> F[キャンセル請求書PDF添付処理]
    F --> G[AbstractMailService.send]
```

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

### 参照テーブル一覧

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

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

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

## 備考

- 本テンプレートタイプの技術名は `cancellation_mail`
- MailTemplateTypesクラスで `MAILTYPE_DOCUMENT_CANCELLATION_INVOICE` として定義（行22）
- ドキュメントタイプマッピング: `storno` -> `cancellation_mail`
- ドイツ語では「Stornorechnung」と呼ばれる

---

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

### 推奨読解順序

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | MailTemplateTypes.php | `src/Core/Content/MailTemplate/MailTemplateTypes.php` | MAILTYPE_DOCUMENT_CANCELLATION_INVOICE = 'cancellation_mail'（行22） |
| 1-2 | index.js | `src/Administration/Resources/app/administration/src/module/sw-order/component/sw-order-send-document-modal/index.js` | storno -> cancellation_mailのマッピング（行119） |

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| MailTemplateTypes.php | `src/Core/Content/MailTemplate/MailTemplateTypes.php` | ソース | テンプレートタイプ定義 |
| en-html.html.twig | `src/Core/Migration/Fixtures/mails/cancellation_mail/en-html.html.twig` | テンプレート | 英語HTMLテンプレート |
| de-html.html.twig | `src/Core/Migration/Fixtures/mails/cancellation_mail/de-html.html.twig` | テンプレート | ドイツ語HTMLテンプレート |
