# 通知設計書 17-久しぶりのご挨拶

## 概要

本ドキュメントは、長期間ログインしていないユーザーへの再訪問促進メールの設計仕様を定義する。

### 本通知の処理概要

この通知は、一定期間Giselleを利用していないユーザーに対して、プロダクトへの復帰を促すリアクティベーションメールを送信する処理である。

**業務上の目的・背景**：休眠ユーザーを再びアクティブユーザーに転換することで、ユーザーベースの維持と収益の安定化を図ることを目的としている。ユーザーが離脱した後も、プロダクトは継続的に改善されており、新機能やアップデートを知らせることで、再度利用する動機を提供する。また、ユーザーのワークスペースやエージェントがそのまま残っていることを伝え、再開のハードルを下げる。

**通知の送信タイミング**：最終ログインから一定期間（30日、60日、90日など）が経過したユーザーに対して、バッチ処理またはキャンペーンで送信される。

**通知の受信者**：一定期間ログインしていないユーザーに送信される。完全にアカウントを削除したユーザーや、明示的に配信停止を選択したユーザーには送信しない。

**通知内容の概要**：「久しぶり」の挨拶、ワークスペース・エージェントが残っている旨、最近の更新情報（リリースノートリンク）、復帰への誘導CTAが含まれる。

**期待されるアクション**：受信者が「Return to Giselle」ボタンをクリックしてGiselle Studioに復帰し、プロダクトの利用を再開すること。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

ユーザーの最終ログイン日時を基準に、一定期間（30日、60日など）ログインしていないユーザーを抽出して送信。

## 通知テンプレート

### メール通知の場合

| 項目 | 内容 |
|-----|------|
| 送信元アドレス | noreply@giselles.ai（想定） |
| 送信元名称 | Giselle |
| 件名 | We've missed you at Giselle |
| 形式 | HTML |

### 本文テンプレート

```
[Giselleロゴ]

It's been a while.
Your agents are waiting for you.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Hi {userName},

It's been a while since you last visited Giselle.

Your Stage and workspace are still here — ready whenever you are.

We've been busy. New templates, model updates, and orchestration
features have been added to make building even smoother.
Check out our [release notes] to see what's new.

Jump back in, explore what's new, and keep creating.

[Return to Giselle]

Need help or inspiration? Visit our [examples gallery] or reach
out anytime at support@giselles.ai.

—
The Giselle Team
https://giselles.ai

[フッター]
```

### 添付ファイル

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

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| userName | ユーザー名（デフォルト: "there"） | ユーザーDB | No |
| returnUrl | Giselle StudioへのURL | 固定値（デフォルト: https://studio.giselles.ai） | Yes |
| examplesGalleryUrl | 例示ギャラリーURL | 固定値（デフォルト: https://giselles.ai） | Yes |
| releaseNotesUrl | リリースノートURL | 固定値（デフォルト: https://docs.giselles.ai/en/releases/release-notes） | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| スケジュール | 日次バッチ処理 | 最終ログインからN日経過 | 自動リアクティベーション送信 |
| 手動操作 | マーケティングキャンペーン実行 | 休眠ユーザーリストが存在 | キャンペーンベースの送信 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 配信停止済みユーザー | マーケティングメールの配信停止ユーザーには送信しない |
| 直近でリアクティベーションメール送信済み | 過去30日以内に同様のメールを受信したユーザーには送信しない |
| アカウント削除済み | 削除済みアカウントには送信しない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[リアクティベーションバッチ開始] --> B[休眠ユーザーリスト抽出]
    B --> C[最終ログイン日時でフィルタ]
    C --> D[配信停止・直近送信済みユーザー除外]
    D --> E[テンプレート変数セット]
    E --> F[Reactメールコンポーネントレンダリング]
    F --> G[メール送信サービスへ送信]
    G --> H{送信結果}
    H -->|成功| I[送信ログ記録]
    H -->|失敗| J[リトライ処理]
    I --> K[終了]
    J --> K
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| users | ユーザー情報取得 | メールアドレス、名前、最終ログイン日時 |
| email_preferences | 配信設定確認 | マーケティングメール配信可否 |
| email_send_logs | 直近送信確認 | 重複送信防止 |

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

