# バッチ設計書 3-Check Schema Drift

## 概要

本ドキュメントは、Check Schema Driftバッチ（check-schema-drift.yml）の設計仕様を記載したものである。このバッチは、本番データベースとGitリポジトリのマイグレーションファイル間のスキーマ差分を検出し、差分が見つかった場合にSlack通知を行う定期実行バッチである。

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

**業務上の目的・背景**：Supabaseを使用したプロジェクトでは、本番データベースのスキーマとGitリポジトリ内のマイグレーションファイルの整合性を維持することが重要である。手動での本番DB変更やマイグレーション適用漏れにより、スキーマドリフト（差分）が発生する可能性がある。本バッチは、このような不整合を早期に検出し、開発チームに通知することで、データベース管理の品質を担保する。

**バッチの実行タイミング**：毎日9:00 JST（UTC 00:00）に定期実行される。手動実行（workflow_dispatch）も可能である。

**主要な処理内容**：
1. mainブランチのコードをチェックアウト
2. Supabase CLIをセットアップ
3. ローカルSupabase環境を起動
4. 本番データベースにリンク
5. `supabase db diff --linked --use-migra`コマンドでスキーマ差分を検出
6. 差分が存在する場合、Slack Webhookで通知

**前後の処理との関連**：本バッチは独立して動作する。スキーマドリフトが検出された場合、開発チームは手動で`supabase db pull`を実行してスキーマを同期する必要がある。

**影響範囲**：本番Supabaseデータベースへの読み取りアクセス、Slackチャンネルへの通知

## バッチ種別

監視 / 差分検出 / 通知

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 日次 |
| 実行時刻 | 9:00 JST（UTC 00:00） |
| 実行曜日 | 毎日 |
| 実行日 | - |
| トリガー | cron / 手動（workflow_dispatch） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| SUPABASE_PROJECT_REF | Supabaseプロジェクト参照IDがSecretsに設定されていること |
| SUPABASE_ACCESS_TOKEN | Supabase APIアクセストークンがSecretsに設定されていること |
| SLACK_CLI_CI_WEBHOOK_URL | Slack Incoming Webhook URLがSecretsに設定されていること |
| Supabase DB構成 | frontend/internal-packages/db配下にSupabase設定が存在すること |

### 実行可否判定

- スケジュール時刻（UTC 00:00）に自動実行
- 前提条件のSecretsが設定されていない場合は失敗

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| - | - | - | - | 入力パラメータなし |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| 本番Supabase DB | PostgreSQL | 本番データベースのスキーマ |
| Git Migrations | SQL | frontend/internal-packages/db/supabase/migrations/ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Actions Output | 環境変数 | drift_detected: true/false |
| Slack通知 | JSON | スキーマドリフト検出時の警告メッセージ |
| 一時ファイル | SQL | /tmp/schema_diff.sql（差分SQL） |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | /tmp/schema_diff.sql |
| 出力先 | GitHub Actionsランナー一時領域 |
| 文字コード | UTF-8 |
| 区切り文字 | - |

## 処理フロー

### 処理シーケンス

```
1. mainブランチチェックアウト
   └─ actions/checkout@v4.3.0を使用
   └─ persist-credentials: false
2. Supabase CLIセットアップ
   └─ supabase/setup-cli@v1.6.0を使用
   └─ version: latest
3. ローカルSupabase起動
   └─ cd frontend/internal-packages/db
   └─ supabase start
4. 本番DBリンク
   └─ supabase link --project-ref
   └─ SUPABASE_ACCESS_TOKEN使用
5. スキーマ差分チェック
   └─ supabase db diff --linked --use-migra
   └─ 結果を/tmp/schema_diff.sqlに出力
   └─ ファイルサイズで差分有無を判定
6. Slack通知（差分ありの場合のみ）
   └─ tokorom/action-slack-incoming-webhook@v1.3.0
   └─ 差分検出メッセージ、ドキュメントリンク、実行URL
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[mainブランチチェックアウト]
    B --> C[Supabase CLIセットアップ]
    C --> D[ローカルSupabase起動]
    D --> E[本番DBリンク]
    E --> F[スキーマ差分チェック]
    F --> G{差分あり?}
    G -->|はい| H[drift_detected=true]
    H --> I[差分SQLを出力]
    I --> J[Slack通知送信]
    G -->|いいえ| K[drift_detected=false]
    K --> L[差分なしログ出力]
    J --> M[バッチ終了]
    L --> M
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| スキーマ差分検出 | 全テーブル | SELECT | 本番DBスキーマの読み取り比較 |

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

本バッチは読み取り専用で、データベースへの書き込みは行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 認証エラー | SUPABASE_ACCESS_TOKEN無効 | Secretsの設定確認 |
| - | 接続エラー | 本番DBへの接続失敗 | ネットワーク/プロジェクト設定確認 |
| - | CLI起動エラー | ローカルSupabase起動失敗 | Docker環境確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

- ワークフロー失敗時：GitHub Actionsの実行ログを確認し、原因特定後に手動で再実行
- Slack通知失敗時：Webhook URLの有効性を確認

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし（読み取りのみ） |
| コミットタイミング | - |
| ロールバック条件 | - |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回/日 |
| 目標処理時間 | 15分以内（timeout-minutes: 15） |
| メモリ使用量上限 | GitHub Actions標準ランナー制限内 |

## 排他制御

- 特に排他制御なし
- 読み取り専用処理のため同時実行可能

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 各ステップ開始時 | ステップ名 |
| 進捗ログ | 差分チェック時 | "Schema drift detected!" または "No schema drift detected." |
| 終了ログ | バッチ終了時 | 差分SQL（差分ありの場合） |
| エラーログ | エラー発生時 | エラー詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| スキーマドリフト検出 | 差分あり | Slack (#cli-ci チャンネル想定) |
| 処理時間 | 15分 | GitHub Actionsタイムアウト |

## 備考

- スキーマドリフト検出時は、migrationOpsContext.mdのドキュメントを参照して対応
- `supabase db diff --linked --use-migra`はmigraツールを使用した高精度な差分検出
- Slack通知には以下の情報が含まれる：
  - ステータス：スキーマドリフト検出
  - 必要なアクション：`supabase db pull`の実行
  - ドキュメントリンク
  - ワークフロー実行URL
