# 機能設計書 82-Webhook詳細表示

## 概要

本ドキュメントは、Fizzyアプリケーションにおける「Webhook詳細表示」機能の設計仕様を定義する。既存のWebhook設定の詳細情報を表示し、配信履歴を確認する機能である。

### 本機能の処理概要

Webhook詳細表示機能は、作成済みのWebhook設定の全情報を確認するための機能である。Webhookの名前、ペイロードURL、署名シークレット、購読イベント、および過去の配信履歴を一覧で確認できる。

**業務上の目的・背景**：チーム管理者がWebhookの設定内容を確認し、外部サービスとの連携が正しく動作しているかを監視するために必要な機能である。署名シークレットの確認や、配信成功・失敗の履歴確認により、連携のトラブルシューティングを行うことができる。

**機能の利用シーン**：管理者がWebhook設定の確認や、外部サービス側での設定（署名検証）を行う際に使用する。また、Webhookが期待通りに動作しているかを配信履歴で確認する際にも使用される。

**主要な処理内容**：
1. 指定されたWebhookの情報をデータベースから取得
2. Webhook基本情報（名前、URL、署名シークレット）の表示
3. 購読イベント一覧の表示
4. 配信履歴（最新20件）の表示
5. 非アクティブな場合は再アクティベーションボタンを表示

**関連システム・外部連携**：なし（参照のみ）

**権限による制御**：ボードの管理者（admin）権限を持つユーザーのみがWebhook詳細を閲覧できる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 62 | Webhook一覧画面 | 参照画面 | 一覧からこの詳細画面に遷移 |
| 64 | Webhook詳細画面 | 主画面 | Webhook詳細情報を表示 |
| 65 | Webhook編集画面 | 結果表示画面 | 編集ボタンから遷移 |

## 機能種別

CRUD操作（Read）/ 参照・表示

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| board_id | UUID | Yes | ボードID | URLパラメータ |
| id | UUID | Yes | WebhookID | URLパラメータ |

### 入力データソース

URLパラメータ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| name | String | Webhook名 |
| url | String | ペイロードURL |
| signing_secret | String | 署名検証用シークレット |
| active | Boolean | アクティブ状態 |
| subscribed_actions | Array | 購読イベント一覧 |
| deliveries | Array | 配信履歴（最新20件） |

### 出力先

HTML画面表示

## 処理フロー

### 処理シーケンス

