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

## 概要

本ドキュメントは、InvenTreeフロントエンドアプリケーションの「通知一覧画面」に関する設計仕様を記載する。

### 本画面の処理概要

本画面は、ユーザーに対して送信されたシステム通知を一覧形式で表示・管理するための画面である。

**業務上の目的・背景**：在庫管理システムにおいて、在庫不足アラート、発注完了通知、製造オーダーの状態変更など、様々なイベントに基づく通知をユーザーに提供することで、業務上重要な情報を見逃さないようにする。これにより、在庫管理業務の効率化とリアルタイムな対応を支援する。

**画面へのアクセス方法**：ヘッダーメニューの通知アイコンをクリック、またはURL `/notifications/*` に直接アクセスする。ホームダッシュボードからも遷移可能。

**主要な操作・処理内容**：
1. 未読通知の一覧表示と確認
2. 通知を既読にマークする操作
3. 既読通知を未読に戻す操作
4. 既読通知の削除
5. すべての未読通知を一括で既読にする操作
6. 通知の一括選択と一括削除

**画面遷移**：
- 遷移元：ホームダッシュボード、ヘッダーメニュー
- 遷移先：通知設定画面（設定への遷移）

**権限による表示制御**：認証済みユーザーのみアクセス可能。ユーザーは自分宛ての通知のみ表示・操作できる。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 45 | 通知表示 | 主機能 | 未読通知と既読履歴の一覧表示、既読/未読の切り替え |
| 44 | 通知設定管理 | 遷移先機能 | 通知設定への遷移 |

## 画面種別

一覧

## URL/ルーティング

`/notifications/*`

## 入出力項目

| 項目名 | 項目種別 | データ型 | 必須 | 説明 |
|--------|----------|----------|------|------|
| - | - | - | - | 本画面は入力項目なし（表示・操作のみ） |

## 表示項目

### 通知一覧テーブル

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| 経過時間（Age） | 文字列 | 通知作成からの経過時間（人間が読める形式） |
| カテゴリ（Category） | 文字列 | 通知のカテゴリ（例：在庫、発注、製造等） |
| 通知名（Notification） | 文字列 | 通知のタイトル・名前 |
| メッセージ（Message） | 文字列 | 通知の詳細メッセージ |

## イベント仕様

### 1-既読にマーク

未読通知の行アクション「Mark as read」ボタン押下時の処理。

**処理フロー**：
1. 対象通知のPKを取得
2. `PATCH /api/notifications/{pk}/` を `{ read: true }` で呼び出し
3. 成功後、未読通知テーブルを再読み込み

### 2-未読にマーク

既読通知の行アクション「Mark as unread」ボタン押下時の処理。

**処理フロー**：
1. 対象通知のPKを取得
2. `PATCH /api/notifications/{pk}/` を `{ read: false }` で呼び出し
3. 成功後、既読通知テーブルを再読み込み

### 3-通知削除

既読通知の行アクション「Delete」ボタン押下時の処理。

**処理フロー**：
1. 対象通知のPKを取得
2. `DELETE /api/notifications/{pk}/` を呼び出し
3. 成功後、既読通知テーブルを再読み込み

### 4-すべて既読にマーク

未読タブのテーブルアクション「Mark all as read」ボタン押下時の処理。

**処理フロー**：
1. `GET /api/notifications/readall/` を `{ read: false }` パラメータで呼び出し
2. 成功後、未読・既読両方のテーブルを再読み込み

### 5-一括削除

選択した通知の一括削除処理。

**処理フロー**：
1. 選択された通知のPKリストを取得
2. 各通知に対して `DELETE /api/notifications/{pk}/` を呼び出し
3. 成功後、テーブルを再読み込み

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 既読にマーク | common_notificationmessage | UPDATE | read フラグを true に更新 |
| 未読にマーク | common_notificationmessage | UPDATE | read フラグを false に更新 |
| 通知削除 | common_notificationmessage | DELETE | 通知レコードを削除 |
| すべて既読にマーク | common_notificationmessage | UPDATE | 対象ユーザーの未読通知をすべて既読に更新 |

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

#### common_notificationmessage

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | read | true/false | 既読/未読状態の切り替え |
| DELETE | - | pk = 指定値 | 通知レコードの削除 |

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|---------------|------|---------------|
| - | - | 本画面では明示的なメッセージ表示なし（操作完了は画面更新で確認） |

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| API通信エラー | エラー内容をコンソールに出力（エラーハンドリングは空のcatch句） |
| 認証エラー | ログイン画面へリダイレクト |
| 通知が見つからない | 404エラー（APIレベルで処理） |

