# 画面設計書 7-アカウント停止画面

## 概要

本ドキュメントは、Chatwootアプリケーションのアカウント停止画面に関する設計書です。アカウントが停止された際にユーザーに状況を通知し、サポートへの連絡を促す画面について記述しています。

### 本画面の処理概要

アカウント停止画面は、ユーザーのアカウントが管理者によって停止された場合に表示される画面です。停止状態であることをユーザーに通知し、サポートウィジェットを通じて問い合わせができるようにします。

**業務上の目的・背景**：アカウントの不正利用、支払い問題、利用規約違反などの理由でアカウントが停止される場合があります。本画面は、停止されたユーザーに対して状況を明確に伝え、適切なサポートチャネルを提供することで、ユーザーの混乱を最小限に抑えます。Chatwootサポートウィジェットを表示することで、ユーザーが直接問い合わせを行えるようにしています。

**画面へのアクセス方法**：ユーザーがログイン後、アカウントが停止状態であることが検出された場合に自動的にリダイレクトされます。URL直接アクセスも可能です（`/app/accounts/:accountId/suspended`）。

**主要な操作・処理内容**：
1. アカウント停止状態の確認と表示
2. Chatwootサポートウィジェットの表示
3. サポートへの問い合わせ（ウィジェット経由）

**画面遷移**：
- 遷移元：ログイン後のアカウント状態チェック、ダッシュボード内のナビゲーション
- 遷移先：なし（停止解除後にダッシュボードにアクセス可能）

**権限による表示制御**：
- administrator、agent、custom_role権限を持つユーザーがアクセス可能
- アカウントが停止されている場合にのみ表示

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 8 | アカウント作成・管理 | 主機能 | 停止されたアカウントの状態表示 |

## 画面種別

エラー（アカウント状態通知）

## URL/ルーティング

| パス | ルート名 | 説明 |
|------|----------|------|
| `/app/accounts/:accountId/suspended` | `account_suspended` | アカウント停止画面 |

### ルートパラメータ

| パラメータ | 型 | 説明 |
|-----------|-----|------|
| `accountId` | String | アカウントID |

### ルートメタ情報

| メタキー | 値 | 説明 |
|---------|-----|------|
| `permissions` | `['administrator', 'agent', 'custom_role']` | アクセス権限 |

## 入出力項目

### 入力項目

本画面ではユーザーによる入力項目はありません。

### 出力項目

| 項目名 | 説明 | 表示条件 |
|--------|------|----------|
| タイトル | アカウント停止タイトル | 常時 |
| メッセージ | 停止理由と問い合わせ案内 | 常時 |

## 表示項目

| 項目名 | 説明 | 表示条件 |
|--------|------|----------|
| 空状態コンポーネント | EmptyStateコンポーネントによる表示 | 常時 |
| タイトル | 「アカウントが停止されています」 | 常時 |
| メッセージ | 停止状態の説明とサポート案内 | 常時 |
| サポートウィジェット | Chatwootサポートウィジェット | ウィジェット設定時 |

## イベント仕様

### 1-コンポーネントマウント時

**トリガー**: コンポーネントのマウント

**処理フロー**:
1. `toggleSupportWidgetVisibility`を呼び出し、サポートウィジェットを表示
2. `setupListenerForWidgetEvent`を呼び出し、ウィジェットイベントリスナーを設定

**データフロー**:
```
[コンポーネントマウント]
    │
    ├─ toggleSupportWidgetVisibility()
    │      │
    │      └─ window.$chatwoot.toggleBubbleVisibility('show')
    │
    └─ setupListenerForWidgetEvent()
           │
           └─ window.addEventListener('chatwoot:on-message', callback)
```

### 2-サポートウィジェットメッセージ受信

**トリガー**: ウィジェットでメッセージを受信した場合

**処理フロー**:
1. `chatwoot:on-message`イベントを検知
2. ウィジェットを表示状態に設定

## データベース更新仕様

### 操作別データベース影響一覧

本画面ではデータベースの更新は行いません。

## メッセージ仕様

| メッセージID | メッセージ種別 | メッセージ内容 | 表示条件 |
|-------------|---------------|---------------|----------|
| APP_GLOBAL.ACCOUNT_SUSPENDED.TITLE | 情報 | アカウントが停止されています | 常時 |
| APP_GLOBAL.ACCOUNT_SUSPENDED.MESSAGE | 情報 | サポートへお問い合わせください | 常時 |

## 例外処理

| 例外条件 | 状態・動作 |
|---------|----------|
| サポートウィジェット未設定 | ウィジェットなしで画面表示 |
| ウィジェットAPI未ロード | ウィジェット表示をスキップ |

## 備考

- Chatwootサポートウィジェット（`window.$chatwoot`）を使用してサポートへの問い合わせを提供
- ウィジェットは画面マウント時に自動的に表示される
- メッセージ受信時にウィジェットが再表示されるため、ユーザーが閉じても通知を見逃さない
- EmptyStateコンポーネントを使用して一貫したエラー表示を提供

---

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

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

### 推奨読解順序

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

アカウント停止状態で扱われるデータを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | dashboard.routes.js | `app/javascript/dashboard/routes/dashboard/dashboard.routes.js` | ルーティング定義と権限設定 |

**読解のコツ**: ルートメタ情報の`permissions`配列で、どのロールがこの画面にアクセスできるかを確認できます。

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

処理の起点となるVueコンポーネントを特定します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Index.vue | `app/javascript/dashboard/routes/dashboard/suspended/Index.vue` | アカウント停止画面のメインコンポーネント |

**主要処理フロー**:
1. **行5-8**: `toggleSupportWidgetVisibility`関数でウィジェット表示
2. **行11-14**: `setupListenerForWidgetEvent`関数でイベントリスナー設定
3. **行17-19**: `onMounted`ライフサイクルフックで初期化

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

```
Index.vue (アカウント停止画面)
    │
    └─ onMounted()
           │
           ├─ toggleSupportWidgetVisibility()
           │      │
           │      └─ window.$chatwoot.toggleBubbleVisibility('show')
           │
           └─ setupListenerForWidgetEvent()
                  │
                  └─ window.addEventListener('chatwoot:on-message', handler)
                         │
                         └─ toggleSupportWidgetVisibility()
```

### データフロー図

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

なし                   ──▶   Index.vue                  ──▶   画面表示
                             (onMounted)
                                 │
                                 ▼
                             [ウィジェット表示]
                             window.$chatwoot.toggleBubbleVisibility('show')
                                 │
                                 ▼
                             [イベントリスナー設定]
                             chatwoot:on-message
                                 │
                                 ▼
                             [EmptyState表示]
                             タイトル + メッセージ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Index.vue | `app/javascript/dashboard/routes/dashboard/suspended/Index.vue` | ソース | アカウント停止画面メインコンポーネント |
| dashboard.routes.js | `app/javascript/dashboard/routes/dashboard/dashboard.routes.js` | ソース | ルーティング定義 |
| EmptyState.vue | `app/javascript/dashboard/components/widgets/EmptyState.vue` | ソース | 空状態表示コンポーネント |
| en.json | `app/javascript/dashboard/i18n/locale/en/appGlobal.json` | 設定 | i18n翻訳ファイル |
