# バッチ設計書 30-check_migrations

## 概要

本ドキュメントは、マイグレーションの整合性をチェックするDjango管理コマンド「check_migrations」の設計仕様を定義する。

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

このコマンドは、InvenTreeシステムの保留中のデータベースマイグレーションを確認し、必要に応じて自動実行することで、データベーススキーマの整合性を維持する。runmigrationsコマンドと同じ内部処理を呼び出す。

**業務上の目的・背景**：システム運用において、データベースマイグレーションの適用状態を確認することは重要である。未適用のマイグレーションがあると、アプリケーションの動作に支障をきたす可能性がある。本コマンドは、マイグレーション状態の確認と、必要に応じた自動適用を行うことで、システムの健全性を維持する。

**バッチの実行タイミング**：手動実行（CLI）。システム起動時やメンテナンス時に実行される。

**主要な処理内容**：
1. 保留中のマイグレーションを確認
2. 必要に応じてメンテナンスモードを有効化
3. Django標準のmigrateコマンドを実行
4. マイグレーション完了後、メンテナンスモードを解除

**前後の処理との関連**：runmigrationsコマンドと同じ処理を実行する。check_for_migrations関数を共有している。

**影響範囲**：データベーススキーマの変更、アプリケーション全体の一時停止に影響する。

## バッチ種別

データベース管理 / 整合性チェック / CLIコマンド

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動） |
| 実行時刻 | システム起動時またはメンテナンス時 |
| 実行曜日 | 不定 |
| 実行日 | 不定 |
| トリガー | CLIコマンド: `python manage.py check_migrations` |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| データベース接続 | InvenTreeデータベースに正常に接続できること |
| 管理者権限 | データベーススキーマ変更権限があること |

### 実行可否判定

特別な実行可否判定はなく、コマンド実行時に即座に処理を開始する。保留中のマイグレーションがない場合も正常終了する。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | 本コマンドは入力パラメータを受け取らない |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| django_migrations | DB | 適用済みマイグレーション履歴 |
| マイグレーションファイル | Python | 各アプリのmigrationsディレクトリ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| データベーススキーマ | DB | スキーマ変更（マイグレーション適用時） |
| django_migrations | DB | 適用済みマイグレーション記録 |
| ログ | Log | マイグレーション確認・実行ログ |

### 出力ファイル仕様

本コマンドはファイル出力を行わない。

## 処理フロー

### 処理シーケンス

```
1. マイグレーション確認開始
   └─ logger.info('Checking for pending database migrations')
2. check_for_migrations関数を呼び出し
   └─ check_for_migrations(force=True, reload_registry=False)
3. check_for_migrations内部処理
   └─ 保留中マイグレーションを取得（get_migration_plan）
   └─ マイグレーションなしの場合は即座に終了
   └─ マイグレーションありの場合：
      └─ メンテナンスモードを有効化
      └─ call_command('migrate', interactive=False) を実行
      └─ メンテナンスモードを無効化
      └─ プラグインレジストリの再読み込み（reload_registry=Trueの場合のみ）
4. 完了ログ出力
   └─ logger.info('Database migrations complete')
```

### フローチャート

```mermaid
flowchart TD
    A[コマンド開始] --> B[Checking for pending database migrations ログ出力]
    B --> C[check_for_migrations呼び出し]
    C --> D[get_migration_planでマイグレーション計画取得]
    D --> E{保留中マイグレーションあり?}
    E -->|なし| F[_PENDING_MIGRATIONS = 0 を設定]
    E -->|あり| G[マイグレーション数を記録]
    G --> H{auto_update有効 または force=True?}
    H -->|No| I[スキップ]
    H -->|Yes| J[メンテナンスモード有効化]
    J --> K[migrate コマンド実行]
    K --> L{成功?}
    L -->|Yes| M[_PENDING_MIGRATIONS = 0 を設定]
    L -->|No| N[エラーログ出力]
    M --> O[メンテナンスモード無効化]
    N --> O
    O --> P[Database migrations complete ログ出力]
    F --> P
    I --> P
    P --> Q[コマンド終了]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| マイグレーション履歴確認 | django_migrations | SELECT | 適用済みマイグレーション確認 |
| マイグレーション数記録 | common_inventreesetting | INSERT/UPDATE | _PENDING_MIGRATIONS設定 |
| スキーマ変更 | 各テーブル | ALTER/CREATE/DROP | マイグレーション内容に依存 |
| マイグレーション記録 | django_migrations | INSERT | 適用済みマイグレーション記録 |

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

#### django_migrations

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | app, name | 全件 | 適用済み確認 |
| INSERT | app, name, applied | マイグレーション情報 | 適用後に記録 |

#### common_inventreesetting

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | key | = '_PENDING_MIGRATIONS' | 保留中マイグレーション数 |
| UPDATE | value | マイグレーション数 | 0 = 完了、n = 保留中 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | NotSupportedError | SQLite制限による操作不可 | SQLiteの場合はログ出力して継続 |
| - | Exception | その他のマイグレーションエラー | エラーログ出力、メンテナンスモード解除 |

### リトライ仕様

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

### 障害時対応

マイグレーション失敗時はメンテナンスモードが有効なまま残る可能性がある。手動でメンテナンスモードを解除し、マイグレーションの問題を調査・修正後に再実行する。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 各マイグレーションファイルごと |
| コミットタイミング | 各マイグレーション成功後 |
| ロールバック条件 | 個別マイグレーションでのエラー発生時 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 数件〜数十件のマイグレーション |
| 目標処理時間 | マイグレーション内容に依存（数秒〜数分） |
| メモリ使用量上限 | 通常のDjangoプロセス制限内 |

## 排他制御

メンテナンスモードにより、処理中は他のユーザーからのアクセスをブロックする。これにより、マイグレーション中のデータ不整合を防止する。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 処理開始時 | "Checking for pending database migrations" |
| 情報ログ | 保留中マイグレーション検出時 | "There are {n} pending migrations" |
| 情報ログ | 各マイグレーション実行時 | マイグレーション名 |
| エラーログ | エラー発生時 | エラー詳細 |
| 終了ログ | 処理完了時 | "Database migrations complete" |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | マイグレーション内容に依存 | システム管理者 |
| エラー発生 | 1件以上 | システム管理者 |

## 備考

- 本コマンドはDjango管理コマンド（BaseCommand）として実装されている
- 実行方法: `python manage.py check_migrations`
- 内部的にInvenTree.tasks.check_for_migrations関数を呼び出す（runmigrationsと同一）
- force=Trueにより、INVENTREE_AUTO_UPDATE設定に関係なく実行
- reload_registry=Falseにより、プラグインレジストリの再読み込みをスキップ
- runmigrationsコマンドと同じ処理を実行するが、コマンド名が異なる
- メンテナンスモードはmaintenance_modeパッケージを使用
- _PENDING_MIGRATIONS設定で保留中マイグレーション数を追跡
- structlogを使用したログ出力
