# 通知サービス 詳細設計書

| 項目 | 内容 |
|------|------|
| 文書番号 | DD-NOTIF-001 |
| バージョン | 1.0 |
| 作成日 | 2025年12月1日 |
| ステータス | 承認済み |

---

## 1. サービス概要

通知サービスは、Jinja2ベースのテンプレートを使用して、個別注文のメール・SMS通知を日本語で送信する。

---

## 2. APIエンドポイント

### 2.1 POST /api/v1/notifications/email — メール送信

**1件の注文**のメール通知を送信する。一括メール機能なし。レート制限: 10件/秒。

**リクエスト例:**
```json
{
    "order_id": 1,
    "to_email": "tanaka@example.co.jp",
    "template_name": "ORDER_CONFIRMATION",
    "template_data": {"order_id": 1, "customer_name": "田中太郎", "total_amount": 179600, "currency": "JPY", "item_count": 2}
}
```

### 2.2 POST /api/v1/notifications/sms — SMS送信

同パターン。1件ずつ処理。

### 2.3 GET /api/v1/notifications/{notification_id} — 通知取得

### 2.4 GET /api/v1/notifications/order/{order_id} — 注文別通知一覧

---

## 3. データモデル

```mermaid
erDiagram
    notification_templates {
        int id PK
        string name UK "ORDER_CONFIRMATION|ORDER_SHIPPED|ORDER_CANCELLED"
        string subject_template
        text body_template "Jinja2形式"
        enum channel "EMAIL|SMS"
        string language "ja"
    }
    notifications {
        int id PK
        int order_id "ユニークではない - 1注文に複数通知可"
        enum channel "EMAIL|SMS"
        string template_name
        string recipient
        string subject
        text body
        enum status "保留中|送信済み|失敗"
        datetime sent_at
        datetime created_at
    }
```

> **スキーマ注記:** `order_id` はユニークではない（1注文に複数通知可）。ただし、グループ送信を追跡する **batch_idカラムは存在しない**。

---

## 4. テンプレートシステム

### 4.1 デフォルトテンプレート（日本語）

| 名前 | 件名 | チャネル |
|------|------|---------|
| ORDER_CONFIRMATION | ご注文確認 — 注文番号 #{{ order_id }} | EMAIL |
| ORDER_SHIPPED | 発送のお知らせ — 注文番号 #{{ order_id }} | EMAIL |
| ORDER_CANCELLED | ご注文キャンセルのお知らせ — 注文番号 #{{ order_id }} | EMAIL |

### 4.2 テンプレート描画

テンプレートはJinja2構文を使用。変数はAPIリクエストの `template_data` で渡される。描画は**通知ごとに個別実行** — バッチテンプレート描画の最適化なし。

---

## 5. 通知フロー

```mermaid
sequenceDiagram
    participant OS as 注文サービス
    participant NS as 通知サービス
    participant DB as 通知DB

    OS->>NS: POST /api/v1/notifications/email
    Note over NS: テンプレート検索
    Note over NS: 件名+本文描画（Jinja2）
    NS->>DB: INSERT notification（ステータス: 送信済み）
    Note over NS: メール送信（モック）
    NS-->>OS: 201 Created
```

---

## 6. レート制限

| パラメータ | 値 |
|-----------|-----|
| 最大レート | **10件/秒** |
| スコープ | グローバル（全チャネル合計） |
| キューイング | **なし — キューは存在しない** |

> **一括処理への影響:** 10,000件の注文通知を10件/秒で処理 = 最低**1,000秒（約17分）**。このレート制限は一括操作の重大なボトルネック。

---

## 7. 現在の制限事項

| ID | 制限事項 | 深刻度 |
|----|---------|--------|
| DD-NTF-LIM-001 | **1APIコールにつき1件の通知。** 一括通知エンドポイントなし。 | 高 |
| DD-NTF-LIM-002 | **バッチメール/SMS送信機能なし。** 複数宛先への一括送信不可。 | 高 |
| DD-NTF-LIM-003 | **レート制限10件/秒が一括操作の重大ボトルネック。** 10,000件で約17分。 | 高 |
| DD-NTF-LIM-004 | **バッチテンプレート描画最適化なし。** 1件ずつ個別描画。 | 中 |
| DD-NTF-LIM-005 | **キューベース非同期送信なし。** 全通知はHTTPリクエスト内で同期処理。 | 高 |
| DD-NTF-LIM-006 | **グループ通知のbatch_idなし。** 同一バッチの通知を関連付けできない。 | 中 |