# 通知設計書 4-組織名更新成功

## 概要

本ドキュメントは、Liamアプリケーションにおける組織名更新成功時のUI通知（トースト）の設計仕様を定義する。組織管理者が組織設定画面で組織名を変更し、正常に更新された場合に表示される成功通知について、表示仕様、トリガー条件、処理フローを詳細に記載する。

### 本通知の処理概要

組織名更新成功通知は、組織設定画面（General設定）で組織名を変更し、保存処理が正常に完了した際に表示されるトースト通知である。

**業務上の目的・背景**：組織名の変更は、会社名変更やブランディング変更に伴う重要な操作である。更新成功をユーザーに明確にフィードバックすることで、変更が確実に反映されたことを確認させ、誤操作による混乱を防止する。また、チーム内の他メンバーにも新しい組織名が表示されるようになるため、変更の完了を確認できることが重要である。

**通知の送信タイミング**：組織設定画面（`/organizations/{organizationId}/settings/general`）で組織名入力フィールドに新しい名前を入力し、「Save」ボタンを押下した後、サーバーアクション`updateOrganizationAction`が正常に完了した時点で表示される。

**通知の受信者**：組織名更新操作を実行した組織管理者本人。現在表示している設定画面上でトースト通知が表示される。

**通知内容の概要**：「Updated」というタイトルと「Organization name has been successfully updated」という説明文が、成功（success）ステータスのトースト通知として表示される。

**期待されるアクション**：ユーザーは組織名の更新が完了したことを確認し、設定画面での作業を続けるか、他のページへ遷移する。

## 通知種別

UI通知（トースト）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（サーバーアクション完了後に即座に表示） |
| 優先度 | 中 |
| リトライ | なし（UI表示のため不要） |

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

組織名更新操作を実行したユーザーの現在のページ上でトースト通知を表示する。

## 通知テンプレート

### UI通知の場合

| 項目 | 内容 |
|-----|------|
| タイトル | Updated |
| 説明文 | Organization name has been successfully updated |
| ステータス | success |
| 表示位置 | header（ヘッダー下部） |

### 本文テンプレート

```
タイトル: Updated
説明: Organization name has been successfully updated
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| なし | - | - | UI通知のため添付ファイルなし |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| なし | - | - | 固定文言のため変数なし（descriptionはサーバーアクションのmessageを使用） |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 画面操作 | 組織名保存ボタン押下 | updateOrganizationActionが成功 | updateState.successがtrueになった時点 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 更新失敗時 | updateState.errorが存在する場合は表示しない（エラートースト表示） |
| 初期状態 | updateState.successがfalseの場合は表示しない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[ユーザーがSaveボタン押下] --> B[updateOrganizationAction実行]
    B --> C[フォームデータバリデーション]
    C -->|バリデーション成功| D[updateOrganizationName呼び出し]
    C -->|バリデーション失敗| E[エラーレスポンス返却]
    D -->|成功| F[成功レスポンス返却]
    D -->|失敗| E
    F --> G[updateState更新 success=true]
    E --> H[updateState更新 error=メッセージ]
    G --> I[useEffect検知]
    H --> J[useEffect検知]
    I --> K[成功トースト表示]
    J --> L[エラートースト表示]
    K --> M[終了]
    L --> M
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| organizations | 組織情報の更新対象確認 | 更新前の存在確認 |

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

#### organizations

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| id | 更新対象の特定 | `WHERE id = ${organizationId}` |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| organizations | UPDATE | 組織名（name）の更新 |

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

| 操作 | 項目（カラム名） | 更新値 | 備考 |
|-----|-----------------|-------|------|
| - | - | - | UI通知のため送信ログなし |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| なし | - | 成功通知のためエラーケースなし |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし（UI表示のため制限不要） |
| 1日あたり上限 | なし |

### 配信時間帯

特に制限なし。ユーザー操作に応じて即座に表示される。

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

- 組織名の更新は認可されたユーザー（組織管理者）のみ実行可能
- フォームデータはサーバーサイドでvalibotによりバリデーション
- 組織名はトリム処理され、空文字列は拒否される

## 備考

- React 19のuseActionStateフックを使用してフォームの状態管理を実装
- useEffectでupdateStateの変更を監視し、success時にトーストを表示
- descriptionにはサーバーアクションから返されるmessageフィールドの値を使用

---

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

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

### 推奨読解順序

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

まず、サーバーアクションの状態型定義を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | organizationClientActions.ts | `frontend/apps/app/components/GeneralPage/components/GeneralPageClient/actions/organizationClientActions.ts` | ActionState型（9-13行目）で状態構造を理解する |

**読解のコツ**: ActionStateはunion型で、success/errorの状態を型安全に管理している。

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

処理の起点となるUIコンポーネントを特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | GeneralPageClient.tsx | `frontend/apps/app/components/GeneralPage/components/GeneralPageClient/GeneralPageClient.tsx` | useActionState（24-28行目）とuseEffect（38-52行目）でフォーム状態管理とトースト表示を理解する |

**主要処理フロー**:
1. **24-28行目**: useActionStateでupdateOrganizationActionをラップ
2. **38-52行目**: useEffectでupdateStateを監視
3. **39-44行目**: updateState.success時に成功トースト表示
4. **45-50行目**: updateState.error時にエラートースト表示

#### Step 3: サーバーアクションを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | organizationClientActions.ts | `frontend/apps/app/components/GeneralPage/components/GeneralPageClient/actions/organizationClientActions.ts` | updateOrganizationAction関数（32-68行目）でバリデーションと更新処理を理解する |

**主要処理フロー**:
- **37-44行目**: organizationIdのバリデーション
- **46-50行目**: 組織名のバリデーション
- **55-62行目**: updateOrganizationName呼び出しとエラーハンドリング
- **64-67行目**: 成功レスポンス返却

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

```
GeneralPageClient.tsx
    │
    ├─ useActionState(updateOrganizationAction)
    │      │
    │      └─ updateAction (formに渡す)
    │
    └─ useEffect([updateState])
           │
           ├─ [success時] toast({ title: 'Updated', ... })
           │
           └─ [error時] toast({ title: 'Error', ... })

updateOrganizationAction
    │
    ├─ v.safeParse() [Validation]
    │
    └─ updateOrganizationName()
           │
           └─ supabase.from('organizations').update()
```

### データフロー図

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

フォーム送信             ───▶ updateOrganizationAction    ───▶ updateState更新
(organizationId, name)        │                               │
                              │                               ▼
                              ├─▶ バリデーション          useEffect検知
                              │                               │
                              └─▶ DB更新                   トースト表示
                                                          (成功/失敗)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| GeneralPageClient.tsx | `frontend/apps/app/components/GeneralPage/components/GeneralPageClient/GeneralPageClient.tsx` | ソース | 組織設定UI・フォーム管理 |
| organizationClientActions.ts | `frontend/apps/app/components/GeneralPage/components/GeneralPageClient/actions/organizationClientActions.ts` | ソース | 組織更新サーバーアクション |
| updateOrganizationName.ts | `frontend/apps/app/components/GeneralPage/components/GeneralPageClient/actions/updateOrganizationName.ts` | ソース | 組織名更新DB処理 |
| Toast.tsx | `frontend/packages/ui/src/components/Toast/Toast.tsx` | ソース | トースト通知UIコンポーネント |
| useToast.tsx | `frontend/packages/ui/src/components/Toast/useToast.tsx` | ソース | トーストフック |
