# 通知設計書 9-最初のワークスペース作成案内

## 概要

本ドキュメントは、Giselleプラットフォームにおける最初のワークスペース作成案内メール通知の設計仕様を定義するものである。ユーザーがStageを探索した後、ワークスペース作成を促すフォローアップメールの送信仕様、テンプレート構造、処理フローを記載する。

### 本通知の処理概要

本通知は、ウェルカムメール送信後のフォローアップとして、ユーザーにワークスペース作成を促す機能である。オンボーディングメールシリーズの第2通目。

**業務上の目的・背景**：ユーザーがStageでAIエージェントを試した後、次のステップとしてチームでの共同作業環境であるワークスペースの作成を促す。ワークスペースを作成することで、Node Builderによるビジュアルエージェント構築、GitHub連携、チームコラボレーションなど、Giselleのフル機能を活用できるようになる。

**通知の送信タイミング**：ウェルカムメール送信後、一定期間経過後（例：24-48時間後）に自動送信される。または、ユーザーがStageを一定回数利用した後にトリガーされる。

**通知の受信者**：サインアップ完了済みで、まだワークスペースを作成していないユーザー。マーケティングメール受信可のユーザーに限定。

**通知内容の概要**：ユーザー名への挨拶、ワークスペースの価値説明（チームコラボレーション、Node Builder、インテグレーション）、ワークスペース作成への案内、ドキュメントへのリンク、Giselleチームからの署名が含まれる。

**期待されるアクション**：受信者は「Create your workspace」ボタンをクリックし、ワークスペース作成フローに進む。チームでのコラボレーションを開始することが期待される。

## 通知種別

メール（マーケティングメール / オンボーディング）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 非同期（スケジュール送信） |
| 優先度 | 中 |
| リトライ | アプリケーション設定に依存 |

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

以下の条件を満たすユーザーに対して送信される：
- サインアップ完了・メール確認済み
- ウェルカムメール送信から一定期間経過
- まだワークスペースを作成していない
- マーケティングメール受信可

## 通知テンプレート

### メール通知の場合

| 項目 | 内容 |
|-----|------|
| 送信元アドレス | noreply@giselles.ai（アプリケーション設定に依存） |
| 送信元名称 | Giselle |
| 件名 | Ready to collaborate? Create your workspace |
| 形式 | HTML |

### 本文テンプレート

