# 機能設計書 40-型定義生成

## 概要

本ドキュメントは、Supabaseデータベーススキーマから TypeScript 型定義を自動生成する機能について記述する。本機能は、Supabase CLIを使用してローカルデータベースのスキーマを解析し、型安全なデータベースアクセスを可能にする型定義ファイルを生成する。

### 本機能の処理概要

**業務上の目的・背景**：データベーススキーマとアプリケーションコードの型整合性を保つことは、ランタイムエラー防止と開発効率向上に不可欠である。本機能は、マイグレーション適用後に型定義を自動生成することで、スキーマ変更を型レベルで検出可能にする。

**機能の利用シーン**：
- マイグレーション適用後の型定義更新
- スキーマ変更のコードレビュー
- CI/CDパイプラインでのスキーマドリフト検出

**主要な処理内容**：
1. supabase gen types typescript：TypeScript型定義生成
2. supabase db dump：SQL schemaファイル出力
3. biome check --write：生成ファイルのフォーマット

**関連システム・外部連携**：
- Supabase CLI：型定義生成コマンド
- Supabase Branching：PRプレビュー環境
- GitHub Actions：スキーマドリフト検出

**権限による制御**：
開発環境でのみ実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLI | 利用画面 | 型定義生成コマンド実行 |

## 機能種別

開発ツール・ビルドツール

## 入力仕様

### 入力パラメータ

#### supabase gen types

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --local | flag | Yes | ローカルDB使用 | - |
| 出力先 | リダイレクト | Yes | 型定義ファイルパス | - |

#### supabase db dump

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| --local | flag | Yes | ローカルDB使用 | - |
| 出力先 | リダイレクト | Yes | SQLファイルパス | - |

### 入力データソース

- ローカルSupabaseデータベーススキーマ
- supabase/migrationsディレクトリのSQLファイル

## 出力仕様

### 出力データ

- `supabase/database.types.ts`：TypeScript型定義
- `supabase/schemas/schema.sql`：データベーススキーマSQL

### 出力先

- `frontend/internal-packages/db/supabase/`

## 処理フロー

### 処理シーケンス

#### 型定義生成フロー

```
1. ローカルSupabase起動確認
   └─ pnpm supabase status
2. マイグレーション適用
   └─ pnpm supabase:migration:up
3. 型定義生成
   ├─ pnpm supabase:gen:types → database.types.ts
   └─ pnpm supabase:gen:schema_sql → schema.sql
4. フォーマット
   └─ biome check --write --unsafe
```

### フローチャート

