# 機能設計書 19-ウェルカムメッセージ

## 概要

本ドキュメントは、Chatwootのウェルカムメッセージ（グリーティングメッセージ）機能について、その処理内容、データベース操作、およびコード構成を詳細に記述した設計書である。

### 本機能の処理概要

ウェルカムメッセージ機能は、インボックスごとに設定可能なグリーティングメッセージを管理し、新しい会話開始時に自動的にウェルカムメッセージを表示する機能である。これにより、顧客がサポートに連絡した際に即座にフレンドリーな応答を提供できる。

**業務上の目的・背景**：カスタマーサポートにおいて、顧客からの問い合わせに対する初動対応の速さは顧客満足度に大きく影響する。エージェントが即座に対応できない場合でも、ウェルカムメッセージにより「問い合わせを受け付けた」という安心感を顧客に提供できる。また、よくある質問への誘導や営業時間の案内など、初期情報の提供にも活用できる。

**機能の利用シーン**：
- Webウィジェットでの新規チャット開始時の自動応答
- SNSチャネルでの初回メッセージ受信時の応答
- 営業時間内/外で異なるメッセージの出し分け（営業時間機能との連携）

**主要な処理内容**：
1. インボックス設定でのグリーティング有効化（greeting_enabled）
2. グリーティングメッセージの設定・保存（greeting_message）
3. 新規会話作成時のグリーティングメッセージ自動送信
4. メッセージ長の制限バリデーション

**関連システム・外部連携**：
- 各種チャネル（WebWidget, SNS等）へのメッセージ配信

**権限による制御**：
- グリーティング設定の変更はAdministratorロールのみ

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 50 | インボックス設定画面 | 主画面 | グリーティングメッセージ設定 |

## 機能種別

設定管理 / 自動応答

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| greeting_enabled | Boolean | No | グリーティング有効フラグ（デフォルト: false） | - |
| greeting_message | String | No | グリーティングメッセージ本文 | max: GREETING_MESSAGE_MAX_LENGTH |

### 入力データソース

- 画面入力（インボックス設定画面からの操作）
- API経由（REST API）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| greeting_enabled | Boolean | グリーティング有効フラグ |
| greeting_message | String | グリーティングメッセージ本文 |

### 出力先

- インボックス設定レスポンス（JSON形式）
- 会話開始時のメッセージとしてチャネルに配信

## 処理フロー

### 処理シーケンス

```
1. グリーティング設定更新
   └─ InboxesController.update 経由でインボックス設定を更新

2. 設定の保存
   ├─ greeting_enabled: true/false
   └─ greeting_message: メッセージ本文

3. 新規会話作成時
   └─ 会話作成処理の中でグリーティング確認

4. グリーティングメッセージ送信判定
   ├─ greeting_enabled == true の場合
   └─ greeting_message が存在する場合

5. メッセージ作成・送信
   └─ ボットメッセージとしてグリーティングを挿入
```

### フローチャート

