# 画面設計書 62-マクロ一覧画面

## 概要

本ドキュメントは、Chatwootのマクロ一覧画面の設計仕様を記述したものです。

### 本画面の処理概要

本画面は、アカウント内で作成されたマクロ（Macros）の一覧を表示し、マクロの管理を行うための画面です。マクロは、複数のアクションをまとめて実行できるショートカット機能であり、エージェントの業務効率化に貢献します。

**業務上の目的・背景**：カスタマーサポート業務において、頻繁に行う一連の操作（例：チームへの割り当て、ラベル付け、ステータス変更など）をマクロとして保存しておくことで、1クリックで複数のアクションを実行できます。これにより、エージェントの作業時間を短縮し、操作ミスを防止します。本画面は、これらのマクロを一覧表示し、新規作成・編集・削除の操作を提供します。

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

**主要な操作・処理内容**：
1. マクロの一覧表示（名前、作成者、更新者、公開範囲）
2. 新規マクロ作成画面への遷移
3. 既存マクロの編集画面への遷移
4. マクロの削除（確認ダイアログ付き）

**画面遷移**：
- 遷移元：設定ホーム画面、サイドバーメニュー
- 遷移先：マクロ新規作成画面（`macros_new`）、マクロ編集画面（`macros_edit`）

**権限による表示制御**：全ロール（管理者・エージェント）がアクセス可能です。ただし、公開範囲（visibility）によって表示されるマクロが異なります。
- グローバルマクロ：全ユーザーに表示
- 個人マクロ：作成者本人のみに表示

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 75 | マクロ（ショートカット） | 主機能 | マクロの一覧表示 |

## 画面種別

一覧

## URL/ルーティング

| 項目 | 値 |
|------|-----|
| パス | `/app/accounts/:accountId/settings/macros` |
| ルート名 | `macros_wrapper` |
| コンポーネント | `app/javascript/dashboard/routes/dashboard/settings/macros/Index.vue` |
| 権限 | `ROLES`, `CONVERSATION_PERMISSIONS` |
| フィーチャーフラグ | `MACROS` |

## 入出力項目

### 入力項目

本画面での直接入力はなし（削除確認のみ）

## 表示項目

### 一覧テーブル

| 項目名 | 項目ID | 型 | 説明 |
|--------|--------|-----|------|
| マクロ名 | name | string | マクロの名称 |
| 作成者 | created_by | object | 作成者のアバターと名前 |
| 最終更新者 | updated_by | object | 最終更新者のアバターと名前 |
| 公開範囲 | visibility | string | `global`（全体公開）または `personal`（個人） |

### アクションボタン

| ボタン名 | アイコン | 説明 |
|---------|---------|------|
| 編集 | i-lucide-pen | マクロ編集画面へ遷移 |
| 削除 | i-lucide-trash-2 | マクロを削除 |

## イベント仕様

### 1-マクロ追加ボタン押下

ヘッダー部の「+ Add Macro」ボタンをクリックすると、マクロ新規作成画面に遷移します。

**処理フロー**：
1. `router-link` により `macros_new` ルートに遷移
2. `MacroEditor.vue` コンポーネントが表示される

### 2-マクロ編集ボタン押下

一覧の各行にある編集ボタンをクリックすると、マクロ編集画面に遷移します。

**処理フロー**：
1. `router-link` により `macros_edit` ルートに遷移（`macroId` パラメータ付き）
2. `MacroEditor.vue` コンポーネントが表示される

### 3-マクロ削除ボタン押下

一覧の各行にある削除ボタンをクリックすると、確認ダイアログが表示されます。

**処理フロー**：
1. `openDeletePopup(macro)` が呼び出される
2. 選択されたマクロが `selectedMacro` に格納される
3. `showDeleteConfirmationPopup` が `true` に設定される
4. 確認後、`confirmDeletion()` が呼び出される
5. `store.dispatch('macros/delete', id)` でAPIを呼び出し
6. 成功時：成功メッセージを表示
7. 失敗時：エラーメッセージを表示

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| マクロ一覧取得 | macros | SELECT | アクセス可能なマクロを取得 |
| マクロ削除 | macros | DELETE | 指定されたマクロを削除 |

### テーブル別更新項目詳細

#### macros

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | - | visibility = 'global' OR (visibility = 'personal' AND created_by_id = current_user.id) | アクセス可能なマクロのみ取得 |
| DELETE | - | WHERE id = :id | 指定IDのレコードを削除 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示タイミング |
|-------------|------|---------------|---------------|
| MACROS.DELETE.API.SUCCESS_MESSAGE | 成功 | マクロ削除成功 | 削除成功時 |
| MACROS.DELETE.API.ERROR_MESSAGE | エラー | マクロ削除失敗 | 削除失敗時 |
| MACROS.DELETE.CONFIRM.MESSAGE | 確認 | 削除確認メッセージ | 削除ボタン押下時 |
| MACROS.DELETE.CONFIRM.YES | 確認 | 削除確定ボタンテキスト | 確認ダイアログ |
| MACROS.DELETE.CONFIRM.NO | 確認 | キャンセルボタンテキスト | 確認ダイアログ |
| MACROS.LIST.404 | 情報 | マクロがありません | マクロが0件の場合 |
| MACROS.LOADING | 情報 | 読み込み中 | データ取得中 |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| データ取得失敗 | エラーを無視し、空のリストを表示 |
| 削除失敗 | エラーメッセージをアラート表示 |
| 権限不足 | 表示されるマクロが制限される（グローバルと自分の個人マクロのみ） |

