# 画面設計書 70-Notion連携画面

## 概要

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

### 本画面の処理概要

本画面は、Notion（ナレッジベース・ドキュメント管理ツール）とChatwootを連携するための設定画面です。Notion連携により、ChatwootからNotionのドキュメントやデータベースにアクセスし、顧客対応に活用できます。

**業務上の目的・背景**：多くの企業がNotionを社内ナレッジベースとして活用しています。Chatwootとの連携により、エージェントは顧客対応中にNotionの情報を参照したり、対応内容をNotionに記録したりすることが可能になります。特にFAQやマニュアルの参照において有用です。

**画面へのアクセス方法**：連携アプリ一覧画面から「Notion」を選択、または直接 `/app/accounts/:accountId/settings/integrations/notion` にアクセスします。

**主要な操作・処理内容**：
1. Notion連携の接続（OAuth認証）
2. Notion連携の切断

**画面遷移**：
- 遷移元：連携アプリ一覧画面
- 遷移先：Notion OAuth認証画面（外部）、連携アプリ一覧画面（切断後）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 148 | Notion統合 | 主機能 | Notion連携の設定 |
| 139 | Notion認可 | 遷移先機能 | Notion認可フロー |

## 画面種別

設定

## URL/ルーティング

| 項目 | 値 |
|------|-----|
| パス | `/app/accounts/:accountId/settings/integrations/notion` |
| ルート名 | `settings_integrations_notion` |
| コンポーネント | `app/javascript/dashboard/routes/dashboard/settings/integrations/Notion.vue` |
| 権限 | `administrator` |

## 入出力項目

### クエリパラメータ

| パラメータ名 | 型 | 説明 |
|-------------|-----|------|
| code | string | Notion OAuth認証後のコード（将来的な使用のため） |

## 表示項目

### 連携情報カード

| 項目名 | 項目ID | 型 | 説明 |
|--------|--------|-----|------|
| ロゴ | integrationLogo | string | Notionのロゴ画像 |
| 名前 | integrationName | string | 「Notion」 |
| 説明 | integrationDescription | string | Notion連携の説明文 |
| 有効状態 | integrationEnabled | boolean | 連携が有効かどうか |

### アクションボタン

| ボタン名 | 表示条件 | 説明 |
|---------|---------|------|
| Connect | 未接続時 | Notion OAuth認証を開始 |
| Disconnect | 接続時 | Notion連携を切断 |

## イベント仕様

### 1-Notion接続ボタン押下

「Connect」ボタンをクリックすると、Notionの認証画面にリダイレクトされます。

**処理フロー**：
1. `authorize()` が呼び出される
2. `notionClient.generateAuthorization()` でNotionの認可URLを取得
3. `window.location.href = url` でNotion認証画面にリダイレクト
4. Notion側で認証完了後、コールバックURLに戻る

### 2-Notion切断ボタン押下

「Disconnect」ボタンをクリックすると、確認ダイアログが表示されます。

**処理フロー**：
1. `Integration.vue` の `openDeletePopup()` が呼び出される
2. 確認ダイアログが表示される
3. 確認後、`confirmDeletion()` が呼び出される
4. `store.dispatch('integrations/deleteIntegration', 'notion')` でAPIを呼び出し
5. 成功時：成功メッセージを表示し、連携アプリ一覧画面に遷移

### 3-画面初期化

画面表示時に、Notion連携情報を取得します。

**処理フロー**：
1. `onMounted` で `initializeNotionIntegration()` が呼び出される
2. `store.dispatch('integrations/get', 'notion')` で連携情報を取得
3. `integrationLoaded` が `true` に設定される

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 連携情報取得 | integrations_hooks | SELECT | Notion連携情報を取得 |
| Notion接続 | integrations_hooks | INSERT/UPDATE | Notion連携を登録/更新 |
| Notion切断 | integrations_hooks | DELETE | Notion連携を削除 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示タイミング |
|-------------|------|---------------|---------------|
| INTEGRATION_SETTINGS.DELETE.API.SUCCESS_MESSAGE | 成功 | 連携削除成功 | 切断成功時 |
| INTEGRATION_SETTINGS.WEBHOOK.DELETE.API.ERROR_MESSAGE | エラー | 連携削除失敗 | 切断失敗時 |
| INTEGRATION_SETTINGS.NOTION.DELETE.TITLE | 確認 | 切断確認タイトル | 切断ボタン押下時 |
| INTEGRATION_SETTINGS.NOTION.DELETE.MESSAGE | 確認 | 切断確認メッセージ | 切断ボタン押下時 |
| INTEGRATION_SETTINGS.CONNECT.BUTTON_TEXT | ボタン | 接続ボタンテキスト | 未接続時 |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| OAuth認可URL取得失敗 | エラーメッセージを表示 |
| 連携削除失敗 | エラーメッセージを表示 |
| 連携情報取得失敗 | ローディング状態を解除 |

