# 画面設計書 63-Webhook新規作成画面

## 概要

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

### 本画面の処理概要

この画面は、ボードに新しいWebhookを設定するためのフォーム画面である。ユーザーはWebhookの名前、ペイロードURL、購読するイベントタイプを指定して、外部アプリケーションとの連携を設定できる。

**業務上の目的・背景**：Fizzyボードで発生するイベント（カード追加、コメント作成、担当者変更など）を外部サービスに自動通知する仕組みを構築する。これにより、Slack、Basecamp Campfire、その他のサービスとのリアルタイム連携が可能となり、チーム間の情報共有とワークフロー自動化を実現する。

**画面へのアクセス方法**：Webhook一覧画面から「Set up a new webhook」ボタンをクリックしてアクセスする。管理者権限を持つユーザーのみがアクセス可能。

**主要な操作・処理内容**：
1. Webhook名の入力（必須）
2. ペイロードURLの入力（必須、http://またはhttps://で始まる必要あり）
3. 購読するイベントの選択（複数選択可能）
4. 「Create Webhook」ボタンでWebhookを作成
5. Escキーまたは「Go back」リンクでキャンセル

**画面遷移**：
- 遷移元：Webhook一覧画面
- 遷移先：作成成功時はWebhook詳細画面、キャンセル時はWebhook一覧画面

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 81 | Webhook作成 | 主機能 | 新しいWebhookを作成 |

## 画面種別

登録

## URL/ルーティング

- 画面表示: `GET /boards/:board_id/webhooks/new`
- 作成処理: `POST /boards/:board_id/webhooks`

## 入出力項目

| 項目名 | 項目ID | データ型 | 必須 | 最大長 | 入力形式 | 説明 |
|--------|--------|----------|------|--------|----------|------|
| Webhook名 | name | string | 必須 | - | テキスト | Webhookの識別名 |
| ペイロードURL | url | text | 必須 | - | URL | 通知先のエンドポイントURL |
| 購読イベント | subscribed_actions | array | - | - | チェックボックス | 通知するイベントの種類（複数選択可） |

### 購読可能なイベント一覧

| イベントID | 表示名 | 説明 |
|-----------|--------|------|
| card_published | Card added | カードが追加された |
| card_board_changed | Card board changed | カードのボードが変更された |
| comment_created | Comment added | コメントが追加された |
| card_assigned | Card assigned | カードに担当者がアサインされた |
| card_unassigned | Card unassigned | カードから担当者が外された |
| card_triaged | Card column changed | カードのカラムが変更された |
| card_closed | Card moved to "Done" | カードが完了した |
| card_reopened | Card reopened | カードが再オープンした |
| card_postponed | Card moved to "Not Now" | カードがNot Nowに移動された |
| card_auto_postponed | Card moved to "Not Now" due to inactivity | 非活動によりカードがNot Nowに自動移動された |
| card_sent_back_to_triage | Card moved back to "Maybe?" | カードがMaybe?に戻された |

## 表示項目

| 項目名 | 説明 |
|--------|------|
| ページタイトル | 「Set up a Webhook」固定 |
| 戻るリンク | Webhook一覧画面への戻りリンク |
| 名前入力フィールド | Webhook名を入力するテキストフィールド |
| URL入力フィールド | ペイロードURLを入力するフィールド |
| URLヘルプテキスト | 「This is the URL for the app that will receive payloads from Fizzy.」 |
| イベント選択ラベル | 「Events」と「Trigger a call to the Payload URL when:」 |
| イベントチェックボックス | 各イベントタイプの選択チェックボックス |
| Enable all ボタン | 全イベントを選択 |
| Disable all ボタン | 全イベントの選択を解除 |
| 作成ボタン | 「Create Webhook」 |

## イベント仕様

### 1-Create Webhookボタン押下

1. フォームバリデーション実行
   - name: 必須チェック
   - url: 必須チェック、URL形式チェック（http://またはhttps://）
2. バリデーション成功時、`POST /boards/:board_id/webhooks` にリクエスト送信
3. Webhookレコードを作成（signing_secretは自動生成）
4. 作成したWebhookの詳細画面にリダイレクト

### 2-Enable allボタン押下

全てのイベントチェックボックスをチェック状態にする。

### 3-Disable allボタン押下

全てのイベントチェックボックスのチェックを外す。

### 4-戻るリンク押下・Escキー押下

Webhook一覧画面に遷移する。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Create Webhook押下 | webhooks | INSERT | 新規Webhookレコードを作成 |
| Create Webhook押下 | webhook_delinquency_trackers | INSERT | 遅延追跡レコードを自動作成 |

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

#### webhooks

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | id | UUID自動生成 | 主キー |
| INSERT | account_id | @board.account_id | ボードのアカウントID |
| INSERT | board_id | @board.id | 所属ボードID |
| INSERT | name | フォーム入力値 | 必須 |
| INSERT | url | フォーム入力値 | 必須、http/https |
| INSERT | subscribed_actions | フォーム入力値（配列） | JSON形式で保存 |
| INSERT | signing_secret | has_secure_token自動生成 | 署名検証用シークレット |
| INSERT | active | true | デフォルト値 |
| INSERT | created_at | 現在日時 | 自動設定 |
| INSERT | updated_at | 現在日時 | 自動設定 |

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 表示条件 |
|---------------|---------------|----------|
| バリデーションエラー | Name can't be blank | 名前が未入力の場合 |
| バリデーションエラー | Url not a URL | URLが不正な形式の場合 |
| バリデーションエラー | Url must use http or https | プロトコルが不正な場合 |
| ブラウザバリデーション | Must be an http:// or https:// URL | パターン不一致時（title属性） |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 未認証アクセス | ログイン画面へリダイレクト |
| 権限不足（非管理者） | 403 Forbidden |
| ボードが見つからない | 404エラー |
| バリデーションエラー | フォームを再表示、エラーメッセージ表示 |

