# 画面設計書 26-通知一覧画面

## 概要

本ドキュメントは、Chatwootの通知一覧画面の設計仕様を記述したものである。

### 本画面の処理概要

通知一覧画面は、ユーザーに届いた通知を一覧表示し、管理する機能を提供する画面である。

**業務上の目的・背景**：顧客サポート業務において、タイムリーな通知の確認は迅速な対応に不可欠である。本画面により、オペレーターは新しい会話の割り当て、メンション、会話の更新など、重要なイベントの通知を一元的に確認・管理できる。これにより、見落としを防ぎ、顧客対応のスピードと品質を向上させることができる。

**画面へのアクセス方法**：ダッシュボードのヘッダーにある通知ベルアイコンをクリック、またはサイドバーの「通知」メニューから直接アクセスする。URLは `/app/accounts/:accountId/notifications` の形式となる。

**主要な操作・処理内容**：
1. 通知一覧の表示
2. 通知から関連会話への遷移
3. 全通知の一括既読処理
4. ページネーションによる一覧のページ切り替え

**画面遷移**：ダッシュボードの各画面からヘッダー経由でアクセス可能。各通知をクリックすると関連する会話詳細画面に遷移する。

**権限による表示制御**：すべてのログインユーザーがアクセス可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 96 | 通知一覧・管理 | 主機能 | 通知の一覧表示 |
| 97 | 一括既読 | 補助機能 | 全通知を既読にする処理 |
| 98 | 未読カウント | API連携 | 未読通知数の表示 |
| 100 | スヌーズ | 補助機能 | 通知の一時停止 |

## 画面種別

一覧

## URL/ルーティング

| パス | ルート名 | 説明 |
|------|----------|------|
| `/app/accounts/:accountId/notifications` | notifications_index | 通知一覧画面 |

## 入出力項目

### 入力項目

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| page | クエリパラメータ | 任意 | ページ番号（デフォルト: 1） |

### 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| notifications | Array | 通知オブジェクトの配列 |
| meta | Object | ページネーション情報（count, currentPage, unreadCount） |

## 表示項目

### 通知一覧

| 項目名 | 説明 | データソース |
|--------|------|--------------|
| 通知タイプ | 通知の種類（割り当て、メンションなど） | notification.notification_type |
| 関連会話 | 通知に関連する会話情報 | notification.primary_actor |
| 送信者 | 通知を発生させたユーザー | notification.secondary_actor |
| 作成日時 | 通知の作成日時 | notification.created_at |
| 既読状態 | 既読/未読の状態 | notification.read_at |

### ヘッダー情報

| 項目名 | 説明 |
|--------|------|
| 未読件数 | 未読通知の数 |
| 一括既読ボタン | 全通知を既読にするボタン |

## イベント仕様

### 1-画面初期表示

画面マウント時、通知一覧を取得する。

**処理フロー**:
1. `notifications/get` アクションを実行（page: 1）
2. 結果をストアに保存し、画面に表示

### 2-ページ変更

ページネーションコントロールでページを切り替える。

**処理フロー**:
1. `onPageChange`を新しいページ番号で実行
2. URLにpageパラメータを追加（pushState）
3. `notifications/get`で新しいページのデータを取得

### 3-通知クリック（会話遷移）

通知行をクリックして関連会話に遷移する。

**処理フロー**:
1. `openConversation`を実行
2. 通知タイプをトラッキング
3. `notifications/read`アクションで既読に更新
4. 関連会話の詳細画面に遷移

### 4-全通知一括既読

一括既読ボタンをクリックする。

**処理フロー**:
1. `onMarkAllDoneClick`を実行
2. トラッキングイベント送信
3. `notifications/readAll`アクションを実行
4. 未読カウントを0に更新

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面初期表示 | notifications | SELECT | 通知一覧取得 |
| ページ変更 | notifications | SELECT | 指定ページの通知取得 |
| 通知クリック | notifications | UPDATE | read_atを現在時刻に更新 |
| 全通知一括既読 | notifications | UPDATE | 全通知のread_atを更新 |

### テーブル別更新項目詳細

#### notifications

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | * | user_id = 現在のユーザー | ページネーション付き |
| UPDATE | read_at | 現在時刻 | 既読処理時 |

## メッセージ仕様

| 種別 | コード | メッセージ | 表示条件 |
|------|--------|-----------|----------|
| 情報 | - | ローディング状態 | データ取得中（uiFlags.isFetching） |
| 情報 | - | 通知がありません | 通知が0件の場合 |

## 例外処理

