# 画面設計書 65-連携アプリ一覧画面

## 概要

本ドキュメントは、Chatwootの連携アプリ一覧画面の設計仕様を記述したものです。

### 本画面の処理概要

本画面は、Chatwootと連携可能な外部サービス（インテグレーション）の一覧を表示する画面です。各連携アプリの有効/無効状態を確認し、設定画面への導線を提供します。

**業務上の目的・背景**：Chatwootは多様な外部サービスとの連携をサポートしています。Slack、Linear、Notion、Dialogflow、Google Translate など、様々なツールとの連携により、カスタマーサポート業務の効率化と機能拡張が可能になります。本画面は、これらの連携アプリを一覧表示し、設定・管理のハブとして機能します。

**画面へのアクセス方法**：ダッシュボードの左サイドバーから「設定」を選択し、「連携」メニューをクリックしてアクセスします。URLパスは `/app/accounts/:accountId/settings/integrations` です。

**主要な操作・処理内容**：
1. 連携アプリの一覧表示（アイコン、名前、説明、有効状態）
2. 各連携アプリの設定画面への遷移

**画面遷移**：
- 遷移元：設定ホーム画面、サイドバーメニュー
- 遷移先：各連携アプリの設定画面、Webhook設定画面、ダッシュボードアプリ設定画面

**権限による表示制御**：管理者（administrator）権限を持つユーザーのみがアクセス可能です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 143 | Hooks（Integrations） | 主機能 | 連携アプリの一覧表示 |

## 画面種別

一覧

## URL/ルーティング

| 項目 | 値 |
|------|-----|
| パス | `/app/accounts/:accountId/settings/integrations` |
| ルート名 | `settings_applications` |
| コンポーネント | `app/javascript/dashboard/routes/dashboard/settings/integrations/Index.vue` |
| 権限 | `administrator` |
| フィーチャーフラグ | `INTEGRATIONS` |

## 入出力項目

本画面での入力はなし

## 表示項目

### 連携アプリカード

| 項目名 | 項目ID | 型 | 説明 |
|--------|--------|-----|------|
| アイコン | logo | string | 連携アプリのロゴ画像 |
| アプリ名 | name | string | 連携アプリの名称 |
| 説明 | description | string | 連携アプリの説明文 |
| 有効状態 | enabled | boolean | 連携が有効かどうか |

### アクションボタン

| ボタン名 | 説明 |
|---------|------|
| Configure | 連携アプリの設定画面へ遷移 |

## イベント仕様

### 1-連携アプリ設定ボタン押下

各カードの「Configure」ボタンをクリックすると、連携アプリの設定画面に遷移します。

**処理フロー**：
1. `router-link` により `settings_applications_integration` ルートに遷移
2. URLパラメータに `integration_id` が含まれる
3. 対応する連携設定コンポーネントが表示される

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 連携一覧取得 | - | API | 外部APIから連携情報を取得 |

本画面ではデータベースの直接更新は行いません。連携情報はIntegrationsAPIを通じて取得されます。

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示タイミング |
|-------------|------|---------------|---------------|
| INTEGRATION_SETTINGS.LOADING | 情報 | 読み込み中 | データ取得中 |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| データ取得失敗 | エラーを無視し、空のリストを表示 |
| 権限不足 | 画面にアクセス不可（ルーティングで制御） |

## 備考

- 連携アプリの一覧はサーバー側で定義されており、`integrations/apps` APIから取得
- 有効/無効状態は各連携アプリごとに管理される
- アプリのロゴ画像は `/dashboard/images/integrations/{id}.png` と `/dashboard/images/integrations/{id}-dark.png` から取得
- `useBranding` composableを使用して、説明文内のインストール名を動的に置換

---

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

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

### 推奨読解順序

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

連携アプリのデータ構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | integrations.js | `app/javascript/dashboard/store/modules/integrations.js` | state構造、getAppIntegrations ゲッターを確認 |

**読解のコツ**: `records` 配列に連携アプリの情報が格納されます。各アプリは `id`, `name`, `description`, `enabled`, `hooks` などのプロパティを持ちます。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Index.vue | `app/javascript/dashboard/routes/dashboard/settings/integrations/Index.vue` | 画面の構成、データ取得処理を確認 |

**主要処理フロー**:
1. **19-21行目**: `onMounted` で `store.dispatch('integrations/get')` を呼び出し
2. **15-17行目**: `computed` でストアから連携リストを取得
3. **42-50行目**: `IntegrationItem` コンポーネントで各カードを表示

#### Step 3: カードコンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | IntegrationItem.vue | `app/javascript/dashboard/routes/dashboard/settings/integrations/IntegrationItem.vue` | カードの表示項目、遷移先URLの生成を確認 |

**主要処理フロー**:
- **35-39行目**: 有効状態に応じたステータス表示
- **45-47行目**: 遷移先URLの生成

#### Step 4: Vuex Store層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | integrations.js | `app/javascript/dashboard/store/modules/integrations.js` | get アクションを確認 |

**主要処理フロー**:
- **40-48行目**: `get` アクションでAPI呼び出し

#### Step 5: API層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | integrations.js | `app/javascript/dashboard/api/integrations.js` | APIクライアントの構造を確認 |

**主要処理フロー**:
- **7-8行目**: `integrations/apps` エンドポイントを使用

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

```
Index.vue (エントリーポイント)
    │
    ├─ onMounted()
    │      └─ store.dispatch('integrations/get')
    │             └─ IntegrationsAPI.get()
    │                    └─ GET /api/v1/accounts/:account_id/integrations/apps
    │
    └─ IntegrationItem.vue
           │
           └─ router-link (設定)
                  └─ settings_applications_integration ルートへ遷移
```

### データフロー図

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

なし ────────────────▶ Index.vue ─────────────────▶ カード一覧表示
                           │
                           ▼
                      Vuex Store
                    (integrations)
                           │
                           ▼
                   IntegrationsAPI
                           │
                           ▼
                  Rails Controller
                (integrations_controller)
                           │
                           ▼
              外部サービス連携情報
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Index.vue | `app/javascript/dashboard/routes/dashboard/settings/integrations/Index.vue` | ソース | メイン画面コンポーネント |
| IntegrationItem.vue | `app/javascript/dashboard/routes/dashboard/settings/integrations/IntegrationItem.vue` | ソース | カードコンポーネント |
| integrations.js | `app/javascript/dashboard/store/modules/integrations.js` | ソース | Vuexストアモジュール |
| integrations.js | `app/javascript/dashboard/api/integrations.js` | ソース | APIクライアント |
| integrations.routes.js | `app/javascript/dashboard/routes/dashboard/settings/integrations/integrations.routes.js` | ソース | ルート定義 |
| SettingsLayout.vue | `app/javascript/dashboard/routes/dashboard/settings/SettingsLayout.vue` | ソース | 設定画面レイアウト |
| BaseSettingsHeader.vue | `app/javascript/dashboard/routes/dashboard/settings/components/BaseSettingsHeader.vue` | ソース | 設定画面ヘッダー |
