# 機能設計書 183-ボット表示

## 概要

本ドキュメントは、Chatwootにおける「ボット表示」機能の設計仕様を定義する。本機能は、特定のインボックスに割り当てられているエージェントボットの情報を取得し、表示するためのAPI機能である。

### 本機能の処理概要

本機能は、指定されたインボックスに現在割り当てられているボットの情報を取得し、クライアントに返却する。インボックス設定画面でのボット情報表示や、ボット割り当て状況の確認に使用される。

**業務上の目的・背景**：インボックスの管理において、現在どのボットが割り当てられているかを把握することは重要である。管理者がインボックスの自動応答設定を確認・変更する際に、現在のボット割り当て状況を表示する必要がある。

**機能の利用シーン**：インボックス設定画面を開いた際に、現在割り当てられているボットの情報を表示する。ボットの割り当て変更前に現在の設定を確認する。

**主要な処理内容**：
1. インボックスIDによるインボックスの取得
2. インボックスに関連付けられたボットの取得
3. ボット情報のJSON形式での返却

**関連システム・外部連携**：インボックス管理機能、ボット割り当て機能（No.182）との連携

**権限による制御**：インボックスの参照権限を持つユーザーが閲覧可能

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 50 | インボックス設定画面 | 主画面 | 割り当てボットの情報表示 |
| 74 | エージェントボット一覧画面 | 参照画面 | ボット情報の参照 |

## 機能種別

参照処理 / データ取得

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| account_id | Integer | Yes | アカウントID | URLパスパラメータ |
| id | Integer | Yes | インボックスID | URLパスパラメータ |

### 入力データソース

- APIリクエスト: GET /api/v1/accounts/{account_id}/inboxes/{id}/agent_bot

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| id | Integer | ボットID |
| name | String | ボット名 |
| description | String | ボットの説明 |
| outgoing_url | String | Webhook送信先URL |
| bot_type | String | ボットタイプ（webhook） |
| bot_config | Object | ボット設定（JSON） |
| avatar_url | String | ボットのアバターURL |
| access_token | String | アクセストークン（認可されたユーザーのみ） |

### 出力先

- HTTPレスポンス（JSON形式）

## 処理フロー

### 処理シーケンス

```
1. リクエスト受信
   └─ GET /api/v1/accounts/:account_id/inboxes/:id/agent_bot

2. インボックス取得
   └─ fetch_inbox before_actionによりインボックスを取得

3. 認可チェック
   └─ インボックスの参照権限を確認

4. ボット取得
   └─ @inbox.agent_bot を取得

5. レスポンス返却
   └─ ボット情報をJSON形式で返却（nilの場合は空レスポンス）
```

### フローチャート

```mermaid
flowchart TD
    A[リクエスト受信] --> B[fetch_inbox]
    B --> C[認可チェック]
    C --> D[agent_bot取得]
    D --> E{ボットが存在するか}
    E -->|Yes| F[ボット情報をJSON化]
    E -->|No| G[空レスポンス/nil]
    F --> H[レスポンス返却]
    G --> H
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-183-01 | アクティブボット取得 | agent_bot_inboxのステータスに関わらずボット情報を返却 | 常時 |
| BR-183-02 | 単一ボット | 1インボックスに対して最大1つのボット情報を返却 | 常時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| インボックス取得 | inboxes | SELECT | 対象インボックスの取得 |
| ボット関連取得 | agent_bot_inboxes | SELECT | インボックスに関連するボット関連の取得 |
| ボット取得 | agent_bots | SELECT | ボット情報の取得 |

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

#### inboxes

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | * | id = params[:id], account_id = Current.account.id | |

#### agent_bot_inboxes

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | agent_bot_id | inbox_id で検索 | has_one :agent_bot_inbox |

#### agent_bots

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | * | agent_bot_inboxes経由で取得 | through: :agent_bot_inbox |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 404 | Not Found | 指定されたインボックスが存在しない | エラーレスポンス返却 |
| 403 | Forbidden | インボックス参照権限がない | エラーレスポンス返却 |

### リトライ仕様

同期処理のため、リトライ仕様は適用されない。

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

参照のみのため、トランザクション制御は不要。

## パフォーマンス要件

- 単純な参照処理のため、特別なパフォーマンス要件なし
- 応答時間: 通常50ms以内

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

- インボックス参照権限の確認（authorize @inbox, :show?）
- アカウント境界の厳守（Current.accountによるスコープ制限）
- アクセストークンの表示は認可されたユーザーのみ

## 備考

- ボットが割り当てられていない場合、@agent_botはnilとなる
- Jbuilderテンプレートでレスポンスをフォーマット

---

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

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

### 推奨読解順序

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

まず、インボックスとボットの関連を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | inbox.rb | `app/models/inbox.rb` | agent_botリレーションの定義 |
| 1-2 | agent_bot_inbox.rb | `app/models/agent_bot_inbox.rb` | 中間テーブルの構造 |

**読解のコツ**:
- Inboxモデルにはhas_one :agent_bot_inbox、has_one :agent_bot, through: :agent_bot_inboxが定義されている
- これによりinbox.agent_botで直接ボットを取得可能

#### Step 2: コントローラーアクションを理解する

ボット情報取得APIの実装を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | inboxes_controller.rb | `app/controllers/api/v1/accounts/inboxes_controller.rb` | agent_botアクションの実装 |

**主要処理フロー**:
- **53-55行目**: agent_botアクション - @inbox.agent_botを取得してインスタンス変数に設定
- **3行目**: before_action :fetch_inbox - インボックス取得のコールバック
- **92-95行目**: fetch_inboxメソッド - インボックス取得と認可チェック

#### Step 3: ビューテンプレートを理解する

レスポンスのフォーマットを理解する。

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

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

```
GET /api/v1/accounts/:account_id/inboxes/:id/agent_bot
    │
    ├─ before_action :fetch_inbox
    │      └─ Current.account.inboxes.find(params[:id])
    │      └─ authorize @inbox, :show?
    │
    └─ agent_bot アクション
           └─ @agent_bot = @inbox.agent_bot
                  │
                  ├─ inbox.agent_bot_inbox (AgentBotInbox)
                  │
                  └─ agent_bot_inbox.agent_bot (AgentBot)
```

### データフロー図

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

APIリクエスト ─────────▶ InboxesController ──────────────▶ JSON Response
(inbox_id)                    │
                              ▼
                     fetch_inbox
                     (Inbox取得)
                              │
                              ▼
                     agent_bot アクション
                     (@inbox.agent_bot)
                              │
                              ▼
                     Jbuilder テンプレート
                              │
                              ▼
                     {
                       id: ...,
                       name: ...,
                       outgoing_url: ...,
                       ...
                     }
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| inboxes_controller.rb | `app/controllers/api/v1/accounts/inboxes_controller.rb` | コントローラー | agent_botアクション |
| inbox.rb | `app/models/inbox.rb` | モデル | agent_botリレーション定義 |
| agent_bot_inbox.rb | `app/models/agent_bot_inbox.rb` | モデル | 中間テーブル |
| agent_bot.rb | `app/models/agent_bot.rb` | モデル | ボットモデル |
| agent_bot.json.jbuilder | `app/views/api/v1/accounts/inboxes/agent_bot.json.jbuilder` | ビュー | レスポンステンプレート |
