# 通知設計書 15-アンバサダー招待

## 概要

本ドキュメントは、アンバサダープログラムへの招待メールの設計仕様を定義する。

### 本通知の処理概要

この通知は、選ばれたユーザーをGiselleアンバサダープログラムに招待するマーケティングメールを送信する処理である。

**業務上の目的・背景**：クリエイターや開発者のコミュニティを育成し、プロダクトの普及とフィードバック収集を促進することを目的としている。アンバサダーは新機能への早期アクセス、今後のリリースへの影響力、AIを活用したチーム構築の方法を定義する機会を得られる。これにより、コミュニティ主導のプロダクト開発と、熱心なユーザーのエンゲージメント強化を実現する。

**通知の送信タイミング**：マーケティングチームがアンバサダー候補を選定し、招待キャンペーンを実行した際に送信される。通常は、アクティブなユーザーやコミュニティ貢献者を対象とする。

**通知の受信者**：アンバサダー候補として選定されたユーザーのみに送信される。全ユーザーへの一斉送信ではなく、限定的なターゲティングが行われる。

**通知内容の概要**：アンバサダープログラムの概要、参加のメリット、申し込みCTAが含まれる。視覚的に魅力的なヒーロー画像を含む。

**期待されるアクション**：受信者が「Apply Now」ボタンをクリックしてアンバサダープログラムに申し込むこと。

## 通知種別

メール（マーケティングメール）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 非同期（バッチ送信） |
| 優先度 | 中〜高 |
| リトライ | 有・3回 |

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

マーケティングチームが手動で選定したアンバサダー候補リストに基づき送信。アクティビティ、コミュニティ貢献度、影響力などを考慮して選定される。

## 通知テンプレート

### メール通知の場合

| 項目 | 内容 |
|-----|------|
| 送信元アドレス | noreply@giselles.ai（想定） |
| 送信元名称 | Giselle |
| 件名 | Join the Giselle Ambassador Program |
| 形式 | HTML |

### 本文テンプレート