#### users

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| email | 送信先メールアドレス | - |
| name | ユーザー名（パーソナライズ用） | - |
| last_login_at | 最終ログイン日時 | CURRENT_DATE - last_login_at > N days |

### 更新テーブル一覧

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

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

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

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 送信失敗 | メールサーバー接続エラー | リトライ処理 |
| テンプレートエラー | 必須変数の欠落 | エラーログ記録 |
| 宛先不正 | 無効なメールアドレス | スキップしてログ記録 |

### リトライ仕様

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

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | メールサービスプロバイダーの制限に準拠 |
| 1日あたり上限 | 休眠ユーザー数に依存 |

### 配信時間帯

ユーザーの復帰を促すため、業務時間内（受信者のタイムゾーン考慮）に送信することを推奨。

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

- 配信停止リンクをフッターに含める
- TLS暗号化通信
- サポートメールアドレス（support@giselles.ai）を明示して信頼性を確保

## 備考

- Preview text に絵文字（💫）を含み、親しみやすさを演出
- 複数のCTAを提供（Return to Giselle、examples gallery、support email）
- ワークスペースとエージェントが残っていることを強調し、再開のハードルを下げる

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | long-time-no-see.tsx | `apps/studio.giselles.ai/emails/marketing/reactivation/long-time-no-see.tsx` | 28-33行目：`LongTimeNoSeeEmailProps`インターフェースの定義 |

**読解のコツ**: 4つのプロパティ（userName, returnUrl, examplesGalleryUrl, releaseNotesUrl）と、それぞれのデフォルト値に注目。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | long-time-no-see.tsx | `apps/studio.giselles.ai/emails/marketing/reactivation/long-time-no-see.tsx` | 35-107行目：メインコンポーネントの構造 |

**主要処理フロー**:
1. **35-40行目**: Props受け取りとデフォルト値設定
2. **49-52行目**: EmailHeaderでheading/subheading設定
3. **57-76行目**: メール本文（久しぶりの挨拶、ワークスペース残存の説明）
4. **77-79行目**: 「Return to Giselle」CTAボタン
5. **80-89行目**: 追加情報（examples gallery、support email）

#### Step 3: 複数のリンクを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | long-time-no-see.tsx | `apps/studio.giselles.ai/emails/marketing/reactivation/long-time-no-see.tsx` | 68-72行目, 82-88行目：複数のLinkコンポーネント |

**主要処理フロー**:
- **69-71行目**: releaseNotesUrlへのリンク
- **82-84行目**: examplesGalleryUrlへのリンク
- **85-88行目**: support@giselles.aiへのmailtoリンク

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

```
LongTimeNoSeeEmail (メインコンポーネント)
    │
    ├─ EmailHeader
    │      ├─ heading: "It's been a while."
    │      └─ subheading: "Your agents are waiting for you."
    │
    ├─ Section (コンテンツ)
    │      ├─ Text ─── 挨拶・説明
    │      │      ├─ 久しぶりの挨拶
    │      │      ├─ ワークスペース残存説明
    │      │      ├─ Link ─── release notes
    │      │      └─ 復帰の呼びかけ
    │      │
    │      ├─ Button ─── Return to Giselle CTA
    │      │
    │      ├─ Text ─── 追加情報
    │      │      ├─ Link ─── examples gallery
    │      │      └─ Link ─── support email
    │      │
    │      └─ Text ─── 署名
    │
    └─ EmailFooter ─── フッター部品
```

### データフロー図

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

休眠ユーザー情報       ───▶  LongTimeNoSeeEmail        ───▶  HTMLメール
├── userName                     コンポーネント                    │
├── returnUrl                          │                          │
├── examplesGalleryUrl                 ▼                          │
└── releaseNotesUrl       React Email レンダリング ───────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| long-time-no-see.tsx | `apps/studio.giselles.ai/emails/marketing/reactivation/long-time-no-see.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` | ソース | 共通スタイル・コンポーネントのエクスポート |
