# 通知設計書 44-Product Stock Warning

## 概要

本ドキュメントは、Shopwareにおける商品在庫警告メール通知の仕様を定義する設計書である。商品の在庫数が設定された閾値を下回った際に、店舗管理者に警告メールを送信する機能について記載する。

### 本通知の処理概要

本通知は、商品の在庫数が管理者が設定した警告閾値（安全在庫数）を下回った際に、自動的に管理者に警告メールを送信する在庫管理支援機能である。在庫切れによる販売機会損失を防ぐため、事前に在庫補充のタイミングを知らせることを目的としている。

**業務上の目的・背景**：ECサイト運営において、在庫切れは直接的な売上損失と顧客満足度低下につながる。在庫警告通知により、管理者は在庫が少なくなった商品を早期に把握し、適切なタイミングで発注・補充を行うことができる。これにより在庫切れの防止と適正在庫の維持が可能となる。

**通知の送信タイミング**：商品の在庫数が更新され、設定された警告閾値を下回ったタイミングで送信される。在庫数の変動は、注文確定、返品処理、手動在庫調整、インポート処理などで発生する。Flowビルダーを通じて送信条件をカスタマイズ可能。

**通知の受信者**：店舗管理者または在庫管理担当者。Flowビルダーの設定により、管理者ユーザーまたはカスタムメールアドレスを指定可能。

**通知内容の概要**：警告対象の商品情報（商品名、商品番号、現在の在庫数）、設定された警告閾値などが含まれる。

**期待されるアクション**：管理者は通知を受けて対象商品の在庫状況を確認し、必要に応じて仕入先への発注、在庫移動、または商品ページの非表示化などの対応を行う。

## 通知種別

メール通知

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 非同期（Flowビルダー経由） |
| 優先度 | 高（在庫管理の緊急性） |
| リトライ | 有・3回 |

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

1. Flowビルダーの受信者設定（admin/custom）に基づく
2. adminの場合、管理者権限を持つユーザーのメールアドレスが使用される
3. customの場合、Flow設定で指定されたメールアドレスに送信

## 通知テンプレート

### メール通知の場合

| 項目 | 内容 |
|-----|------|
| 送信元アドレス | システム設定 `core.basicInformation.email` |
| 送信元名称 | 販売チャネル設定のショップ名 |
| 件名 | Product stock warning |
| 形式 | HTML/テキスト |

### 本文テンプレート

```twig
<div style="font-family:arial; font-size:12px;">
    <p>
        Stock warning for the following product:<br/>
        <br/>
        Product name: {{ product.translated.name }}<br/>
        Product number: {{ product.productNumber }}<br/>
        <br/>
        Current stock: {{ product.stock }}<br/>
    </p>
</div>
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| なし | - | - | 添付ファイル機能は未対応 |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| product | 商品エンティティ | product テーブル | Yes |
| product.translated.name | 商品名（翻訳済み） | product_translation | Yes |
| product.productNumber | 商品番号 | product.product_number | Yes |
| product.stock | 現在の在庫数 | product.stock | Yes |
| salesChannel | 販売チャネル情報 | sales_channel テーブル | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| Flowアクション | product.stock.changed | 在庫が閾値以下 | 商品在庫変更時 |
| Flowアクション | checkout.order.placed | 在庫が閾値以下 | 注文確定による在庫減少時 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 在庫が閾値以上 | 在庫警告閾値を上回っている場合 |
| 警告閾値未設定 | 商品に警告閾値が設定されていない場合 |
| 通知済み | 短期間内に同一商品の通知が送信済みの場合（重複防止） |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[在庫数変更イベント] --> B{在庫警告閾値設定済み?}
    B -->|No| C[送信スキップ]
    B -->|Yes| D{現在在庫 <= 閾値?}
    D -->|No| C
    D -->|Yes| E[Flow条件チェック]
    E --> F[SendMailAction実行]
    F --> G[テンプレート取得]
    G --> H[変数展開]
    H --> I[メール送信]
    I --> J{送信結果}
    J -->|成功| K[送信ログ記録]
    J -->|失敗| L[リトライ処理]
    K --> M[終了]
    L --> M
    C --> M
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| product | 商品情報取得 | 在庫数、警告閾値、商品番号 |
| product_translation | 翻訳情報 | 商品名 |
| mail_template | メールテンプレート | product_stock_warning |
| mail_template_type | テンプレートタイプ | technical_name = 'product_stock_warning' |
| user | 管理者情報 | admin受信者の場合 |

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

#### product

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| id | 商品ID | イベントから取得 |
| product_number | 商品番号 | 通知内容 |
| stock | 現在の在庫数 | 通知内容・閾値判定 |

### 更新テーブル一覧

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

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 商品未存在 | 対象商品がDBに存在しない | 送信スキップ |
| 送信失敗 | SMTPサーバーエラー | リトライ後、エラーログ記録 |
| テンプレートエラー | Twigレンダリング失敗 | MailErrorEvent発火 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

制限なし（在庫警告の緊急性を考慮）

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

- 管理者向け通知のため、一般顧客への配信は行わない
- 商品情報は機密性が低いため、特別な暗号化は不要
- Flowビルダーでの受信者設定は管理者のみがアクセス可能

## 備考

- MailTemplateTypes::MAILTYPE_STOCK_WARNING 定数で定義（product_stock_warning）
- 在庫管理の高度化にはERP連携やサードパーティプラグインの利用を推奨
- 複数商品の一括警告通知は標準機能では未対応（個別通知）

---

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

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

### 推奨読解順序

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

在庫警告で使用されるテンプレートタイプ定数を理解する。

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

**読解のコツ**: product_stock_warningが本通知の技術名。在庫関連の処理を追跡する際のキーとなる。

#### Step 2: メール送信アクションを理解する

Flowビルダー経由でのメール送信処理を確認する。

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

**主要処理フロー**:
1. **86-95行目**: Flow設定の取得とスキップ条件チェック
2. **100-111行目**: MailAwareデータの存在チェックとテンプレートID取得
3. **113-117行目**: メールテンプレートの取得
4. **126-134行目**: 受信者の決定（admin/custom/default）
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発火

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

```
Stock Change Event (在庫変更)
    │
    ├─ Flow Engine (条件: 在庫 <= 閾値)
    │      │
    │      └─ SendMailAction::handleFlow()
    │             │
    │             ├─ getMailTemplate() - テンプレート取得
    │             │
    │             ├─ getRecipients() - 受信者決定
    │             │      ├─ admin - 管理者ユーザー
    │             │      └─ custom - カスタムアドレス
    │             │
    │             └─ send()
    │                    │
    │                    └─ MailService::send()
    │                           │
    │                           ├─ MailBeforeValidateEvent
    │                           ├─ createMail()
    │                           ├─ MailBeforeSentEvent
    │                           ├─ MailSender::send()
    │                           └─ MailSentEvent
```

### データフロー図

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

Product Stock Update            Flow Engine                         Stock Warning Email
  │                                 │                                    │
  ├─ productId                      ├─ 閾値チェック                       └─ 管理者へ送信
  ├─ stock (新在庫数)               ├─ 条件評価
  └─ previousStock                  └─ メール送信トリガー
                                        │
                                        ▼
                                  SendMailAction
                                        │
                                        ├─ テンプレート: product_stock_warning
                                        │
                                        └─ MailService::send()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| MailTemplateTypes.php | `src/Core/Content/MailTemplate/MailTemplateTypes.php` | ソース | MAILTYPE_STOCK_WARNING定数（28行目） |
| 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` | マイグレーション | テンプレートタイプ登録 |
