# バッチ設計書 19-Notify Supabase Failure

## 概要

本ドキュメントは、GitHub Actions ワークフロー「Notify Supabase Failure」の設計を定義するものである。Supabaseデプロイ失敗時にSlackへ通知するバッチ処理について記載する。

### 本バッチの処理概要

**業務上の目的・背景**：本プロジェクトはSupabaseをデータベースインフラとして使用している。mainブランチへのマージ後にSupabaseデプロイが失敗した場合、即座にチームに通知することが重要である。本バッチは、GitHub Check Suiteイベントを監視し、Supabaseアプリからの失敗通知を検出してSlackに警告を送信する。これにより、本番環境のデータベース問題を早期に発見し、迅速な対応を可能にする。

**バッチの実行タイミング**：GitHub Check Suiteが完了（completed）し、以下の条件を全て満たす場合に実行：
- アプリ名が「Supabase」
- 結論（conclusion）が「failure」
- 対象ブランチが「main」

**主要な処理内容**：
1. Check Suite completedイベントの受信
2. Supabase失敗条件の検証
3. Slack Incoming Webhookへの通知送信
4. 失敗詳細（ブランチ、アプリ名、結果、Check Suite URL）の提供

**前後の処理との関連**：本バッチはSupabase GitHub Appのデプロイプロセスを監視する。Release（No.5）やDatabase CI（No.7）とは独立して動作する。

**影響範囲**：Slackチャンネル（SLACK_CLI_CI_WEBHOOK_URL）

## バッチ種別

障害通知 / 監視 / アラート

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（随時） |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | Check Suite completed（Supabase失敗時） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Supabase統合 | Supabase GitHub Appがリポジトリに接続されていること |
| シークレット | SLACK_CLI_CI_WEBHOOK_URLが設定されていること |
| 権限 | contents: read が付与されていること |

### 実行可否判定

以下の全条件が満たされた場合のみ実行：
- `github.event.check_suite.app.name == 'Supabase'`
- `github.event.check_suite.conclusion == 'failure'`
- `github.event.check_suite.head_branch == 'main'`

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| SLACK_CLI_CI_WEBHOOK_URL | シークレット | Yes | - | Slack Incoming Webhook URL |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| github.event.check_suite | オブジェクト | Check Suite情報 |
| github.event.check_suite.app.name | 文字列 | アプリ名（Supabase） |
| github.event.check_suite.conclusion | 文字列 | 結果（failure） |
| github.event.check_suite.head_branch | 文字列 | ブランチ名（main） |
| github.event.check_suite.check_runs_url | URL | Check Runs詳細URL |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| Slack通知 | Attachments | 失敗通知（赤色） |
| GitHub Checks | Status | CI実行結果（成功/失敗） |

### 出力ファイル仕様

ファイル出力は行わない。

## 処理フロー

### 処理シーケンス

```
1. Check Suiteイベント受信
   └─ completedタイプを検出

2. 条件検証
   └─ Supabaseアプリ、failure、mainブランチか確認

3. Slack通知送信
   └─ Incoming Webhookに失敗情報をPOST
```

### フローチャート

```mermaid
flowchart TD
    A[Check Suite completed] --> B{app.name == Supabase?}
    B -->|いいえ| C[スキップ]
    B -->|はい| D{conclusion == failure?}
    D -->|いいえ| C
    D -->|はい| E{head_branch == main?}
    E -->|いいえ| C
    E -->|はい| F[Slack通知送信]
    F --> G[通知内容: Branch, App, Result, URL]
    G --> H[ステータス: 成功]
    C --> I[バッチ終了]
    H --> I
```

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

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

データベース操作は行わない。

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| WEBHOOK_FAILED | 通知エラー | Slack Webhook送信失敗 | Webhook URLの有効性確認 |
| NETWORK_ERROR | ネットワークエラー | Slack APIへの接続失敗 | 一時的な問題であれば自動復旧 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | tokorom/action-slack-incoming-webhookの設定に準拠 |
| リトライ間隔 | アクション依存 |
| リトライ対象エラー | 一時的なネットワークエラー |

### 障害時対応

1. ワークフロー実行ログで通知失敗を確認
2. SLACK_CLI_CI_WEBHOOK_URLの有効性を確認
3. Slack Webhook設定（https://api.slack.com/apps/A08CVT65VAT）を確認
4. 手動でSlackに通知

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1通知 |
| 目標処理時間 | 10分以内（timeout-minutes: 10） |
| メモリ使用量上限 | GitHubランナー標準（7GB） |

## 排他制御

排他制御の設定はない。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | ワークフロー開始時 | Check Suite情報 |
| 終了ログ | ワークフロー終了時 | 通知結果 |
| エラーログ | エラー発生時 | 通知失敗詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| Supabase失敗 | 1回 | Slack（SLACK_CLI_CI_WEBHOOK_URL） |
| 通知失敗 | 1回 | GitHub Checks UI |

## 備考

- tokorom/action-slack-incoming-webhook v1.3.0（コミット: d57bf1eb618f3dae9509afefa70d5774ad3d42bf）を使用
- Slack App ID: A08CVT65VAT
- 通知カラー: bad（赤色）
- 通知フィールド: Branch（main）、Check Suite App、Result（failure）、Check Suite URL
- mainブランチのみを監視対象とし、featureブランチでの失敗は通知しない