## 備考

- Notion連携はOAuth認証フローを使用
- `notionClient.generateAuthorization()` でNotionの認可URLを生成
- フィーチャーフラグが不要（常に利用可能）
- `integrationAction` が空文字列の場合、カスタムのConnectボタンを表示（`slot#action` を使用）
- `isCreatingNotion` フラグで接続処理中のローディング表示を制御
- `ButtonNext` コンポーネントを使用してカスタムのConnectボタンを表示

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Notion.vue | `app/javascript/dashboard/routes/dashboard/settings/integrations/Notion.vue` | 画面の構成、OAuth認証処理を確認 |

**主要処理フロー**:
1. **41-44行目**: `initializeNotionIntegration()` で初期化処理
2. **32-39行目**: `authorize()` でNotionの認可URLを取得しリダイレクト
3. **24-30行目**: `integrationAction` で接続/切断状態を判定

**読解のコツ**: `integrationAction` が空文字列を返す場合、`slot#action` を使用してカスタムのConnectボタンを表示します。これは `Integration.vue` のデフォルトの接続ボタンではなく、`authorize()` を呼び出すカスタムボタンです。

#### Step 2: Notion API クライアントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | notion_auth.js | `app/javascript/dashboard/api/notion_auth.js` | Notion認可URL生成APIを確認 |

**主要処理フロー**:
- `generateAuthorization()` でバックエンドAPIを呼び出し、NotionのOAuth認可URLを取得

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Integration.vue | `app/javascript/dashboard/routes/dashboard/settings/integrations/Integration.vue` | 連携カードの共通コンポーネント、slot#actionの使用を確認 |

**主要処理フロー**:
- **119-127行目**: `slot name="action"` でカスタムボタンを受け入れ

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

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

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

```
Notion.vue (エントリーポイント)
    │
    ├─ onMounted()
    │      └─ initializeNotionIntegration()
    │             └─ store.dispatch('integrations/get', 'notion')
    │                    └─ IntegrationsAPI.get()
    │                           └─ GET /api/v1/accounts/:id/integrations/apps
    │
    └─ Integration.vue
           │
           ├─ [接続時] slot#action
           │      └─ authorize()
           │             └─ notionClient.generateAuthorization()
           │                    └─ GET /api/v1/accounts/:id/notion/authorize
           │                           └─ window.location.href = url
           │                                  └─ Notion OAuth画面
           │
           └─ [切断時] confirmDeletion()
                  └─ store.dispatch('integrations/deleteIntegration')
                         └─ IntegrationsAPI.delete()
                                └─ DELETE /api/v1/accounts/:id/integrations/notion
```

### データフロー図

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

Connect押下 ─────────▶ authorize() ──────────────▶ Notion OAuth
                           │
                           ▼
                notionClient.generateAuthorization()
                           │
                           ▼
                  Rails Controller
               (notion/authorize)
                           │
                           ▼
                    OAuth URL 生成
                           │
                           ▼
               window.location.href = url
                           │
                           ▼
              Notion OAuth 画面へリダイレクト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Notion.vue | `app/javascript/dashboard/routes/dashboard/settings/integrations/Notion.vue` | ソース | メイン画面コンポーネント |
| Integration.vue | `app/javascript/dashboard/routes/dashboard/settings/integrations/Integration.vue` | ソース | 連携カード共通コンポーネント |
| notion_auth.js | `app/javascript/dashboard/api/notion_auth.js` | ソース | Notion認証APIクライアント |
| 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` | ソース | ルート定義 |
