# 通知設計書 21-年間振り返り

## 概要

本ドキュメントは、ユーザーの年間アクティビティを振り返るマーケティングメール「年間振り返り」の設計仕様を定義する。年末または年始にユーザーへ送信され、過去1年間のGiselleでの活動を振り返り、次年度への継続的な利用を促進する。

### 本通知の処理概要

年間振り返りメールは、ユーザーが過去1年間にGiselleプラットフォームで達成した成果や活動履歴を振り返る特別なマーケティングメールである。

**業務上の目的・背景**：年末年始は多くのユーザーが過去を振り返り、新年の目標を設定する時期である。この心理的タイミングを活用し、ユーザーにGiselleでの1年間の活動を可視化することで、達成感とサービスへの愛着を醸成する。また、新機能やアップデート情報を含めることで、来年への期待感を高め、継続利用を促進する。年間振り返りは、ユーザーエンゲージメントを維持し、解約率を低下させるための重要なリテンション施策である。

**通知の送信タイミング**：毎年12月下旬から1月上旬にかけて、マーケティングキャンペーンの一環として一斉送信される。具体的な送信日時はマーケティングチームが年間キャンペーンスケジュールに基づいて決定する。ユーザーごとにパーソナライズされたデータを集計した後、バッチ処理によりメール送信が行われる。

**通知の受信者**：対象期間（1年間）に1回以上Giselleにログインまたはアクティビティを記録した全ユーザーが対象となる。マーケティングメールのオプトアウトを選択しているユーザーは除外される。また、アカウントが停止・削除されたユーザーも対象外となる。

**通知内容の概要**：メールには「{年度} in Review - A Year of Building Together」というテーマのもと、ユーザーのGiselleでの活動に関する情報が含まれる。Node Builderの利用状況、ビルダーコミュニティでの活動、今後のアップデート予告などが記載される。ヒーローイメージと共に視覚的に訴求力のあるデザインで送信される。

**期待されるアクション**：ユーザーはメール内の「View Your Year in Giselle」ボタンをクリックして、詳細な年間振り返りページにアクセスすることが期待される。これにより、ユーザーの再訪問を促し、プラットフォームへのエンゲージメントを深める。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

- 対象年度にアクティビティがあるユーザーを抽出
- マーケティングメールの受信設定がオプトインのユーザーのみ
- アカウントがアクティブ状態のユーザーのみ

## 通知テンプレート

### メール通知の場合

| 項目 | 内容 |
|-----|------|
| 送信元アドレス | marketing@giselles.ai（想定） |
| 送信元名称 | Giselle |
| 件名 | {year} in Review - A Year of Building Together |
| 形式 | HTML |

### 本文テンプレート

```html
<!-- ヒーローイメージセクション -->
<img src="year-in-review-1.jpg" alt="Year in review" />

<!-- メインコンテンツ -->
<h1>{currentYear} in Review - A Year of Building Together.</h1>

<p>
From launching Node Builder to growing our builder community, this year
has been full of creation and connection.
</p>

<p>
Here's a look back at the moments that defined {currentYear} - and a
glimpse of what's next.
</p>

<button href="{viewYearInGiselleUrl}">View Your Year in Giselle →</button>

<!-- フッター -->
<footer>
  <!-- Giselleロゴ、ソーシャルリンク、著作権表示 -->
</footer>
```

### 添付ファイル

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

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| currentYear | 対象年度 | システム日付から取得 | Yes |
| viewYearInGiselleUrl | 年間振り返りページURL | 定数（https://studio.giselles.ai/year-in-review） | Yes |
| heroImageSrc | ヒーローイメージURL | getEmailAssetUrl関数 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| バッチ/スケジュール | 年間キャンペーンスケジュール | マーケティングオプトイン済み | 12月下旬〜1月上旬に一斉送信 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| マーケティングメールオプトアウト | ユーザーがマーケティングメールの受信を拒否している場合 |
| アカウント非アクティブ | アカウントが停止または削除されている場合 |
| 対象年度にアクティビティなし | 1年間に一度もログインやアクティビティがない場合 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[年間キャンペーン開始] --> B[対象ユーザー抽出]
    B --> C{マーケティングオプトイン?}
    C -->|Yes| D{年間アクティビティあり?}
    C -->|No| E[送信スキップ]
    D -->|Yes| F[テンプレート変数展開]
    D -->|No| E
    F --> G[ヒーローイメージURL生成]
    G --> H[メール送信実行]
    H --> I{送信結果}
    I -->|成功| J[送信ログ記録]
    I -->|失敗| K[リトライ処理]
    J --> L[終了]
    K --> L
    E --> L
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| users | ユーザー情報取得 | メールアドレス、マーケティング設定 |
| user_activities | 年間アクティビティ確認 | 対象年度のログイン・操作履歴 |

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

#### users

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| email | 送信先メールアドレス | アクティブユーザー |
| marketing_opt_in | マーケティング配信可否 | true |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| email_send_logs | INSERT | メール送信ログ |

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

