# 通知設計書 18-未完了サインアップ

## 概要

本ドキュメントは、サインアップを開始したが完了していないユーザーへのリマインダーメールの設計仕様を定義する。

### 本通知の処理概要

この通知は、サインアップフローを途中で離脱したユーザーに対して、メール認証の完了を促すリアクティベーションメールを送信する処理である。

**業務上の目的・背景**：サインアップファネルのコンバージョン率を向上させることを目的としている。ユーザーがサインアップを開始しながら、メール認証を完了しないまま離脱するケースは少なくない。これらのユーザーにリマインダーを送信することで、サインアップ完了率を改善し、ユーザー獲得コストの最適化に寄与する。

**通知の送信タイミング**：サインアップ開始から一定時間（24時間、48時間など）が経過し、メール認証が完了していないユーザーに対して、バッチ処理で送信される。

**通知の受信者**：サインアップを開始したが、メール認証を完了していないユーザーに送信される。既に認証完了したユーザーや、明示的にキャンセルしたユーザーには送信しない。

**通知内容の概要**：メール認証の完了を促すメッセージ、認証コード入力ページへのリンク、認証コード再送信リンクが含まれる。

**期待されるアクション**：受信者が「Verify your email」ボタンをクリックして認証ページに移動し、メール認証を完了してサインアップを完了すること。

## 通知種別

メール（マーケティングメール / リアクティベーションメール）

## 送信仕様

### 基本情報

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

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

サインアップテーブルを参照し、サインアップ開始日時から一定時間経過かつメール認証未完了のユーザーを抽出して送信。

## 通知テンプレート

### メール通知の場合

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

### 本文テンプレート

```
[Giselleロゴ]

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

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

Verify your email.

Hi {userName}, we noticed you started signing up for Giselle but
didn't finish verifying your email.

Complete your signup by verifying your email address. Enter the
verification code we sent, or request a new one if you need it.

[Verify your email]

Didn't receive a code? [Request a new verification code]

—
The Giselle Team
https://giselles.ai

[フッター]
```

### 添付ファイル

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

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| userName | ユーザー名（デフォルト: "there"） | サインアップDB | No |
| completeSignupUrl | 認証ページURL | 固定値（デフォルト: https://studio.giselles.ai/signup/verify-email） | Yes |
| resendCodeUrl | 認証コード再送信URL | 固定値（デフォルト: https://studio.giselles.ai/signup/verify-email） | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| スケジュール | 日次バッチ処理 | サインアップ開始からN時間経過かつ認証未完了 | 自動リマインダー送信 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| メール認証完了済み | 既に認証を完了したユーザーには送信しない |
| 配信停止済み | 明示的に配信停止を選択したユーザーには送信しない |
| 直近でリマインダー送信済み | 過去24時間以内に同様のメールを受信したユーザーには送信しない |
| サインアップキャンセル済み | サインアップをキャンセルしたユーザーには送信しない |

## 処理フロー

### 送信フロー

```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 | ユーザー情報取得 | メールアドレス、名前 |
| auth.users | 認証状態確認 | Supabase認証テーブル |
| email_send_logs | 直近送信確認 | 重複送信防止 |

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

#### users / auth.users

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| email | 送信先メールアドレス | - |
| name | ユーザー名（パーソナライズ用） | - |
| email_confirmed_at | 認証完了日時 | IS NULL（未認証） |
| created_at | サインアップ開始日時 | CURRENT_TIMESTAMP - created_at > N hours |

### 更新テーブル一覧

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

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

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

## エラー処理

### エラーケース一覧

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

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

サインアップ直後のユーザーの熱意が冷めないうちに送信することが重要。24〜48時間以内の送信を推奨。

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

- 配信停止リンクをフッターに含める
- TLS暗号化通信
- 認証コード再送信URLはセキュアに設計

## 備考

- EmailHeaderのheading/subheadingは「It's been a while. / Your agents are waiting for you.」で、他のリアクティベーションメールと共通
- h1スタイルで「Verify your email.」を強調表示
- 認証コード再送信リンクを提供して、ユーザーの利便性を向上

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | incomplete-signup.tsx | `apps/studio.giselles.ai/emails/marketing/reactivation/incomplete-signup.tsx` | 30-34行目：`IncompleteSignupEmailProps`インターフェースの定義 |

**読解のコツ**: 3つのプロパティ（userName, completeSignupUrl, resendCodeUrl）で、認証完了とコード再送信の両方のCTAを提供していることに注目。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | incomplete-signup.tsx | `apps/studio.giselles.ai/emails/marketing/reactivation/incomplete-signup.tsx` | 36-92行目：メインコンポーネントの構造 |

**主要処理フロー**:
1. **36-40行目**: Props受け取りとデフォルト値設定
2. **49-52行目**: EmailHeaderでheading/subheading設定
3. **57行目**: h1スタイルで「Verify your email.」表示
4. **58-65行目**: メール本文（認証促進メッセージ）
5. **66-68行目**: 「Verify your email」CTAボタン
6. **69-74行目**: 認証コード再送信リンク

#### Step 3: 2つのCTAを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | incomplete-signup.tsx | `apps/studio.giselles.ai/emails/marketing/reactivation/incomplete-signup.tsx` | 66-68行目, 69-74行目：Button と Link |

**主要処理フロー**:
- **66-68行目**: `<Button href={completeSignupUrl}>`で主要CTA
- **71-73行目**: `<Link href={resendCodeUrl}>`で認証コード再送信

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

```
IncompleteSignupEmail (メインコンポーネント)
    │
    ├─ EmailHeader
    │      ├─ heading: "It's been a while."
    │      └─ subheading: "Your agents are waiting for you."
    │
    ├─ Section (コンテンツ)
    │      ├─ Heading (h1) ─── "Verify your email."
    │      ├─ Text ─── 認証促進メッセージ
    │      ├─ Text ─── 認証方法の説明
    │      ├─ Button ─── Verify your email CTA
    │      ├─ Text ─── 認証コード再送信
    │      │      └─ Link ─── Request a new verification code
    │      └─ Text ─── 署名
    │
    └─ EmailFooter ─── フッター部品
```

### データフロー図

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

未認証ユーザー情報     ───▶  IncompleteSignupEmail      ───▶  HTMLメール
├── userName                     コンポーネント                    │
├── completeSignupUrl                  │                          │
└── resendCodeUrl                      ▼                          │
                          React Email レンダリング ───────────────┘
```

### 関連ファイル一覧

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