# 通知設計書 7-組織削除エラー

## 概要

本ドキュメントは、Liamアプリケーションにおける組織削除失敗時のUI通知（トースト）の設計仕様を定義する。組織管理者が組織設定画面で組織を削除しようとした際に、何らかの理由で削除に失敗した場合に表示されるエラー通知について、表示仕様、トリガー条件、処理フローを詳細に記載する。

### 本通知の処理概要

組織削除エラー通知は、組織設定画面（General設定）で組織を削除しようとした際に、バリデーションエラーまたはデータベース削除エラーが発生した場合に表示されるエラートースト通知である。

**業務上の目的・背景**：組織の削除が失敗した場合、ユーザーに明確なフィードバックを提供することで、問題の認識と対処を促す。特に、確認テキストの不一致（誤入力）による失敗は頻繁に発生する可能性があるため、適切なエラーメッセージでユーザーを導く必要がある。

**通知の送信タイミング**：組織設定画面（`/organizations/{organizationId}/settings/general`）で削除ボタンを押下し、確認ダイアログで確認テキストを入力して削除を確定した後、サーバーアクション`deleteOrganizationAction`がエラーを返した時点で表示される。

**通知の受信者**：組織削除操作を実行した組織管理者本人。現在表示している設定画面上でトースト通知が表示される（ページ遷移は行われない）。

**通知内容の概要**：「Error」というタイトルと、具体的なエラー内容を説明するdescriptionが、エラー（error）ステータスのトースト通知として表示される。

**期待されるアクション**：ユーザーはエラーメッセージを確認し、確認テキストを正しく入力し直して再度削除を試みる。

## 通知種別

UI通知（トースト）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（サーバーアクション完了後に即座に表示） |
| 優先度 | 高 |
| リトライ | なし（UI表示のため不要、ユーザーが手動で再試行） |

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

組織削除操作を実行したユーザーの現在のページ上でトースト通知を表示する。ページ遷移は行われない。

## 通知テンプレート

### UI通知の場合

| 項目 | 内容 |
|-----|------|
| タイトル | Error |
| 説明文 | deleteState.errorの値（エラー内容に応じて変動） |
| ステータス | error |
| 表示位置 | header（ヘッダー下部） |

### 本文テンプレート

```
タイトル: Error
説明: ${deleteState.error}
```

### 想定されるエラーメッセージ一覧

| エラーメッセージ | 発生条件 |
|----------------|---------|
| Invalid organization ID | 組織IDが空または無効な場合 |
| Confirmation text is required | 確認テキストが空の場合 |
| Organization not found | 組織が存在しない場合 |
| Confirmation text does not match organization name | 確認テキストと組織名が一致しない場合 |
| Failed to delete organization | データベース削除に失敗した場合 |

### 添付ファイル

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

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| deleteState.error | エラーメッセージ | サーバーアクションのレスポンス | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 画面操作 | 組織削除確定ボタン押下 | deleteOrganizationActionが失敗 | deleteState.errorが存在する場合 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 削除成功時 | deleteState.successがtrueの場合は表示しない（リダイレクト後に成功トースト表示） |
| 初期状態 | deleteState.errorがnullの場合は表示しない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[ユーザーが削除確定] --> B[deleteOrganizationAction実行]
    B --> C[organizationIdバリデーション]
    C -->|無効| D[Invalid organization ID エラー返却]
    C -->|有効| E[confirmTextバリデーション]
    E -->|空| F[Confirmation text is required エラー返却]
    E -->|有効| G[組織情報取得]
    G -->|存在しない| H[Organization not found エラー返却]
    G -->|存在する| I{確認テキスト一致確認}
    I -->|不一致| J[Confirmation text does not match... エラー返却]
    I -->|一致| K[deleteOrganization呼び出し]
    K -->|失敗| L[Failed to delete... エラー返却]
    K -->|成功| M[成功レスポンス返却]
    D --> N[deleteState.error設定]
    F --> N
    H --> N
    J --> N
    L --> N
    N --> O[useEffect検知]
    O --> P[エラートースト表示]
    P --> Q[終了]
    M --> R[sessionStorage保存→リダイレクト]
    R --> Q
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| organizations | 組織存在確認、組織名取得 | 確認テキスト照合に使用 |

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

