# 画面設計書 62-Webhook一覧画面

## 概要

本ドキュメントは、FizzyアプリケーションにおけるWebhook一覧画面の設計仕様を定義するものである。

### 本画面の処理概要

この画面は、特定のボードに設定されたWebhookの一覧を表示し、管理者がWebhookの追加・削除を行うための画面である。Webhookは外部アプリケーションとの連携を可能にし、ボード内で発生したイベント（カード追加、コメント作成など）を外部サービスに通知する機能を提供する。

**業務上の目的・背景**：Fizzyを他のツール（Slack、Basecamp、Campfireなど）と連携させることで、チームのワークフローを自動化し、情報の分断を防ぐ。例えば、新しいカードがFizzyに追加された際にSlackチャンネルに自動通知を送ることで、チームメンバーが最新の状況を把握しやすくなる。この機能により、複数ツールを横断した効率的なチーム運営が可能になる。

**画面へのアクセス方法**：ボード詳細画面のヘッダーメニューから「Webhooks」ボタンをクリックしてアクセスする。管理者権限を持つユーザーのみがアクセス可能。

**主要な操作・処理内容**：
1. 登録済みWebhookの一覧表示
2. 各Webhookの詳細画面への遷移
3. Webhookの削除（確認ダイアログ付き）
4. 新規Webhook設定画面への遷移

**画面遷移**：
- 遷移元：ボード詳細画面、ボード設定画面
- 遷移先：Webhook詳細画面、Webhook新規作成画面、ボード詳細画面

**権限による表示制御**：管理者（admin）権限を持つユーザーのみがこの画面にアクセス可能。一般メンバーはアクセスできない。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 80 | Webhook一覧表示 | 主機能 | ボードに設定されたWebhook一覧を表示 |

## 画面種別

一覧

## URL/ルーティング

`GET /boards/:board_id/webhooks`

## 入出力項目

（入力項目なし - 一覧表示のみ）

## 表示項目

| 項目名 | 説明 |
|--------|------|
| ページタイトル | 「Webhooks」固定 |
| Webhook名 | 各Webhookの名前（リンク付き） |
| 削除ボタン | 各Webhookを削除するボタン |
| 新規作成リンク | 「Set up a new webhook」ボタン |
| 説明テキスト | Webhookが未登録の場合に表示される説明文 |

### Webhook未登録時の表示

Webhookが1件も登録されていない場合、以下の説明テキストが表示される：
- 「Webhooks can notify another application when something happens in this Fizzy board. You'll choose which events to subscribe to and provide a URL to receive the data.」
- 「For example, you could create a webhook that posts to a Campfire chat in Basecamp when new cards are added to Fizzy.」

## イベント仕様

### 1-Webhook名クリック

選択したWebhookの詳細画面（`/boards/:board_id/webhooks/:id`）に遷移する。

### 2-削除ボタン押下

1. 確認ダイアログ「Are you sure you want to permanently remove this webhook?」を表示
2. 確認後、`DELETE /boards/:board_id/webhooks/:id` にリクエスト送信
3. Webhookレコードと関連するdeliveriesを削除
4. Webhook一覧画面をリロード

### 3-新規作成リンク押下

Webhook新規作成画面（`/boards/:board_id/webhooks/new`）に遷移する。

### 4-戻るボタン押下

ボード詳細画面に戻る。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 削除ボタン押下 | webhooks | DELETE | Webhookレコードを削除 |
| 削除ボタン押下 | webhook_deliveries | DELETE | 関連する配信履歴を削除 |
| 削除ボタン押下 | webhook_delinquency_trackers | DELETE | 関連する遅延追跡レコードを削除 |

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

#### webhooks（削除時）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | - | WHERE id = :id AND board_id = :board_id | カスケード削除でdeliveriesも削除 |

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 表示条件 |
|---------------|---------------|----------|
| 確認 | Are you sure you want to permanently remove this webhook? | 削除ボタン押下時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 未認証アクセス | ログイン画面へリダイレクト |
| 権限不足（非管理者） | 403 Forbidden |
| ボードが見つからない | 404エラー |