```mermaid
flowchart TD
    A[マイグレーション作成] --> B[supabase:migration:up]
    B --> C[supabase:gen]
    C --> D[supabase:gen:types]
    C --> E[supabase:gen:schema_sql]
    D --> F[database.types.ts]
    E --> G[schema.sql]
    F --> H[biome format]
    H --> I[型定義完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-40-01 | ローカルDB使用 | 型定義はローカルDBから生成 | 開発時 |
| BR-40-02 | マイグレーション後生成 | マイグレーション適用後に必ず型生成 | スキーマ変更時 |
| BR-40-03 | フォーマット適用 | biomeでフォーマット統一 | 型定義生成後 |
| BR-40-04 | コミット必須 | 型定義変更はコミットに含める | PRマージ前 |
| BR-40-05 | スキーマドリフト検出 | 日次CIでドリフトチェック | 本番環境 |

### 生成される型構造

| 型名 | 説明 |
|-----|------|
| Database | データベース全体の型 |
| Tables | 各テーブルの型（Row/Insert/Update） |
| Views | ビューの型 |
| Functions | RPC関数の型（Args/Returns） |
| Enums | Enum型 |
| CompositeTypes | 複合型 |
| Json | JSON型のユニオン |

### スキーマごとの型構造

| スキーマ | 主要テーブル |
|---------|-------------|
| public | organizations, projects, design_sessions, building_schemas 等 |
| graphql_public | GraphQL関連 |

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

本機能はスキーマの読み取りのみを行い、データ操作は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Supabase未起動 | ローカルSupabaseが起動していない | pnpm supabase:start |
| - | マイグレーションエラー | SQLエラー | マイグレーションファイル修正 |
| - | スキーマドリフト | 本番と型定義の不一致 | supabase db pull --linked |

### リトライ仕様

該当なし。

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

該当なし（読み取りのみ）。

## パフォーマンス要件

- 型定義生成は数秒で完了
- スキーマドリフト検出は日次実行

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

- 型定義ファイルに機密情報は含まれない
- Service Role Keyはローカル環境のみ使用

## 備考

- Supabase Branchingにより、PRごとにプレビュー環境が自動作成
- スキーマドリフト検出は`.github/workflows/check-schema-drift.yml`で定義
- マイグレーションファイル名は`YYYYMMDDHHmmss_description.sql`形式

---

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

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

### 推奨読解順序

#### Step 1: package.jsonのスクリプトを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | package.json | `frontend/internal-packages/db/package.json` | supabase関連スクリプト |

**主要処理フロー**:
- **34行目**: supabase:gen - 型定義とスキーマSQLの同時生成
- **35行目**: supabase:gen:schema_sql - schema.sql出力
- **36行目**: supabase:gen:types - database.types.ts生成 + biome format
- **37-40行目**: マイグレーション関連コマンド

#### Step 2: 生成された型定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | database.types.ts | `frontend/internal-packages/db/supabase/database.types.ts` | 型構造 |

**主要処理フロー**:
- **1-7行目**: Json型定義（プリミティブ/オブジェクト/配列）
- **9-34行目**: graphql_publicスキーマ
- **35行目以降**: publicスキーマ（Tables、Views、Functions）
- **各テーブル**: Row（読み取り）、Insert（挿入）、Update（更新）、Relationships

#### Step 3: マイグレーション運用を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | migrationOpsContext.md | `docs/migrationOpsContext.md` | 運用ガイドライン |

**主要処理フロー**:
- **1-30行目**: デプロイメントシステム、ブランチングワークフロー
- **31-51行目**: スキーマドリフト防止・検出
- **53-93行目**: マイグレーション作成ルール
- **154-167行目**: マイグレーション後の手順

#### Step 4: 型オーバーライドを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | supabase-overrides/index.ts | `frontend/internal-packages/db/src/types/supabase-overrides/index.ts` | カスタム型マージ |

**主要処理フロー**:
- **1-9行目**: 各オーバーライド型のインポート
- **11-20行目**: MergeDeepによる型合成

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

```
pnpm supabase:gen
    ├─ supabase:gen:schema_sql
    │      └─ supabase db dump --local
    │             └─ schema.sql
    │
    └─ supabase:gen:types
           ├─ supabase gen types typescript --local
           │      └─ database.types.ts（生成）
           └─ biome check --write --unsafe
                  └─ database.types.ts（フォーマット）

型の利用フロー:
database.types.ts
    │
    ↓
src/types/supabase-overrides/index.ts
    │ MergeDeep
    ↓
AppDatabaseOverrides
    │
    ↓
createServerClient<AppDatabaseOverrides>
```

### データフロー図

```
マイグレーションファイル
supabase/migrations/*.sql
         │
         ↓ supabase:migration:up
┌─────────────────────────────┐
│ ローカルPostgreSQLデータベース │
│ (Docker)                     │
└─────────────┬───────────────┘
              │
    ┌─────────┴─────────┐
    ↓                   ↓
supabase db dump   supabase gen types
    │                   │
    ↓                   ↓
schema.sql        database.types.ts
                        │
                        ↓ biome format
                  database.types.ts
                  （フォーマット済み）
                        │
                        ↓
              AppDatabaseOverrides
              （型オーバーライド適用）
                        │
                        ↓
              SupabaseClient<AppDatabaseOverrides>
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| package.json | `frontend/internal-packages/db/package.json` | 設定 | npmスクリプト定義 |
| database.types.ts | `frontend/internal-packages/db/supabase/database.types.ts` | 生成ファイル | 型定義 |
| schema.sql | `frontend/internal-packages/db/supabase/schemas/schema.sql` | 生成ファイル | スキーマSQL |
| migrationOpsContext.md | `docs/migrationOpsContext.md` | ドキュメント | 運用ガイドライン |
| check-schema-drift.yml | `.github/workflows/check-schema-drift.yml` | CI設定 | スキーマドリフト検出 |
| supabase-overrides/index.ts | `frontend/internal-packages/db/src/types/supabase-overrides/index.ts` | ソース | 型オーバーライド |

### コマンド一覧

| コマンド | 説明 |
|---------|------|
| pnpm supabase:start | ローカルSupabase起動 |
| pnpm supabase:stop | ローカルSupabase停止 |
| pnpm supabase:reset | データベースリセット |
| pnpm supabase:migration -f <name> | マイグレーション作成 |
| pnpm supabase:migration:up | マイグレーション適用 |
| pnpm supabase:gen | 型定義・スキーマSQL生成 |
