# 機能設計書 101-通知設定

## 概要

本ドキュメントは、Chatwootにおけるユーザー毎の通知プリファレンス設定機能について記述する。この機能により、ユーザーは各種通知の受信方法（メール、プッシュ通知）を細かくカスタマイズできる。

### 本機能の処理概要

**業務上の目的・背景**：カスタマーサポート業務において、エージェントは日々大量の通知を受け取る可能性がある。すべての通知を同じ方法で受け取ると、重要な通知が埋もれたり、不要な通知で業務効率が低下したりする。本機能により、ユーザーは自分の業務スタイルに合わせて通知の受信方法を選択でき、重要な通知を確実に受け取りながら、不要な通知を抑制することが可能となる。

**機能の利用シーン**：プロフィール設定画面において、ユーザーが「会話作成」「会話割り当て」「新規メッセージ」「メンション」「SLA違反」などの各イベントタイプごとに、メール通知とプッシュ通知のオン/オフを設定する際に利用される。

**主要な処理内容**：
1. 現在の通知設定の取得（show アクション）
2. 通知設定の更新（update アクション）
3. メール通知フラグとプッシュ通知フラグの個別管理
4. ビットフラグによる効率的な複数フラグ管理

**関連システム・外部連携**：本機能は通知配信システム（PushNotificationService、EmailNotificationService）と連携し、ここで設定されたフラグに基づいて通知の配信可否が判定される。

**権限による制御**：ログインユーザーは自分自身の通知設定のみ参照・更新可能。管理者であっても他ユーザーの通知設定を変更することはできない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 89 | プロフィール設定画面 | 主画面 | 通知プリファレンスの設定 |

## 機能種別

CRUD操作（参照・更新）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| selected_email_flags | Array | No | 有効化するメール通知タイプのリスト | 許可された通知タイプのみ |
| selected_push_flags | Array | No | 有効化するプッシュ通知タイプのリスト | 許可された通知タイプのみ |

### 入力データソース

- 画面入力: プロフィール設定画面の通知設定セクション
- DBテーブル: notification_settings テーブルから現在の設定値を取得

### 通知タイプ一覧

| タイプ名 | 説明 |
|---------|------|
| conversation_creation | 会話作成時の通知 |
| conversation_assignment | 会話割り当て時の通知 |
| assigned_conversation_new_message | 担当会話の新規メッセージ通知 |
| conversation_mention | メンション通知 |
| participating_conversation_new_message | 参加中会話の新規メッセージ通知 |
| sla_missed_first_response | SLA初回応答違反通知 |
| sla_missed_next_response | SLA次回応答違反通知 |
| sla_missed_resolution | SLA解決違反通知 |

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | Integer | 通知設定ID |
| user_id | Integer | ユーザーID |
| account_id | Integer | アカウントID |
| all_email_flags | Array | 利用可能なすべてのメール通知フラグ |
| selected_email_flags | Array | 有効化されているメール通知フラグ |
| all_push_flags | Array | 利用可能なすべてのプッシュ通知フラグ |
| selected_push_flags | Array | 有効化されているプッシュ通知フラグ |

### 出力先

- 画面表示: JSON形式でAPIレスポンスとして返却

## 処理フロー

### 処理シーケンス

```
1. リクエスト受信
   └─ APIエンドポイント: /api/v1/accounts/:account_id/notification_settings

2. 認証・認可チェック
   └─ ログインユーザーの検証

3. 通知設定レコードの取得
   └─ current_userとaccount_idで該当レコードを検索

4. 設定の表示（show）または更新（update）
   ├─ show: 現在の設定をJSON形式で返却
   └─ update: フラグを更新して保存後、設定を返却
```

### フローチャート