## 備考

- Webhookはボード単位で設定される
- 削除時は関連するwebhook_deliveriesも`dependent: :delete_all`で削除される
- 一覧はname昇順、id降順でソートされる（`scope :ordered`）

---

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

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

### 推奨読解順序

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

Webhookの構造と関連モデルを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | webhook.rb | `app/models/webhook.rb` | Webhookモデルの定義、バリデーション、スコープ |
| 1-2 | schema.rb | `db/schema.rb` | webhooksテーブル（830-842行目）、webhook_deliveriesテーブル（815-828行目） |

**読解のコツ**: `has_many :deliveries, dependent: :delete_all` により、Webhook削除時に関連する配信履歴も自動削除される。

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

コントローラーのindex/destroyアクションを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | webhooks_controller.rb | `app/controllers/webhooks_controller.rb` | index, destroyアクションの処理フロー |
| 2-2 | board_scoped.rb | `app/controllers/concerns/board_scoped.rb` | ボードスコープの設定 |

**主要処理フロー**:
1. **2行目**: BoardScopedをinclude - @boardを設定
2. **4行目**: before_action :ensure_admin - 管理者権限チェック
3. **7-9行目**: indexアクション - Webhookをページネーション付きで取得
4. **31-34行目**: destroyアクション - Webhookを削除

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

一覧画面のUI構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.html.erb | `app/views/webhooks/index.html.erb` | 一覧画面のメインテンプレート |
| 3-2 | _webhook.html.erb | `app/views/webhooks/_webhook.html.erb` | 各Webhook行のパーシャル |

**主要処理フロー（index.html.erb）**:
- **1行目**: ページタイトルを「Webhooks」に設定
- **3-9行目**: ヘッダーに戻るリンクを配置
- **12-15行目**: Webhookが存在する場合、一覧をレンダリング
- **16-18行目**: Webhookが存在しない場合、説明文を表示
- **21-24行目**: 新規作成ボタン

**主要処理フロー（_webhook.html.erb）**:
- **2-4行目**: Webhook名（詳細画面へのリンク）
- **8-12行目**: 削除ボタン（確認ダイアログ付き）

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

```
[ユーザー] Webhooksボタンクリック
    │
    └─ GET /boards/:board_id/webhooks
           │
           ├─ BoardScoped#set_board
           │      └─ Current.user.boards.find(params[:board_id])
           │
           ├─ ApplicationController#ensure_admin
           │      └─ 管理者権限チェック
           │
           └─ WebhooksController#index
                  │
                  ├─ @board.webhooks.ordered
                  │
                  └─ render "webhooks/index"
                         │
                         └─ render partial: "webhooks/webhook", collection: @page.records
```

### データフロー図

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

GET /boards/:id/webhooks ─▶ WebhooksController#index ──────▶ webhooks/index.html.erb
                                   │
                                   └─ @board.webhooks.ordered
                                          │
                                          └─ webhooks テーブルからSELECT

DELETE /webhooks/:id ──────▶ WebhooksController#destroy ───▶ redirect_to webhooks
                                   │
                                   └─ @webhook.destroy!
                                          │
                                          ├─ webhooks テーブルからDELETE
                                          └─ webhook_deliveries をカスケード削除
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| webhooks_controller.rb | `app/controllers/webhooks_controller.rb` | コントローラー | Webhook CRUD操作を処理 |
| webhook.rb | `app/models/webhook.rb` | モデル | Webhookデータの管理 |
| index.html.erb | `app/views/webhooks/index.html.erb` | ビュー | Webhook一覧画面 |
| _webhook.html.erb | `app/views/webhooks/_webhook.html.erb` | パーシャル | 各Webhook行の表示 |
| board_scoped.rb | `app/controllers/concerns/board_scoped.rb` | Concern | ボードスコープ設定 |
| webhooks_helper.rb | `app/helpers/webhooks_helper.rb` | ヘルパー | Webhookリンク生成など |
| routes.rb | `config/routes.rb` | 設定 | ルーティング定義（47-51行目） |