```
[Giselleロゴ]

[アンバサダー招待ヒーロー画像]

Hi {userName},

We're inviting a select group of creators and developers to
join the early Giselle Ambassador Program.

As an ambassador, you'll gain early access to new features,
shape upcoming releases, and help define how teams build with AI.

[Apply Now]

—
The Giselle Team
https://giselles.ai

[フッター]
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| なし | - | - | 添付ファイルなし |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| userName | ユーザー名（デフォルト: "there"） | ユーザーDB | No |
| applyUrl | 申し込みページURL | 固定値（デフォルト: https://giselles.ai/ambassador） | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 手動操作 | マーケティングキャンペーン実行 | 候補者リストが存在 | アンバサダー招待送信 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 配信停止済みユーザー | マーケティングメールの配信停止ユーザーには送信しない |
| 既にアンバサダーのユーザー | 既にプログラムに参加済みの場合は招待しない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[アンバサダー招待キャンペーン開始] --> B[候補者リスト取得]
    B --> C[配信停止・既参加者除外]
    C --> D[テンプレート変数セット]
    D --> E[Reactメールコンポーネントレンダリング]
    E --> F[メール送信サービスへ送信]
    F --> G{送信結果}
    G -->|成功| H[送信ログ記録]
    G -->|失敗| I[リトライ処理]
    H --> J[終了]
    I --> J
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| users | ユーザー情報取得 | メールアドレス、名前 |
| email_preferences | 配信設定確認 | マーケティングメール配信可否 |
| ambassador_members | 既存アンバサダー確認 | 重複招待防止（想定） |

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

#### users

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| email | 送信先メールアドレス | 候補者リストに含まれるユーザー |
| name | ユーザー名（パーソナライズ用） | - |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| email_send_logs | INSERT | 送信履歴の記録 |

#### 送信ログテーブル

| 操作 | 項目（カラム名） | 更新値 | 備考 |
|-----|-----------------|-------|------|
| INSERT | email_type | 'ambassador_invite' | 通知種別 |
| INSERT | recipient_email | {送信先} | 受信者メール |
| INSERT | sent_at | CURRENT_TIMESTAMP | 送信日時 |
| INSERT | status | 'sent' / 'failed' | 送信結果 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 送信失敗 | メールサーバー接続エラー | リトライ処理 |
| 画像読み込みエラー | ヒーロー画像URL無効 | フォールバック処理 |
| テンプレートエラー | 必須変数の欠落 | エラーログ記録 |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | メールサービスプロバイダーの制限に準拠 |
| 1日あたり上限 | 候補者数に依存（限定送信） |

### 配信時間帯

ターゲットユーザーのタイムゾーンを考慮し、業務時間内の送信を推奨。個人化された招待のため、受信率の高い時間帯を選択。

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

- 配信停止リンクをフッターに含める
- TLS暗号化通信
- 限定招待のため、申し込みURLは認証付きを推奨

## 備考

- 「select group of creators and developers」という限定感を演出
- ヒーロー画像（ambassador-invite.jpg）で視覚的なインパクトを提供
- Preview text に絵文字（🪶）を含む

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ambassador-invite.tsx | `apps/studio.giselles.ai/emails/marketing/campaigns/ambassador-invite.tsx` | 30-33行目：`AmbassadorInviteEmailProps`インターフェースの定義 |

**読解のコツ**: シンプルな2プロパティ構成（userName, applyUrl）であることに注目。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ambassador-invite.tsx | `apps/studio.giselles.ai/emails/marketing/campaigns/ambassador-invite.tsx` | 35-87行目：メインコンポーネントの構造 |

**主要処理フロー**:
1. **35-38行目**: Props受け取りとデフォルト値設定
2. **39行目**: ヒーロー画像URL取得
3. **49-55行目**: ヒーロー画像セクション
4. **57-77行目**: コンテンツセクション
5. **67-69行目**: 「Apply Now」CTAボタン

#### Step 3: ヒーロー画像とCTAを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ambassador-invite.tsx | `apps/studio.giselles.ai/emails/marketing/campaigns/ambassador-invite.tsx` | 49-55行目：imageSection、67-69行目：Buttonコンポーネント |

**主要処理フロー**:
- **50-55行目**: ヒーロー画像の表示
- **67行目**: `<Button href={applyUrl} style={button}>`でCTAボタンを実装

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

```
AmbassadorInviteEmail (メインコンポーネント)
    │
    ├─ getEmailAssetUrl() ─── ヒーロー画像URL生成
    │
    ├─ EmailHeader ─── ヘッダー部品（ロゴのみ）
    │
    ├─ Section (imageSection)
    │      └─ Img ─── アンバサダー招待ヒーロー画像
    │
    ├─ Section (コンテンツ)
    │      ├─ Text ─── 挨拶（Hi {userName}）
    │      ├─ Text ─── プログラム説明（select group）
    │      ├─ Text ─── メリット説明（early access）
    │      ├─ Button ─── Apply Now CTA
    │      └─ Text ─── 署名
    │
    └─ EmailFooter ─── フッター部品
```

### データフロー図

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

候補者リスト      ───▶  AmbassadorInviteEmail      ───▶  HTMLメール
├── userName                 コンポーネント                    │
└── applyUrl                       │                          │
                                   ▼                          │
                          React Email レンダリング ────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ambassador-invite.tsx | `apps/studio.giselles.ai/emails/marketing/campaigns/ambassador-invite.tsx` | ソース | メインテンプレートコンポーネント |
| email-header.tsx | `apps/studio.giselles.ai/emails/components/email-header.tsx` | ソース | 共通ヘッダーコンポーネント |
| email-footer.tsx | `apps/studio.giselles.ai/emails/components/email-footer.tsx` | ソース | 共通フッターコンポーネント |
| index.ts | `apps/studio.giselles.ai/emails/components/index.ts` | ソース | 共通スタイル・コンポーネントのエクスポート |
| ambassador-invite.jpg | `（アセットディレクトリ）` | 画像 | アンバサダー招待ヒーロー画像 |