```
1. リクエスト受信
   └─ GET /boards/:board_id/webhooks/:id
2. 認証・認可チェック
   └─ ログインユーザーかつボード管理者権限を確認
3. ボード取得
   └─ Current.userのボードからboard_idで検索
4. Webhook取得
   └─ @board.webhooks.find(params[:id])
5. ビューレンダリング
   └─ Webhook詳細情報と配信履歴を表示
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{ログイン済み?}
    B -->|No| C[ログイン画面へ]
    B -->|Yes| D{管理者権限?}
    D -->|No| E[403 Forbidden]
    D -->|Yes| F[ボード取得]
    F --> G{ボード存在?}
    G -->|No| H[404 Not Found]
    G -->|Yes| I[Webhook取得]
    I --> J{Webhook存在?}
    J -->|No| K[404 Not Found]
    J -->|Yes| L[詳細画面レンダリング]
    L --> M[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-82-01 | 配信履歴制限 | 配信履歴は最新20件のみ表示 | 詳細画面表示時 |
| BR-82-02 | シークレット表示 | 署名シークレットは常に表示（マスクなし） | 管理者のみアクセス可能なため |
| BR-82-03 | 再アクティベーション | 非アクティブ時のみ再アクティベーションボタンを表示 | active=false時 |

### 計算ロジック

該当なし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| Webhook取得 | webhooks | SELECT | 指定IDのWebhookを取得 |
| 配信履歴取得 | webhook_deliveries | SELECT | 関連する配信履歴を取得 |

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

#### webhooks

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | 全カラム | id = params[:id] AND board_id = @board.id | 単一レコード取得 |

#### webhook_deliveries

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | 全カラム | webhook_id = @webhook.id ORDER BY created_at DESC LIMIT 20 | 最新20件 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 401 | Unauthorized | 未ログイン | ログイン画面へリダイレクト |
| 403 | Forbidden | 管理者権限なし | 権限エラー表示 |
| 404 | NotFound | ボードまたはWebhookが存在しない | エラーページ表示 |

### リトライ仕様

該当なし

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

参照のみのためトランザクション制御なし

## パフォーマンス要件

- レスポンス時間: 500ms以内
- 配信履歴は最新20件に制限してパフォーマンスを確保

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

- 管理者権限チェックによる認可制御
- 署名シークレットの表示は管理者のみのため問題なし

## 備考

配信履歴の各エントリには以下の情報が含まれる：
- 配信日時
- 配信状態（pending/in_progress/completed/errored）
- 成功/失敗の判定

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | webhook.rb | `app/models/webhook.rb` | Webhookモデルの属性とリレーション |
| 1-2 | delivery.rb | `app/models/webhook/delivery.rb` | 配信履歴モデルの構造 |

**読解のコツ**: `has_many :deliveries`により配信履歴が関連付けられている。`scope :ordered`で配信日時の降順ソートが定義されている。

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

コントローラーのshowアクションが処理の起点となる。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | webhooks_controller.rb | `app/controllers/webhooks_controller.rb` | showアクションの処理フロー |

**主要処理フロー**:
1. **4行目**: `before_action :ensure_admin` - 管理者権限チェック
2. **5行目**: `before_action :set_webhook` - Webhook取得
3. **11-12行目**: `show`アクション - ビューレンダリング（暗黙的）
4. **37-39行目**: `set_webhook`メソッド - Webhook取得ロジック

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

詳細画面の表示内容を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | show.html.erb | `app/views/webhooks/show.html.erb` | 詳細画面の構造 |
| 3-2 | _delivery.html.erb | `app/views/webhooks/_delivery.html.erb` | 配信履歴の表示形式 |

**主要処理フロー**:
- **20-21行目**: Webhook名とURL表示
- **23-27行目**: 非アクティブ時の再アクティベーションボタン
- **30-37行目**: 署名シークレット表示
- **41-50行目**: 購読イベント一覧
- **54-60行目**: 配信履歴表示（最新20件）

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

```
WebhooksController#show
    │
    ├─ BoardScoped#set_board
    │      └─ Current.user.boards.find(params[:board_id])
    │
    ├─ ApplicationController#ensure_admin
    │      └─ Current.user.admin?
    │
    └─ set_webhook
           └─ @board.webhooks.find(params[:id])
                  │
                  └─ @webhook.deliveries.ordered.limit(20)
```

### データフロー図

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

URLパラメータ ───▶ WebhooksController ───▶ HTML画面
  - board_id              │
  - id                    │
                          ▼
                    webhooksテーブル ───▶ Webhook情報表示
                          │               - name
                          │               - url
                          │               - signing_secret
                          │               - subscribed_actions
                          ▼
                    webhook_deliveries ───▶ 配信履歴表示
                    テーブル                 - 最新20件
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| webhooks_controller.rb | `app/controllers/webhooks_controller.rb` | ソース | showアクション実装 |
| webhook.rb | `app/models/webhook.rb` | ソース | Webhookモデル |
| delivery.rb | `app/models/webhook/delivery.rb` | ソース | 配信履歴モデル |
| show.html.erb | `app/views/webhooks/show.html.erb` | テンプレート | 詳細画面 |
| _delivery.html.erb | `app/views/webhooks/_delivery.html.erb` | テンプレート | 配信履歴パーシャル |
| webhooks_helper.rb | `app/helpers/webhooks_helper.rb` | ソース | ヘルパーメソッド |
| routes.rb | `config/routes.rb` | 設定 | ルーティング定義 |