```mermaid
flowchart TD
    A[新規会話作成] --> B{greeting_enabled?}
    B -->|No| C[通常処理]
    B -->|Yes| D{greeting_message存在?}
    D -->|No| C
    D -->|Yes| E[グリーティングメッセージ作成]
    E --> F[会話にメッセージ追加]
    F --> C
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルト無効 | greeting_enabledのデフォルト値はfalse | インボックス作成時 |
| BR-002 | メッセージ長制限 | greeting_messageはGREETING_MESSAGE_MAX_LENGTHまで | 設定保存時 |
| BR-003 | 有効化条件 | greeting_enabledがtrueかつgreeting_messageが存在する場合のみ送信 | 会話作成時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| グリーティング設定更新 | inboxes | UPDATE | greeting_enabled, greeting_message更新 |
| グリーティング取得 | inboxes | SELECT | インボックス設定取得 |

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

#### inboxes

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | greeting_enabled | true/false | デフォルトfalse |
| UPDATE | greeting_message | メッセージ本文 | 文字数制限あり |
| SELECT | greeting_enabled, greeting_message | id条件 | - |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 422 | UnprocessableEntity | greeting_messageが文字数制限超過 | エラー内容を表示 |
| 403 | Forbidden | 操作権限がない | 権限確認メッセージ表示 |

### リトライ仕様

特になし（同期処理のため）

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

インボックス設定更新はActiveRecordの暗黙的トランザクション内で実行される。

## パフォーマンス要件

- 設定更新: 100ms以内のレスポンス

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

- InboxPolicyによる認可制御
- XSS対策のためのメッセージサニタイズ

## 備考

- グリーティングメッセージはinboxesテーブルのgreeting_messageカラムに保存
- 営業時間外メッセージ（out_of_office_message）とは別機能

---

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

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

### 推奨読解順序

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

Inboxモデルのグリーティング関連カラムを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | inbox.rb | `app/models/inbox.rb` | greeting_enabled, greeting_messageカラム |

**読解のコツ**:
- スキーマコメントの17-18行目でgreeting_enabled, greeting_messageを確認
- バリデーション（54行目）でgreeting_messageの長さ制限を確認

**主要処理フロー**:
1. **17行目**: `greeting_enabled :boolean default(FALSE)`
2. **18行目**: `greeting_message :string`
3. **54行目**: `validates :greeting_message, length: { maximum: Limits::GREETING_MESSAGE_MAX_LENGTH }`

#### Step 2: コントローラでの設定更新を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | inboxes_controller.rb | `app/controllers/api/v1/accounts/inboxes_controller.rb` | update処理、permitted_params |

**主要処理フロー**:
1. **45-51行目**: update - インボックス設定更新
2. **173-179行目**: inbox_attributes - 許可パラメータ（greeting_enabled, greeting_message含む）

#### Step 3: 許可パラメータの定義を確認

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | inboxes_controller.rb | `app/controllers/api/v1/accounts/inboxes_controller.rb` | inbox_attributes メソッド |

**主要処理フロー**:
- **174行目**: `:greeting_enabled, :greeting_message` が許可パラメータに含まれる

#### Step 4: 文字数制限の定義を確認

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | limits.rb | `app/models/limits.rb` または設定ファイル | GREETING_MESSAGE_MAX_LENGTH定数 |

**主要処理フロー**:
- グリーティングメッセージの最大文字数定義

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

```
Api::V1::Accounts::InboxesController
    │
    ├─ update
    │      │
    │      ├─ permitted_params
    │      │      └─ inbox_attributes
    │      │             └─ :greeting_enabled, :greeting_message
    │      │
    │      └─ @inbox.update!(inbox_params)
    │             │
    │             └─ validates :greeting_message, length: { maximum: ... }
    │
    └─ Inbox (モデル)
           └─ greeting_enabled, greeting_message カラム
```

### データフロー図

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

APIリクエスト ────────▶ InboxesController.update ────────▶ JSONレスポンス
(greeting_enabled,            │
 greeting_message)            ▼
                         バリデーション
                    (greeting_message長チェック)
                              │
                              ▼
                         inboxes テーブル
                         (UPDATE)


[グリーティング送信時]

新規会話作成 ────────▶ グリーティング判定 ────────▶ メッセージ作成
                              │
                              ├─ greeting_enabled == true?
                              └─ greeting_message存在?
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| inbox.rb | `app/models/inbox.rb` | モデル | グリーティング設定カラム定義 |
| inboxes_controller.rb | `app/controllers/api/v1/accounts/inboxes_controller.rb` | コントローラ | グリーティング設定更新API |
| inbox_policy.rb | `app/policies/inbox_policy.rb` | ポリシー | 設定更新の認可 |
| limits.rb | `app/models/limits.rb` | 定数 | GREETING_MESSAGE_MAX_LENGTH定義 |