```mermaid
flowchart TD
    A[リクエスト受信] --> B{アクション種別}
    B -->|show| C[通知設定取得]
    B -->|update| D[パラメータ取得]
    C --> E[JSON形式でレスポンス]
    D --> F[email_flagsを更新]
    F --> G[push_flagsを更新]
    G --> H[DBに保存]
    H --> E
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-101-01 | アカウント別設定 | 通知設定はアカウント単位で管理される | 常時 |
| BR-101-02 | デフォルト値 | 新規ユーザーはemail_flags=0、push_flags=0で初期化 | ユーザー作成時 |
| BR-101-03 | 自己設定のみ | ユーザーは自分自身の通知設定のみ変更可能 | 常時 |

### 計算ロジック

FlagShihTzu gemを使用したビットフラグ管理:
- 各通知タイプに1つのビットが割り当てられる
- email_flags、push_flagsカラムは整数型で複数フラグを格納
- `selected_email_flags=`でフラグの一括設定が可能

## データベース操作仕様

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| show | notification_settings | SELECT | 現在の通知設定を取得 |
| update | notification_settings | UPDATE | 通知フラグを更新 |

### テーブル別操作詳細

#### notification_settings

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | * | account_id = Current.account.id AND user_id = current_user.id | 一意インデックスあり |
| UPDATE | email_flags | ビットフラグの整数値 | FlagShihTzu経由で更新 |
| UPDATE | push_flags | ビットフラグの整数値 | FlagShihTzu経由で更新 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 401 | Unauthorized | 未認証状態でアクセス | ログインページへリダイレクト |
| 404 | NotFound | 通知設定レコードが存在しない | 該当なし（通常は自動作成される） |
| 422 | UnprocessableEntity | バリデーションエラー | エラーメッセージを返却 |

### リトライ仕様

特になし。同期処理のため即時エラー返却。

## トランザクション仕様

update処理はRailsのデフォルトトランザクション内で実行。save!メソッドによりエラー時は自動ロールバック。

## パフォーマンス要件

- レスポンス時間: 100ms以内
- 複合インデックス (account_id, user_id) による高速検索

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

- 認証必須: Devise TokenAuthによる認証
- 認可: 自分自身の通知設定のみアクセス可能
- Strong Parameters: 許可されたパラメータのみ受け付け

## 備考

- FlagShihTzu gemにより、単一カラムで複数のブール値フラグを管理
- 通知設定はユーザーのアカウント参加時に自動作成される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | notification_setting.rb | `app/models/notification_setting.rb` | 通知設定モデルの構造とビットフラグの定義 |
| 1-2 | notification.rb | `app/models/notification.rb` | NOTIFICATION_TYPES定数で通知タイプを確認 |

**読解のコツ**: FlagShihTzu gemの`has_flags`メソッドにより、整数カラムを複数のブールフラグとして扱っている。`EMAIL_NOTIFICATION_FLAGS`と`PUSH_NOTIFICATION_FLAGS`でフラグ名とビット位置のマッピングを定義。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | notification_settings_controller.rb | `app/controllers/api/v1/accounts/notification_settings_controller.rb` | APIエンドポイントの処理フロー |

**主要処理フロー**:
1. **2-3行目**: `before_action :set_user, :load_notification_setting` - 事前処理でユーザーと設定を取得
2. **4行目**: `def show; end` - 空のshowアクション（ビューでレスポンス生成）
3. **6-9行目**: `def update` - フラグ更新処理
4. **26-28行目**: `update_flags` - selected_email_flags、selected_push_flagsの一括設定

#### Step 3: ビュー層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | show.json.jbuilder | `app/views/api/v1/accounts/notification_settings/show.json.jbuilder` | JSONレスポンスの構造 |

**主要処理フロー**:
- **1-7行目**: すべてのフラグ一覧と選択済みフラグをJSON形式で出力

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

```
NotificationSettingsController
    │
    ├─ before_action
    │      ├─ set_user (current_userを@userに設定)
    │      └─ load_notification_setting (notification_settingsテーブルから取得)
    │
    ├─ show
    │      └─ show.json.jbuilder (JSONレスポンス生成)
    │
    └─ update
           ├─ update_flags
           │      ├─ selected_email_flags= (FlagShihTzuメソッド)
           │      └─ selected_push_flags= (FlagShihTzuメソッド)
           ├─ save!
           └─ show.json.jbuilder
```

### データフロー図

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

APIリクエスト ───────▶ NotificationSettingsController ───▶ JSON Response
(selected_flags)           │
                           │
                           ▼
                    notification_settings
                    テーブル (UPDATE/SELECT)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| notification_setting.rb | `app/models/notification_setting.rb` | モデル | 通知設定のデータモデル定義 |
| notification_settings_controller.rb | `app/controllers/api/v1/accounts/notification_settings_controller.rb` | コントローラー | API エンドポイント |
| show.json.jbuilder | `app/views/api/v1/accounts/notification_settings/show.json.jbuilder` | ビュー | JSONレスポンステンプレート |
| notification.rb | `app/models/notification.rb` | モデル | 通知タイプの定数定義 |
| base_controller.rb | `app/controllers/api/v1/accounts/base_controller.rb` | コントローラー | 基底クラス（認証処理） |
