# 通知設計書 39-Document A11y

## 概要

本ドキュメントは、Shopwareにおけるアクセシビリティ対応ドキュメント（A11y Document）を顧客に送付する際のメール通知の設計仕様を定義する。

### 本通知の処理概要

本通知は、注文のアクセシビリティ対応ドキュメント（HTML形式の請求書・納品書等）が顧客にメールで送付される際に使用される通知である。視覚障害者等がスクリーンリーダーで読み上げ可能な形式でドキュメントを提供する。

**業務上の目的・背景**：アクセシビリティ（A11y）は、障害を持つ人々を含むすべてのユーザーがコンテンツにアクセスできるようにするための重要な取り組みである。PDF形式のドキュメントはスクリーンリーダーで読み上げにくい場合があるため、HTML形式の代替ドキュメントを提供することで、視覚障害者等も注文ドキュメントの内容を確認できるようになる。EU圏のアクセシビリティ法規制への対応としても重要。

**通知の送信タイミング**：注文状態の変更時やドキュメント送信時に、アクセシビリティドキュメントが存在する場合、メール本文内にHTMLドキュメントへのリンクが含まれる。また、`a11y_mail`テンプレートを使用した専用の通知も可能。

**通知の受信者**：注文を行った顧客のメールアドレス（`order.orderCustomer.email`）宛に送信される。

**通知内容の概要**：顧客の敬称・氏名、注文番号、アクセシビリティ対応ドキュメントへのリンクが含まれる。リンク先ではログインまたはゲスト認証（メールアドレス+郵便番号）が必要。

**期待されるアクション**：顧客は通知を受け取り、リンクをクリックしてHTML形式のドキュメントにアクセスする。スクリーンリーダー等を使用してドキュメントの内容を確認することが期待される。

## 通知種別

メール通知

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（ドキュメント送信時に含まれる）/ 非同期（Flow経由） |
| 優先度 | 中 |
| リトライ | メール送信サービスの設定に依存 |

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

1. デフォルトでは注文顧客のメールアドレスが使用される
2. アクセシビリティドキュメントへのリンクは、他のドキュメント送信メール内に含まれる形で提供される

## 通知テンプレート

### メール通知の場合

| 項目 | 内容 |
|-----|------|
| 送信元アドレス | 販売チャネル設定による |
| 送信元名称 | `{{ salesChannel.name }}` |
| 件名 | 親ドキュメントの件名に準拠 |
| 形式 | HTML/テキスト両対応 |

### 本文テンプレート（a11yDocumentsセクション）

```html
{% 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 %}
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| なし | - | - | アクセシビリティドキュメントはリンク形式で提供 |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| a11yDocuments | アクセシビリティドキュメント配列 | 動的生成 | No |
| a11yDocuments[].documentId | ドキュメントID | document.id | Yes |
| a11yDocuments[].deepLinkCode | ディープリンクコード | document.deep_link_code | Yes |
| a11yDocuments[].fileExtension | ファイル拡張子 | document_a11y_media_file.file_extension | Yes |
| order | 注文エンティティ | order テーブル | Yes |
| salesChannel | 販売チャネル | sales_channel テーブル | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 他の通知に含まれる | ドキュメント送信時 | a11yドキュメントが存在 | 請求書・納品書等の送信時に含まれる |
| 状態変更通知に含まれる | 注文状態変更時 | a11yドキュメントが存在 | 決済状態変更等の通知に含まれる |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| a11yドキュメント未生成 | アクセシビリティ対応ドキュメントが生成されていない場合 |
| documentA11yMediaFile未設定 | ドキュメントにa11yメディアファイルが紐づいていない場合 |

## 処理フロー

### リンク生成フロー

```mermaid
flowchart TD
    A[ドキュメント送信処理開始] --> B{document.documentA11yMediaFile存在?}
    B -->|Yes| C[a11yDocuments配列に追加]
    B -->|No| D[スキップ]
    C --> E[テンプレート変数としてメールに渡す]
    E --> F[メール本文内にa11yリンクを展開]
    F --> G[メール送信]
    D --> G
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| document | ドキュメント情報 | 元ドキュメント |
| document_a11y_media_file | a11yメディアファイル | HTML形式ドキュメント |
| order | 注文情報取得 | ディープリンクコード |
| sales_channel | 販売チャネル | ドメイン情報 |

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

#### document

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

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| リンク生成エラー | ドメイン情報が取得できない | デフォルトドメインを使用 |
| ファイル不存在 | a11yファイルが削除されている | リンクをスキップ |

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

- アクセシビリティドキュメントへのアクセスはログインまたはゲスト認証（メールアドレス+郵便番号）が必要
- ディープリンクコードは推測困難なランダム文字列を使用
- HTMLドキュメントはXSS対策が施されている

## 備考

- 本テンプレートタイプの技術名は `a11y_mail`
- MailTemplateTypesクラスで `MAILTYPE_DOCUMENT_A11Y` として定義（行94）
- Migration1737105721MigrateOrderStateChangeDocumentToA11Yでテンプレートが更新された
- アクセシビリティドキュメントは `frontend.account.order.single.document.a11y` ルートで提供される
- `loadTheLinksForA11y()` メソッドでa11yドキュメントリンクが生成される（sw-order-send-document-modal内）

---

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

### 推奨読解順序

#### Step 1: テンプレートタイプを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | MailTemplateTypes.php | `src/Core/Content/MailTemplate/MailTemplateTypes.php` | MAILTYPE_DOCUMENT_A11Y = 'a11y_mail'（行94） |

#### Step 2: a11yドキュメントリンク生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.js | `src/Administration/Resources/app/administration/src/module/sw-order/component/sw-order-send-document-modal/index.js` | loadTheLinksForA11y()メソッド（行245-255） |

**主要処理フロー**:
- **行245-255**: documentA11yMediaFileが存在する場合、a11yDocuments配列にリンク情報を追加

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Migration1737105721MigrateOrderStateChangeDocumentToA11Y.php | `src/Core/Migration/V6_6/Migration1737105721MigrateOrderStateChangeDocumentToA11Y.php` | a11y対応テンプレートへの移行処理 |

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

```
sw-order-send-document-modal
    │
    ├─ createdComponent()
    │      └─ loadTheLinksForA11y()
    │              │
    │              └─ document.documentA11yMediaFile チェック
    │                      │
    │                      └─ a11yDocuments配列に追加
    │
    └─ onSendDocument()
           │
           └─ mailService.sendMailTemplate()
                  │
                  └─ a11yDocumentsをテンプレートデータに含める
```

### データフロー図

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

document              ───▶ loadTheLinksForA11y()      ───▶ a11yDocuments配列
(documentA11yMediaFile)    │
                           ▼
                      a11yDocuments = [{
                        documentId: ...,
                        deepLinkCode: ...,
                        fileExtension: ...
                      }]
                           │
                           ▼
                      Twig テンプレート展開          ───▶ メール本文内リンク
                           │
                           ▼
                      顧客がリンクをクリック        ───▶ 認証画面
                           │
                           ▼
                      HTMLドキュメント表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| 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` | ソース | a11yリンク生成 |
| Migration1737105721MigrateOrderStateChangeDocumentToA11Y.php | `src/Core/Migration/V6_6/Migration1737105721MigrateOrderStateChangeDocumentToA11Y.php` | マイグレーション | テンプレート更新 |
| 各メールテンプレート | `src/Core/Migration/Fixtures/mails/*/en-html.html.twig` | テンプレート | a11yDocumentsセクションを含む |