| 操作 | 項目（カラム名） | 更新値 | 備考 |
|-----|-----------------|-------|------|
| INSERT | email_type | 'year_in_review' | 通知種別 |
| INSERT | recipient_email | {ユーザーメール} | 送信先 |
| INSERT | sent_at | 送信日時 | タイムスタンプ |
| INSERT | status | 'sent'/'failed' | 送信結果 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 送信失敗 | メールサーバー接続エラー | リトライ後、ログに記録 |
| テンプレートエラー | 画像URLが取得できない | デフォルト画像を使用 |
| 宛先不正 | メールアドレス形式不正 | 送信スキップ、ログに記録 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 3回 |
| リトライ間隔 | 指数バックオフ（1分、5分、15分） |
| リトライ対象エラー | 一時的なネットワークエラー、サーバーエラー |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | マーケティングプラットフォームの制限に準拠 |
| 1日あたり上限 | なし（バッチ処理で一括送信） |

### 配信時間帯

年末年始の適切な時間帯（各タイムゾーンに応じて調整）に送信。深夜・早朝の送信は避ける。

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

- メールアドレスは個人情報として適切に取り扱う
- 送信ログには必要最小限の情報のみ記録
- パーソナライズデータは暗号化された経路で送信
- オプトアウトリンクをフッターに必ず含める

## 備考

- テンプレートファイル: `apps/studio.giselles.ai/emails/marketing/special/year-in-review.tsx`
- React Emailを使用したHTMLメール生成
- 共通コンポーネント: EmailHeader、EmailFooter、EmailFonts
- ヒーローイメージはgetEmailAssetUrl関数で動的に取得

---

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

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

### 推奨読解順序

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

まず、メールテンプレートで使用されるPropsインターフェースとスタイル定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | year-in-review.tsx | `apps/studio.giselles.ai/emails/marketing/special/year-in-review.tsx` | YearInReviewEmailPropsインターフェース（29-31行目）でテンプレート変数を確認 |

**読解のコツ**: React Emailのコンポーネント構造に慣れていない場合、@react-email/componentsのドキュメントを参照すると理解が深まる。

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

メールテンプレートのメインコンポーネントを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | year-in-review.tsx | `apps/studio.giselles.ai/emails/marketing/special/year-in-review.tsx` | YearInReviewEmail関数コンポーネント（33-81行目）がメールの構造を定義 |

**主要処理フロー**:
1. **36行目**: getEmailAssetUrl関数でヒーローイメージURLを取得
2. **37行目**: 現在の年度をnew Date().getFullYear()で取得
3. **44行目**: Previewコンポーネントでメールクライアントのプレビュー文を設定
4. **49-56行目**: ヒーローイメージセクションのレンダリング
5. **57-72行目**: メインコンテンツ（見出し、本文、CTAボタン）のレンダリング
6. **77行目**: EmailFooterコンポーネントでフッターを描画

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

メールで使用される共通UIコンポーネントを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | email-header.tsx | `apps/studio.giselles.ai/emails/components/email-header.tsx` | EmailHeaderコンポーネントでロゴと見出しを描画 |
| 3-2 | email-footer.tsx | `apps/studio.giselles.ai/emails/components/email-footer.tsx` | EmailFooterコンポーネントでフッター（ロゴ、リンク、ソーシャル、著作権）を描画 |
| 3-3 | email-fonts.tsx | `apps/studio.giselles.ai/emails/components/email-fonts.tsx` | フォント定義を提供 |

**主要処理フロー**:
- **email-footer.tsx 5-122行目**: ソーシャルアイコン、製品リンク、著作権表示を含むフッター全体を構成

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

```
YearInReviewEmail (year-in-review.tsx)
    |
    +-- Html
    |     +-- Head
    |     |     +-- EmailFonts (email-fonts.tsx)
    |     |
    |     +-- Preview
    |     +-- Body
    |           +-- Container
    |                 +-- EmailHeader (email-header.tsx)
    |                 |     +-- Img (logo)
    |                 |
    |                 +-- Section (imageSection)
    |                 |     +-- Img (heroImage)
    |                 |
    |                 +-- Section (content)
    |                 |     +-- Heading
    |                 |     +-- Text
    |                 |     +-- Button
    |                 |
    |                 +-- Section (topBorder)
    |
    +-- EmailFooter (email-footer.tsx)
          +-- Container
                +-- Section
                      +-- Img (footerLogo)
                      +-- Text (links)
                      +-- Section (socialIcons)
                      +-- Text (copyright)
                      +-- Text (explanation)
```

### データフロー図

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

viewYearInGiselleUrl ──────> YearInReviewEmail ──────────> HTML Email
(Props)                     コンポーネント
                                  |
getEmailAssetUrl() ──────> heroImageSrc ──────────> <Img src={...} />
                                  |
new Date().getFullYear() -> currentYear ──────> {currentYear} in Review
                                  |
EmailHeader ─────────────> ヘッダーセクション ──────> <Section>
                                  |
EmailFooter ─────────────> フッターセクション ──────> <Container>
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| year-in-review.tsx | `apps/studio.giselles.ai/emails/marketing/special/year-in-review.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-fonts.tsx | `apps/studio.giselles.ai/emails/components/email-fonts.tsx` | ソース | フォント定義コンポーネント |
| index.ts | `apps/studio.giselles.ai/emails/components/index.ts` | ソース | コンポーネントエクスポート |
| email-assets.ts | `apps/studio.giselles.ai/emails/utils/email-assets.ts` | ソース | 画像URL生成ユーティリティ |