```
[Giselleロゴ]
Ready to collaborate?
Create your workspace.
---
Hi {ユーザー名},

You've explored Giselle's Stage — now it's time to take the next step.

Create a dedicated workspace for your team to collaborate, build agents visually with the Node Builder, and manage integrations together — all in one place.

Workspaces are shared within your team, allowing everyone to collaborate on building and managing AI agents together. Connect GitHub, use multiple AI models, and access your knowledge store — everything you need to build powerful agents.

[Create your workspace ボタン]

Need help getting started? Check out our documentation.

Or keep experimenting in your personal Stage.

—
The Giselle Team
https://giselles.ai
---
[フッター：Product / Blog / Documentation リンク、SNSアイコン、著作権表示]
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| なし | - | - | 本通知には添付ファイルなし |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| userName | ユーザー名（デフォルト: "there"） | ユーザープロファイル | No |
| createWorkspaceUrl | ワークスペース作成画面のURL | アプリケーション設定 | No |
| stageUrl | Stage画面のURL（未使用だが定義あり） | アプリケーション設定 | No |
| docsUrl | ドキュメントのURL | アプリケーション設定 | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| スケジュール | ウェルカムメール送信から一定期間経過 | ワークスペース未作成 | オンボーディングシリーズの第2通目 |
| イベント | Stageで一定回数エージェント実行 | ワークスペース未作成 | アクティブユーザーへのフォローアップ |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| ワークスペース作成済み | 既にワークスペースを作成しているユーザー |
| マーケティングメール拒否 | ユーザーがマーケティングメールの受信を拒否している場合 |
| 前のメール未送信 | ウェルカムメール（01-welcome）が未送信の場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[スケジュールトリガー発火] --> B[対象ユーザー抽出]
    B --> C{ワークスペース作成済み?}
    C -->|はい| D[送信スキップ]
    C -->|いいえ| E{マーケティングメール受信可?}
    E -->|はい| F[ユーザー情報取得]
    E -->|いいえ| D
    F --> G[メールテンプレート展開]
    G --> H[メール送信実行]
    H --> I{送信結果}
    I -->|成功| J[送信ログ記録]
    I -->|失敗| K[エラーログ記録・リトライ]
    J --> L[終了]
    K --> L
    D --> L
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| auth.users | ユーザー情報取得 | Supabase管理テーブル |
| user_profiles | ユーザー名取得 | アプリケーション管理テーブル |
| workspaces | ワークスペース存在確認 | ユーザーが所属するワークスペース |
| email_logs | 前回メール送信履歴確認 | ウェルカムメール送信済み確認 |
| user_preferences | マーケティングメール設定確認 | アプリケーション管理テーブル |

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

#### auth.users

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| email | 送信先メールアドレス | 対象ユーザー |
| id | ユーザー識別 | ワークスペース存在確認用 |

#### workspaces

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| id | ワークスペース存在確認 | user_id で検索（オーナーまたはメンバー） |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| email_logs | INSERT | 送信ログ記録 |

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

| 操作 | 項目（カラム名） | 更新値 | 備考 |
|-----|-----------------|-------|------|
| INSERT | type | first_workspace | メール種別 |
| INSERT | status | sent/failed | 送信結果 |
| INSERT | sent_at | CURRENT_TIMESTAMP | 送信日時 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 送信失敗 | SMTPサーバー接続エラー | リトライ処理を実行 |
| テンプレートエラー | テンプレート変数の展開失敗 | エラーログに記録 |
| ユーザー情報不足 | プロファイル情報が取得できない | デフォルト値を使用 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | アプリケーション設定に依存 |
| リトライ間隔 | アプリケーション設定に依存 |
| リトライ対象エラー | 一時的な送信エラー |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | アプリケーション設定に依存 |
| 1日あたり上限 | アプリケーション設定に依存 |

### 配信時間帯

ユーザーのタイムゾーンを考慮した適切な時間帯（設定による）

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

- TLS暗号化によりメール送信時のデータ保護を実施
- マーケティングメールの配信停止オプションをフッターに含める（CAN-SPAM準拠）
- ユーザー名がない場合はデフォルト値「there」を使用

## 備考

- 本通知はオンボーディングメールシリーズの第2通目（02-first-workspace）
- テンプレートはReact Emailを使用して実装されている
- stageUrlプロパティは定義されているが、テンプレート本文では使用されていない（将来の拡張用または設計変更の名残）

---

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

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

### 推奨読解順序

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

メールテンプレートに渡されるPropsの構造を理解することで、通知に必要なデータを把握できる。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | 02-first-workspace.tsx | `apps/studio.giselles.ai/emails/marketing/onboarding/02-first-workspace.tsx` | FirstWorkspaceEmailPropsインターフェース（28-33行目）でuserName、createWorkspaceUrl、stageUrl、docsUrlプロパティを確認 |

**読解のコツ**: stageUrlプロパティは定義されているが、変数名が`_stageUrl`となっておりテンプレート本文では未使用であることに注意（38行目）。

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

メールテンプレートコンポーネントの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | 02-first-workspace.tsx | `apps/studio.giselles.ai/emails/marketing/onboarding/02-first-workspace.tsx` | FirstWorkspaceEmailコンポーネント（35-104行目）の構造 |

**主要処理フロー**:
1. **35-40行目**: propsをデフォルト値付きで受け取る（stageUrlは`_stageUrl`として未使用）
2. **46行目**: Previewにワークスペース作成促進メッセージを設定
3. **49-52行目**: EmailHeaderに見出しとサブ見出しを設定
4. **57-73行目**: 本文テキスト（ユーザー名、Stage探索後のステップ、ワークスペースの価値説明）
5. **74-76行目**: "Create your workspace"ボタン
6. **77-86行目**: ドキュメントへのリンクとStageでの継続実験への言及

#### Step 3: 共通コンポーネントを理解する

メールの共通レイアウトとスタイルを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | email-header.tsx | `apps/studio.giselles.ai/emails/components/email-header.tsx` | ヘッダーコンポーネント（見出し・サブ見出し表示） |
| 3-2 | email-footer.tsx | `apps/studio.giselles.ai/emails/components/email-footer.tsx` | フッターコンポーネント |
| 3-3 | email-styles.ts | `apps/studio.giselles.ai/emails/components/email-styles.ts` | buttonスタイル、textスタイル、linkスタイル |

**主要処理フロー**:
- **02-first-workspace.tsx 87-94行目**: 署名セクション

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

```
FirstWorkspaceEmail (02-first-workspace.tsx)
    │
    ├─ EmailFonts (email-fonts.tsx)
    │      └─ フォント読み込み設定
    │
    ├─ EmailHeader (email-header.tsx)
    │      ├─ ロゴ表示
    │      ├─ 見出し: "Ready to collaborate?"
    │      └─ サブ見出し: "Create your workspace."
    │
    ├─ 本文セクション
    │      ├─ 挨拶テキスト（ユーザー名含む）
    │      ├─ Stage探索後のステップ説明
    │      ├─ ワークスペースの価値説明（チームコラボ、Node Builder、インテグレーション）
    │      ├─ "Create your workspace"ボタン（buttonスタイル適用）
    │      ├─ ドキュメントへのリンク
    │      ├─ Stageでの継続実験への言及
    │      └─ 署名セクション（signatureTextスタイル適用）
    │
    └─ EmailFooter (email-footer.tsx)
           └─ リンク、SNSアイコン、著作権表示
```

### データフロー図

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

アプリケーションからの
userName + ───▶ FirstWorkspaceEmail ───▶ HTMLメール
createWorkspaceUrl    コンポーネント         （対象ユーザー宛に
+ docsUrl                                      アプリ経由で送信）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| 02-first-workspace.tsx | `apps/studio.giselles.ai/emails/marketing/onboarding/02-first-workspace.tsx` | ソース | ワークスペース作成案内メールテンプレート |
| 01-welcome.tsx | `apps/studio.giselles.ai/emails/marketing/onboarding/01-welcome.tsx` | ソース | 前回のオンボーディングメール（ウェルカム） |
| 03-reminder.tsx | `apps/studio.giselles.ai/emails/marketing/onboarding/03-reminder.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` | ソース | メールフッターコンポーネント |
| email-styles.ts | `apps/studio.giselles.ai/emails/components/email-styles.ts` | ソース | 共通スタイル定義 |
