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

## 概要

本ドキュメントは、Fizzyアプリケーションにおける通知一覧画面の設計仕様を記述したものです。

### 本画面の処理概要

通知一覧画面は、ユーザーに対する通知を未読・既読に分類して一覧表示する画面です。カードへのコメント、アサイン、メンションなど、ユーザーに関連するアクティビティが通知として表示されます。

**業務上の目的・背景**：チームでカンバンボードを運用する際、自分に関連する更新を見逃さないことが重要です。本画面は、コメントの追加、担当者のアサイン、メンションなどのアクティビティを通知として集約し、ユーザーが効率的に確認・対応できるようにします。未読通知と既読通知を分離して表示することで、優先度の高い情報に素早くアクセスできます。

**画面へのアクセス方法**：ヘッダーの通知アイコン（ベルアイコン）をクリック、または通知トレイから「すべての通知を見る」を選択することでアクセスできます。

**主要な操作・処理内容**：
1. 未読通知の一覧を確認
2. 既読通知の一覧を確認（ページネーション対応）
3. 個別の通知を既読にする
4. 全通知を一括で既読にする
5. 通知をクリックして関連カードへ遷移

**画面遷移**：
- 遷移元：ホーム画面、通知トレイ画面
- 遷移先：カード詳細画面（通知クリック時）、通知設定画面

**権限による表示制御**：ユーザー自身の通知のみが表示されます。他のユーザーの通知にはアクセスできません。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 57 | 通知一覧表示 | 主機能 | 未読・既読の通知一覧を表示 |
| 58 | 通知既読 | 補助機能 | 通知を既読にする |
| 59 | 通知一括既読 | 補助機能 | 複数の通知を一括で既読にする |

## 画面種別

一覧

## URL/ルーティング

- **パス**: `/notifications`
- **HTTPメソッド**: GET
- **コントローラ**: `NotificationsController#index`

## 入出力項目

| 項目名 | 項目ID | 入出力 | データ型 | 必須 | 最大長 | 説明 |
|--------|--------|--------|----------|------|--------|------|
| ページ番号 | page | 入力 | Integer | 任意 | - | ページネーション用 |

## 表示項目

| 項目名 | 説明 | データ取得元 |
|--------|------|-------------|
| ページタイトル | 「Notifications」固定 | - |
| 未読通知セクション | 未読の通知一覧 | @unread |
| 「New for you」ヘッダー | 未読セクションのタイトル | - |
| 「Mark all as read」ボタン | 一括既読ボタン | - |
| 既読通知セクション | 既読の通知一覧 | @page.records |
| 「Previously seen」ヘッダー | 既読セクションのタイトル | - |
| 通知設定リンク | 通知設定画面へのリンク | - |
| 「Nothing new for you」 | 未読がない場合のメッセージ | - |

## イベント仕様

### 1-通知クリック

通知をクリックして関連カードへ遷移します。

- **トリガー**: 通知項目をクリック
- **処理フロー**:
  1. 通知に関連付けられたカードIDを取得
  2. カード詳細画面へ遷移
- **遷移先**: `/cards/:id`

### 2-個別既読

個別の通知を既読にします。

- **トリガー**: 通知の既読ボタンをクリック
- **処理フロー**:
  1. POST `/notifications/:id/reading` を送信
  2. 通知のread_atを更新
  3. Turbo Streamで通知を既読セクションに移動
- **データ更新**: notifications.read_at = 現在時刻

### 3-一括既読

すべての未読通知を既読にします。

- **トリガー**: 「Mark all as read」ボタンをクリック
- **処理フロー**:
  1. POST `/notifications/bulk_reading` を送信
  2. 未読通知すべてのread_atを更新
  3. ページをリロード
- **データ更新**: notifications.read_at = 現在時刻（対象：未読すべて）

### 4-通知設定へ遷移

通知設定画面へ遷移します。

- **トリガー**: 設定アイコンをクリック
- **遷移先**: `/notifications/settings`

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | notifications | SELECT | 未読・既読通知を取得 |
| 個別既読 | notifications | UPDATE | read_atを更新 |
| 一括既読 | notifications | UPDATE | 複数の通知のread_atを更新 |

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

#### notifications

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | - | user_id = Current.user.id AND read_at IS NULL | 未読通知取得 |
| SELECT | - | user_id = Current.user.id AND read_at IS NOT NULL | 既読通知取得 |
| UPDATE | read_at | 現在時刻 | 既読処理 |
| UPDATE | unread_count | 0 | 既読処理時にリセット |

## メッセージ仕様

