# バッチ設計書 54-railties:install:migrations

## 概要

本ドキュメントは、Railties（エンジン等）から不足しているマイグレーションファイルをアプリケーションにコピーするRakeタスクについて記載する。

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

このバッチは、Railsアプリケーションに組み込まれたエンジン（Railties）からデータベースマイグレーションファイルをアプリケーションのマイグレーションディレクトリにコピーするためのRakeタスクである。

**業務上の目的・背景**：Railsエンジンは独自のデータベーステーブルを持つことができるが、エンジンのマイグレーションをホストアプリケーションで実行するためには、マイグレーションファイルをアプリケーションのdb/migrateディレクトリにコピーする必要がある。本タスクは、複数のエンジンのマイグレーションを一括で管理し、重複したマイグレーションのコピーを防ぎつつ、必要なマイグレーションのみを取り込むことを可能にする。

**バッチの実行タイミング**：手動実行が基本。新しいエンジンの追加後、エンジンのアップデート後、デプロイ前の準備作業として実行する。

**主要な処理内容**：
1. データベース設定のロード
2. FROM環境変数で指定されたRailtiesのフィルタリング（省略時は全エンジン）
3. 各Railtieのdb/migrateパスからマイグレーションファイルを取得
4. MIGRATIONS_PATHが指定されている場合はカスタムパスを使用
5. 同名のマイグレーションが既に存在する場合はスキップ
6. 新規マイグレーションをアプリケーションのマイグレーションディレクトリにコピー

**前後の処理との関連**：本バッチ実行後、db:migrateを実行してマイグレーションを適用する。エンジン個別のinstall:migrationsタスク（例：active_storage:install:migrations）は内部的に本タスクを呼び出す。

**影響範囲**：アプリケーションのdb/migrateディレクトリへのファイル追加。データベース構造には直接影響しないが、後続のdb:migrateでテーブルが作成される。

## バッチ種別

ファイル操作（マイグレーションファイルのコピー）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動） |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | 手動実行 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| database.yml | データベース設定ファイルが存在すること |
| エンジンのロード | コピー元となるRailsエンジンがアプリケーションにロードされていること |
| マイグレーションディレクトリ | 出力先のマイグレーションディレクトリが存在すること |

### 実行可否判定

db:load_configが前提タスクとして実行され、データベース設定が読み込まれる。設定が読み込めない場合はエラーとなる。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| FROM | String | No | - | コピー元のRailtie名（カンマ区切りで複数指定可能） |
| MIGRATIONS_PATH | String | No | db/migrate | エンジン内のカスタムマイグレーションパス |
| DATABASE | String | No | primary | コピー先のデータベース名（マルチDB環境用） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| 各エンジンのdb/migrateディレクトリ | .rbファイル | Railsマイグレーションファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| db/migrate（またはDATABASE指定のパス） | .rbファイル | コピーされたマイグレーションファイル |
| 標準出力 | テキスト | コピー結果・スキップ結果のメッセージ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | {タイムスタンプ}_{元のマイグレーション名}.{エンジン名}.rb |
| 出力先 | db/migrate（またはconfig.migrations_pathsで指定されたパス） |
| 文字コード | UTF-8 |
| 区切り文字 | - |

## 処理フロー

### 処理シーケンス

```
1. データベース設定ロード
   └─ db:load_configを実行
2. Railtie抽出
   └─ FROM環境変数でフィルタリング（空の場合は全Railtie）
3. マイグレーションパス取得
   └─ 各Railtieのdb/migrateパスを取得
   └─ MIGRATIONS_PATH指定時はカスタムパスを使用
4. コピー先決定
   └─ DATABASE指定時はカスタムmigrations_pathsを使用
   └─ 未指定時はデフォルトのmigrations_pathsを使用
5. マイグレーションコピー
   └─ ActiveRecord::Migration.copyを実行
6. 結果出力
   └─ コピーしたファイル、スキップしたファイルを出力
```

### フローチャート

```mermaid
flowchart TD
    A[タスク開始] --> B[db:load_config]
    B --> C{FROM指定あり?}
    C -->|Yes| D[指定されたRailtieのみ抽出]
    C -->|No| E[全Railtieを対象]
    D --> F[マイグレーションパス取得]
    E --> F
    F --> G{MIGRATIONS_PATH指定?}
    G -->|Yes| H[カスタムパス使用]
    G -->|No| I[デフォルトパス使用]
    H --> J{DATABASE指定?}
    I --> J
    J -->|Yes| K[指定DBのmigrations_path使用]
    J -->|No| L[デフォルトmigrations_path使用]
    K --> M[ActiveRecord::Migration.copy実行]
    L --> M
    M --> N{同名ファイル存在?}
    N -->|Yes| O["NOTE: スキップメッセージ出力"]
    N -->|No| P["Copied: コピーメッセージ出力"]
    O --> Q[タスク終了]
    P --> Q
```

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

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

本バッチはデータベースを直接操作しない。ファイルシステム上のマイグレーションファイルのコピーのみ行う。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | データベース操作なし |

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

直接のテーブル操作なし（後続のdb:migrateでテーブルが作成される）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 設定エラー | DATABASE指定が無効 | "Invalid DATABASE provided"メッセージ、正しいDB名を指定 |
| - | 設定エラー | 指定DBにカスタムmigrations_pathなし | "does not have a custom migration path"、DB設定を確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（手動タスク） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

1. エラーメッセージを確認し、設定を修正後に再実行する
2. 同名マイグレーションがスキップされた場合は、既存ファイルとの競合を確認する
3. 必要に応じて既存マイグレーションをリネームして再実行する

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 数件〜数十件（マイグレーションファイル数） |
| 目標処理時間 | 数秒以内 |
| メモリ使用量上限 | 特になし（軽量処理） |

## 排他制御

同時実行は推奨しない。ファイルコピー処理のため、同時実行時は予期しないファイル競合が発生する可能性がある。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| コピーログ | マイグレーションコピー時 | "Copied migration {ファイル名} from {エンジン名}" |
| スキップログ | 同名ファイル存在時 | "NOTE: Migration {ファイル名} from {エンジン名} has been skipped..." |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| - | - | 手動実行のため監視対象外 |

## 備考

- マイグレーションファイルはエンジン名のサフィックス付きでコピーされる（例：20240101000000_create_users.active_storage.rb）
- 同名マイグレーションが既に存在する場合はスキップされ、NOTEメッセージが出力される
- エンジン個別のinstall:migrationsタスク（例：active_storage:install:migrations）は、FROM=エンジン名を設定して本タスクを呼び出す
- マルチデータベース環境ではDATABASE環境変数で出力先を指定可能