## 備考

- タブ切り替えで「未読通知（Notifications）」と「履歴（History）」を切り替え可能
- テーブルは選択機能と一括削除機能を備えている
- 経過時間は作成日時からの相対時間で表示される
- ソート機能は「経過時間」列で利用可能

---

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

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

### 推奨読解順序

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

通知データの構造とAPIエンドポイントの定義を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ApiEndpoints.ts | `src/frontend/lib/enums/ApiEndpoints.ts` | 通知関連のAPIエンドポイント定義（notifications_list, notifications_readall）を確認 |

**読解のコツ**: ApiEndpointsは列挙型で定義されており、`notifications_list`と`notifications_readall`が通知機能のAPIパスを定義している。

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

画面のメインコンポーネントを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Notifications.tsx | `src/frontend/src/pages/Notifications.tsx` | メイン画面コンポーネント。useApi、useTableフックの利用方法を確認 |

**主要処理フロー**:
1. **22-26行**: コンポーネント定義とフック初期化（api, unreadTable, readTable）
2. **27-39行**: markAllAsRead関数の定義（一括既読処理）
3. **41-126行**: notificationPanels定義（未読・既読の2タブ構成）
4. **128-133行**: レンダリング部分（PageDetail + PanelGroup）

#### Step 3: テーブルコンポーネントを理解する

通知テーブルの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | NotificationTable.tsx | `src/frontend/src/tables/notifications/NotificationTable.tsx` | テーブル列定義とInvenTreeTableの利用方法を確認 |

**主要処理フロー**:
- **22-44行**: テーブル列定義（age_human, category, name, message）
- **46-59行**: InvenTreeTableコンポーネントの利用

#### Step 4: 共通コンポーネントを理解する

画面構成に使用される共通コンポーネントを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | PageDetail.tsx | `src/frontend/src/components/nav/PageDetail.tsx` | ページヘッダーコンポーネント |
| 4-2 | PanelGroup.tsx | `src/frontend/src/components/panels/PanelGroup.tsx` | タブパネルグループコンポーネント |

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

```
NotificationsPage (Notifications.tsx:22)
    │
    ├─ useApi() - APIコンテキストからAPIインスタンス取得
    │
    ├─ useTable('unreadnotifications') - 未読テーブル状態管理
    │
    ├─ useTable('readnotifications') - 既読テーブル状態管理
    │
    ├─ markAllAsRead() (27-39行)
    │      └─ api.get(ApiEndpoints.notifications_readall)
    │              └─ unreadTable.refreshTable()
    │              └─ readTable.refreshTable()
    │
    └─ PanelGroup
           └─ NotificationTable (unread)
           │      └─ InvenTreeTable
           │              └─ api.patch() - 既読マーク
           │
           └─ NotificationTable (history)
                  └─ InvenTreeTable
                          └─ api.patch() - 未読マーク
                          └─ api.delete() - 削除
```

### データフロー図

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

ユーザー操作 ───▶ NotificationsPage ───▶ 画面表示更新
                        │
                        ▼
                   API呼び出し
                   (PATCH/GET/DELETE)
                        │
                        ▼
                   Django Backend
                        │
                        ▼
                   PostgreSQL/SQLite
                   (common_notificationmessage)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Notifications.tsx | `src/frontend/src/pages/Notifications.tsx` | ソース | 通知一覧画面メインコンポーネント |
| NotificationTable.tsx | `src/frontend/src/tables/notifications/NotificationTable.tsx` | ソース | 通知テーブルコンポーネント |
| ApiEndpoints.ts | `src/frontend/lib/enums/ApiEndpoints.ts` | ソース | APIエンドポイント定義 |
| PageDetail.tsx | `src/frontend/src/components/nav/PageDetail.tsx` | ソース | ページヘッダーコンポーネント |
| PanelGroup.tsx | `src/frontend/src/components/panels/PanelGroup.tsx` | ソース | タブパネルグループコンポーネント |
| InvenTreeTable.tsx | `src/frontend/src/tables/InvenTreeTable.tsx` | ソース | 汎用テーブルコンポーネント |
| UseTable.ts | `src/frontend/src/hooks/UseTable.ts` | ソース | テーブル状態管理フック |
| ApiContext.tsx | `src/frontend/src/contexts/ApiContext.tsx` | ソース | API呼び出しコンテキスト |