## 備考

- マクロの公開範囲（visibility）は `personal`（個人）と `global`（全体公開）の2種類
- エージェントロールのユーザーは個人マクロのみ作成可能
- 管理者ロールのユーザーはグローバルマクロも作成可能
- 一覧の取得は `Macro.with_visibility(user, params)` で公開範囲に応じたフィルタリングが行われる
- Enterprise版では監査ログ機能が追加される（`Macro.include_mod_with('Audit::Macro')`）

---

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

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

### 推奨読解順序

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

マクロのデータ構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | macro.rb | `app/models/macro.rb` | モデル定義、visibility enum、ACTIONS_ATTRS定数を確認 |

**読解のコツ**: `visibility` が `enum` で定義されており、`personal: 0`, `global: 1` の値を持ちます。`with_visibility` クラスメソッドで公開範囲に応じたフィルタリングを行います。

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

Vueコンポーネントがエントリーポイントとなります。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Index.vue | `app/javascript/dashboard/routes/dashboard/settings/macros/Index.vue` | 画面の構成、Vuexストアとの連携を確認 |

**主要処理フロー**:
1. **23-25行目**: `onMounted` で `store.dispatch('macros/get')` を呼び出し
2. **18-19行目**: `computed` プロパティでストアからデータを取得
3. **27-48行目**: 削除処理のイベントハンドラ

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | MacrosTableRow.vue | `app/javascript/dashboard/routes/dashboard/settings/macros/MacrosTableRow.vue` | 各行の表示項目、編集・削除ボタンの動作を確認 |

**主要処理フロー**:
- **17-25行目**: 作成者・更新者の名前を computed で取得
- **27-33行目**: 公開範囲のラベルを i18n キーから取得
- **55行目**: 編集ボタンは `router-link` で遷移

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | macros.js | `app/javascript/dashboard/store/modules/macros.js` | state、getters、actions、mutationsの構造を確認 |

**主要処理フロー**:
- **31-41行目**: `get` アクションでAPI呼び出し
- **85-95行目**: `delete` アクションで削除処理

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

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

**主要処理フロー**:
- **4-7行目**: `ApiClient` を継承し、`macros` エンドポイントを使用

#### Step 6: バックエンド層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 6-1 | macros_controller.rb | `app/controllers/api/v1/accounts/macros_controller.rb` | コントローラのアクション、認可処理を確認 |

**主要処理フロー**:
- **7-9行目**: `index` アクションで `Macro.with_visibility` を使用
- **45-48行目**: `destroy` アクションで削除

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

```
Index.vue (エントリーポイント)
    │
    ├─ onMounted()
    │      └─ store.dispatch('macros/get')
    │             └─ MacrosAPI.get()
    │                    └─ GET /api/v1/accounts/:account_id/macros
    │                           └─ Macro.with_visibility(user, params)
    │
    ├─ MacrosTableRow.vue
    │      ├─ router-link (編集)
    │      │      └─ macros_edit ルートへ遷移
    │      │
    │      └─ @delete イベント
    │             └─ openDeletePopup()
    │
    └─ deleteMacro()
           └─ store.dispatch('macros/delete')
                  └─ MacrosAPI.delete()
                         └─ DELETE /api/v1/accounts/:account_id/macros/:id
```

### データフロー図

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

ユーザー操作 ────────▶ Index.vue ─────────────▶ 画面表示更新
                           │
                           ▼
                      Vuex Store
                       (macros)
                           │
                           ▼
                      MacrosAPI
                           │
                           ▼
                  Rails Controller
               (macros_controller.rb)
                           │
                           ▼
                        Macro
                       (Model)
                           │
                           ▼
                    PostgreSQL
                      (macros)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Index.vue | `app/javascript/dashboard/routes/dashboard/settings/macros/Index.vue` | ソース | メイン画面コンポーネント |
| MacrosTableRow.vue | `app/javascript/dashboard/routes/dashboard/settings/macros/MacrosTableRow.vue` | ソース | 一覧行コンポーネント |
| macros.js | `app/javascript/dashboard/store/modules/macros.js` | ソース | Vuexストアモジュール |
| macros.js | `app/javascript/dashboard/api/macros.js` | ソース | APIクライアント |
| macros.routes.js | `app/javascript/dashboard/routes/dashboard/settings/macros/macros.routes.js` | ソース | ルート定義 |
| macros_controller.rb | `app/controllers/api/v1/accounts/macros_controller.rb` | ソース | Railsコントローラ |
| macro.rb | `app/models/macro.rb` | ソース | モデル定義 |
| SettingsLayout.vue | `app/javascript/dashboard/routes/dashboard/settings/SettingsLayout.vue` | ソース | 設定画面レイアウト |
| BaseSettingsHeader.vue | `app/javascript/dashboard/routes/dashboard/settings/components/BaseSettingsHeader.vue` | ソース | 設定画面ヘッダー |