| 種別 | メッセージID | メッセージ内容 | 表示条件 |
|------|------------|---------------|---------|
| 情報 | new_for_you | New for you | 未読通知があるとき |
| 情報 | nothing_new | Nothing new for you | 未読通知がないとき |
| 情報 | previously_seen | Previously seen | 既読セクションのヘッダー |
| 情報 | showing_limit | Showing the 500 most recent (X are hidden) | 未読が500件超のとき |

## 例外処理

| 例外 | 発生条件 | 処理内容 |
|-----|---------|---------|
| 認証エラー | 未ログイン状態 | ログイン画面へリダイレクト |

## 備考

- 未読通知は最大500件まで表示（APIの場合は100件）
- 既読通知はページネーション対応
- Stimulusコントローラ（badge, navigable-list）でインタラクティブ操作を制御
- Action CableでリアルタイムにWebSocket経由で通知を受信
- 通知はカードごとにユニーク（同一カードの通知は集約）

---

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

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

### 推奨読解順序

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

通知のデータモデルと関連するテーブル構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | notification.rb | `app/models/notification.rb` | 通知モデルの定義、スコープ、既読/未読処理 |
| 1-2 | schema.rb | `db/schema.rb` | notificationsテーブル（387-404行目）の構造 |

**読解のコツ**: Notificationモデルは`scope :unread`と`scope :read`で未読・既読を分離。`read`と`unread`メソッドで状態を切り替えます。`belongs_to :source, polymorphic: true`で様々な通知元に対応。

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

コントローラのindexアクションを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | notifications_controller.rb | `app/controllers/notifications_controller.rb` | indexアクションの実装、未読/既読の取得 |

**主要処理フロー**:
1. **2-3行目**: MAX_UNREAD_NOTIFICATIONSで未読の上限を設定（500件/API:100件）
2. **6行目**: 未読通知を取得（ページネーションパラメータがない場合のみ）
3. **7行目**: 既読通知をページネーション取得

#### Step 3: ビューレイヤーを理解する

通知一覧画面のテンプレート構造を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.html.erb | `app/views/notifications/index.html.erb` | メイン画面テンプレート |
| 3-2 | _unread_notifications.html.erb | `app/views/notifications/index/_unread_notifications.html.erb` | 未読セクションパーシャル |
| 3-3 | _read_notifications.html.erb | `app/views/notifications/index/_read_notifications.html.erb` | 既読セクションパーシャル |
| 3-4 | _notification.html.erb | `app/views/notifications/_notification.html.erb` | 通知アイテムパーシャル |

**主要処理フロー**:
- **index.html.erb 18-22行目**: Stimulusコントローラ（badge, navigable-list）の設定
- **index.html.erb 20-21行目**: 未読・既読セクションをレンダリング
- **_unread_notifications 5行目**: 一括既読ボタン

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

```
NotificationsController#index
    │
    ├─ @unread = Current.user.notifications.unread
    │      │       .ordered.preloaded.limit(500)
    │      │
    │      └─ Notification.scope :unread (read_at IS NULL)
    │
    ├─ set_page_and_extract_portion_from
    │      │
    │      └─ Current.user.notifications.read.ordered.preloaded
    │             │
    │             └─ Notification.scope :read (read_at IS NOT NULL)
    │
    └─ render index.html.erb
           │
           ├─ render _unread_notifications.html.erb
           │      │
           │      └─ render _notification.html.erb (collection)
           │
           └─ render _read_notifications.html.erb
                  │
                  └─ render _notification.html.erb (collection)
```

### データフロー図

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

ページパラメータ         NotificationsController#index
  page ─────────────────▶ 未読/既読分離取得
                              │
                        ┌─────┴─────┐
                        │           │
                   未読取得     既読取得
                   (max 500)   (paginated)
                        │           │
                        ▼           ▼
                    @unread    @page.records
                        │           │
                        └─────┬─────┘
                              │
                              ▼
                        index.html.erb
                              │
                        ┌─────┴─────┐
                        │           │
                   未読セクション   既読セクション
                        │           │
                        └─────┬─────┘
                              │
                              ▼
                        画面表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| notifications_controller.rb | `app/controllers/notifications_controller.rb` | コントローラ | 通知一覧の表示制御 |
| index.html.erb | `app/views/notifications/index.html.erb` | テンプレート | メイン画面 |
| _unread_notifications.html.erb | `app/views/notifications/index/_unread_notifications.html.erb` | パーシャル | 未読セクション |
| _read_notifications.html.erb | `app/views/notifications/index/_read_notifications.html.erb` | パーシャル | 既読セクション |
| _notification.html.erb | `app/views/notifications/_notification.html.erb` | パーシャル | 通知アイテム |
| notification.rb | `app/models/notification.rb` | モデル | 通知データ定義 |
| routes.rb | `config/routes.rb` | 設定 | ルーティング定義（112-121行目） |
| schema.rb | `db/schema.rb` | スキーマ | notificationsテーブル定義 |