| 例外条件 | 処理内容 |
|----------|---------|
| 通知が0件 | 空状態を表示 |
| API通信エラー | ローディング状態を解除 |
| 会話が見つからない | 通知クリック時にエラーハンドリング |

## 備考

- 通知はページサイズ15件でページネーション
- 通知クリック時にAnalyticsトラッキングを実行
- 通知タイプ：conversation_assignment, conversation_mention, participating_conversation_new_message など
- 未読カウントはヘッダーのベルアイコンにも表示される

---

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

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

### 推奨読解順序

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

まず、通知のデータ構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.js | `app/javascript/dashboard/store/modules/notifications/index.js` | stateの構造（records, meta, uiFlags） |

**読解のコツ**: Vuexストアの`state`オブジェクトを見ることで、どのようなデータが管理されているか把握できる。metaにunreadCountが含まれることに注目。

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

処理の起点となるVueコンポーネントを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | NotificationsView.vue | `app/javascript/dashboard/routes/dashboard/notifications/components/NotificationsView.vue` | 画面のメインコンポーネント |

**主要処理フロー**:
1. **行15-20**: mapGettersで必要なデータを取得（meta, records, uiFlags）
2. **行22-24**: mountedで通知一覧を取得
3. **行26-29**: `onPageChange`でページ切り替え処理
4. **行30-51**: `openConversation`で通知から会話へ遷移
5. **行52-55**: `onMarkAllDoneClick`で一括既読処理

#### Step 3: Vuexストアアクションを理解する

通知管理のビジネスロジックを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | actions.js | `app/javascript/dashboard/store/modules/notifications/actions.js` | get, read, readAllアクション |

**主要処理フロー**:
- **行5-20**: `get`アクションで通知一覧取得
- **行54-67**: `read`アクションで既読処理
- **行78-89**: `readAll`アクションで一括既読

#### Step 4: APIレイヤーを理解する

バックエンドとの通信処理を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | notifications.js | `app/javascript/dashboard/api/notifications.js` | get, read, readAllメソッド |

**主要処理フロー**:
- **行9-19**: `get`メソッドでGETリクエスト
- **行29-33**: `read`メソッドで既読POSTリクエスト
- **行40-42**: `readAll`メソッドで一括既読POSTリクエスト

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

```
NotificationsView.vue (View層)
    │
    ├─ mounted
    │      └─ store.dispatch('notifications/get', { page: 1 })
    │             └─ NotificationsAPI.get()
    │                    └─ axios.get('/notifications')
    │
    ├─ onPageChange (ページ変更時)
    │      └─ store.dispatch('notifications/get', { page })
    │
    ├─ openConversation (通知クリック時)
    │      ├─ useTrack() (トラッキング)
    │      ├─ store.dispatch('notifications/read')
    │      │      └─ NotificationsAPI.read()
    │      └─ router.push() (会話画面へ遷移)
    │
    └─ onMarkAllDoneClick (一括既読)
           ├─ useTrack() (トラッキング)
           └─ store.dispatch('notifications/readAll')
                  └─ NotificationsAPI.readAll()
```

### データフロー図

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

page (URL) ─────────────▶ notifications/get
                                │
                                ▼
                         NotificationsAPI.get()
                                │
                                ▼
                         Rails API (/api/v1/accounts/:account_id/notifications)
                                │
                                ▼
                         Vuexストア更新 ───▶ 画面表示更新
                                                    │
                                                    ├─ NotificationTable表示
                                                    └─ TableFooter（ページネーション）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| NotificationsView.vue | `app/javascript/dashboard/routes/dashboard/notifications/components/NotificationsView.vue` | ソース | メイン画面コンポーネント |
| NotificationTable.vue | `app/javascript/dashboard/routes/dashboard/notifications/components/NotificationTable.vue` | ソース | 通知テーブルコンポーネント |
| index.js | `app/javascript/dashboard/store/modules/notifications/index.js` | ソース | Vuexストア定義 |
| actions.js | `app/javascript/dashboard/store/modules/notifications/actions.js` | ソース | Vuexアクション定義 |
| getters.js | `app/javascript/dashboard/store/modules/notifications/getters.js` | ソース | Vuexゲッター定義 |
| mutations.js | `app/javascript/dashboard/store/modules/notifications/mutations.js` | ソース | Vuexミューテーション定義 |
| notifications.js | `app/javascript/dashboard/api/notifications.js` | ソース | 通知API |
| TableFooter.vue | `app/javascript/dashboard/components/widgets/TableFooter.vue` | ソース | ページネーションコンポーネント |
| events.js | `app/javascript/dashboard/helper/AnalyticsHelper/events.js` | ソース | トラッキングイベント定義 |