## 備考

- URLにはhttp://またはhttps://のみ許可（Webhook::PERMITTED_SCHEMES）
- signing_secretはhas_secure_tokenにより自動生成され、Webhook認証に使用
- subscribed_actionsはWebhook::PERMITTED_ACTIONSで許可されたアクションのみ保存される
- 作成時にdelinquency_trackerも自動作成される（after_create :create_delinquency_tracker!）

---

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

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

### 推奨読解順序

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

Webhookモデルのバリデーションと許可アクションを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | webhook.rb | `app/models/webhook.rb` | バリデーション、PERMITTED_ACTIONS定数、has_secure_token |
| 1-2 | schema.rb | `db/schema.rb` | webhooksテーブル構造（830-842行目） |

**読解のコツ**:
- `PERMITTED_ACTIONS`（9-21行目）で許可されるイベント種別を確認
- `has_secure_token :signing_secret`（23行目）で署名シークレットの自動生成を確認
- `normalizes :subscribed_actions`（38行目）で入力値の正規化処理を確認

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

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

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

**主要処理フロー**:
1. **14-16行目**: newアクション - 空のWebhookインスタンスを生成
2. **18-21行目**: createアクション - Webhookを作成し詳細画面にリダイレクト
3. **41-44行目**: webhook_params - Strong Parametersで許可するパラメータを定義

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

フォームのUI構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | new.html.erb | `app/views/webhooks/new.html.erb` | 新規作成フォームテンプレート |
| 3-2 | _actions.html.erb | `app/views/webhooks/form/_actions.html.erb` | イベント選択パーシャル |

**主要処理フロー（new.html.erb）**:
- **1行目**: ページタイトルを設定
- **12行目**: form_withでフォーム開始
- **14行目**: 名前入力フィールド（required, autofocus）
- **22-28行目**: URL入力フィールド（required, pattern付き）
- **36行目**: イベント選択パーシャルをレンダリング
- **39-41行目**: 作成ボタン

**主要処理フロー（_actions.html.erb）**:
- **3行目**: Enable allボタン
- **5行目**: Disable allボタン
- **8-22行目**: collection_check_boxesでイベント選択チェックボックスを生成

#### Step 4: ヘルパーを理解する

イベント選択オプションの生成を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | webhooks_helper.rb | `app/helpers/webhooks_helper.rb` | webhook_action_options, ACTION_LABELS |

**主要処理フロー**:
- **2-15行目**: ACTION_LABELS - イベントIDと表示名のマッピング
- **17-19行目**: webhook_action_options - 許可されたアクションのオプションを返す

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

```
[ユーザー] Set up a new webhookクリック
    │
    ├─ GET /boards/:board_id/webhooks/new
    │      │
    │      └─ WebhooksController#new
    │             │
    │             ├─ @webhook = @board.webhooks.new
    │             │
    │             └─ render "webhooks/new"
    │                    │
    │                    └─ render "webhooks/form/actions"
    │
    └─ POST /boards/:board_id/webhooks（送信時）
           │
           └─ WebhooksController#create
                  │
                  ├─ @board.webhooks.create!(webhook_params)
                  │      │
                  │      ├─ has_secure_token :signing_secret
                  │      │
                  │      └─ after_create :create_delinquency_tracker!
                  │
                  └─ redirect_to webhook
```

### データフロー図

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

フォーム送信 ───────────▶ WebhooksController#create ──────▶ Webhook詳細画面
  - name                        │
  - url                         ├─ webhook_params
  - subscribed_actions[]        │      │
                                │      └─ Strong Parameters
                                │
                                ├─ @board.webhooks.create!
                                │      │
                                │      ├─ normalizes :subscribed_actions
                                │      │
                                │      ├─ validate_url
                                │      │
                                │      └─ webhooks テーブルにINSERT
                                │
                                └─ webhook_delinquency_trackers にINSERT
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| webhooks_controller.rb | `app/controllers/webhooks_controller.rb` | コントローラー | Webhook CRUD操作を処理 |
| webhook.rb | `app/models/webhook.rb` | モデル | Webhookデータの管理、バリデーション |
| new.html.erb | `app/views/webhooks/new.html.erb` | ビュー | 新規作成フォーム |
| _actions.html.erb | `app/views/webhooks/form/_actions.html.erb` | パーシャル | イベント選択UI |
| webhooks_helper.rb | `app/helpers/webhooks_helper.rb` | ヘルパー | イベント選択オプション生成 |
| board_scoped.rb | `app/controllers/concerns/board_scoped.rb` | Concern | ボードスコープ設定 |
| routes.rb | `config/routes.rb` | 設定 | ルーティング定義 |