#### organizations

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| name | 確認テキストとの照合 | `WHERE id = ${organizationId}` |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| なし | - | エラー時はデータベース更新なし |

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

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

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| バリデーションエラー | organizationIdが空または無効 | エラートースト表示、ユーザーに再試行を促す |
| バリデーションエラー | 確認テキストが空 | エラートースト表示、ユーザーに入力を促す |
| 存在確認エラー | 組織が存在しない | エラートースト表示、ページリロードを促す |
| 照合エラー | 確認テキストと組織名が不一致 | エラートースト表示、正しい組織名の入力を促す |
| データベースエラー | 削除クエリが失敗 | エラートースト表示、ユーザーに再試行を促す |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（ユーザー操作による手動リトライ） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

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

### 配信時間帯

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

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

- エラーメッセージには技術的な詳細情報を含めず、ユーザーフレンドリーな表現を使用
- 確認テキストの不一致エラーは、組織名を開示しない表現を使用
- サーバーサイドで全てのバリデーションを行い、不正な操作を拒否

## 備考

- React 19のuseActionStateフックを使用してフォームの状態管理を実装
- useEffectでdeleteState.errorの変更を監視し、errorが存在する場合にトーストを表示
- ページ遷移は行われず、ユーザーは同じページで再試行可能

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: `{ success: false; error: string; message?: undefined }`がエラー時の状態。

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | GeneralPageClient.tsx | `frontend/apps/app/components/GeneralPage/components/GeneralPageClient/GeneralPageClient.tsx` | useEffect（54-75行目）でエラー時のトースト表示処理を理解する |

**主要処理フロー**:
1. **54行目**: useEffectでdeleteStateを監視
2. **68-73行目**: deleteState.error時にエラートースト表示
3. **69行目**: title: 'Error'を設定
4. **70行目**: description: deleteState.errorを設定

#### Step 3: サーバーアクションのエラーケースを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | organizationClientActions.ts | `frontend/apps/app/components/GeneralPage/components/GeneralPageClient/actions/organizationClientActions.ts` | 各種エラーケース（81行目、90行目、100行目、107行目、116行目）を理解する |

**主要処理フロー**:
- **81行目**: `{ success: false, error: 'Invalid organization ID' }`
- **90行目**: `{ success: false, error: 'Confirmation text is required' }`
- **100行目**: `{ success: false, error: 'Organization not found' }`
- **104-108行目**: 確認テキスト不一致エラー
- **113-117行目**: 削除失敗エラー

#### Step 4: バリデーションスキーマを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | organizationClientActions.ts | `frontend/apps/app/components/GeneralPage/components/GeneralPageClient/actions/organizationClientActions.ts` | バリデーションスキーマ（26-29行目）を理解する |

**主要処理フロー**:
- **26-29行目**: confirmTextSchema - minLength(1)で空を拒否

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

```
GeneralPageClient.tsx
    │
    ├─ DeleteOrganizationButtonClient
    │      │
    │      └─ deleteAction (formに渡す)
    │
    └─ useEffect([deleteState])
           │
           └─ [error時] toast({ title: 'Error', description: error })

deleteOrganizationAction
    │
    ├─ [organizationId無効] return { success: false, error: '...' }
    │
    ├─ [confirmText空] return { success: false, error: '...' }
    │
    ├─ getOrganizationDetails()
    │      │
    │      └─ [存在しない] return { success: false, error: '...' }
    │
    ├─ [確認テキスト不一致] return { success: false, error: '...' }
    │
    └─ deleteOrganization()
           │
           └─ [失敗] return { success: false, error: '...' }
```

### データフロー図

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

削除確定                 ───▶ deleteOrganizationAction    ───▶ deleteState更新
(organizationId,              │                               │
 confirmText - 不正)          │                               ▼
                              └─▶ バリデーション/照合失敗   useEffect検知
                                    │                         │
                                    └─▶ error設定          エラートースト
                                                          (ページ遷移なし)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| GeneralPageClient.tsx | `frontend/apps/app/components/GeneralPage/components/GeneralPageClient/GeneralPageClient.tsx` | ソース | 削除UI・エラーハンドリング |
| organizationClientActions.ts | `frontend/apps/app/components/GeneralPage/components/GeneralPageClient/actions/organizationClientActions.ts` | ソース | 組織削除サーバーアクション・エラー生成 |
| DeleteOrganizationButtonClient.tsx | `frontend/apps/app/components/GeneralPage/components/GeneralPageClient/components/DeleteOrganizationButtonClient.tsx` | ソース | 削除確認ダイアログ |
| Toast.tsx | `frontend/packages/ui/src/components/Toast/Toast.tsx` | ソース | トースト通知UIコンポーネント |
| useToast.tsx | `frontend/packages/ui/src/components/Toast/useToast.tsx` | ソース | トーストフック |
