# バッチ設計書 40-restore

## 概要

本ドキュメントは、InvenTreeシステムにおけるリストアバッチ（restore）の設計仕様を定義する。

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

restoreは、InvenTreeのデータベースとメディアファイルをバックアップから復元するinvokeタスクである。django-dbbackupを使用してデータベースとメディアファイルのリストアを実行する。

**業務上の目的・背景**：InvenTreeはビジネスクリティカルな在庫管理データを保持しており、システム障害、データ破損、または誤操作によるデータ損失が発生した場合、迅速に正常な状態に復旧する必要がある。本バッチは、backupコマンドで作成されたバックアップファイルからデータベースとメディアファイルを復元し、システムを以前の正常な状態に戻すことを可能にする。これは災害復旧計画（DR）の重要な要素であり、ビジネス継続性を確保するために不可欠な機能である。

**バッチの実行タイミング**：手動実行（CLIコマンド）。以下の場面で実行される：
- システム障害後のデータ復旧時
- データ破損検出後の復元時
- マイグレーション失敗後のロールバック時
- テスト環境へのデータ復元時
- サーバー移行時

**主要な処理内容**：
1. データベースリストア（dbrestore）の実行
2. メディアファイルリストア（mediarestore）の実行
3. 圧縮・暗号化されたバックアップの解凍・復号化

**前後の処理との関連**：
- 前提：バックアップファイルが存在すること、データベース接続が確立されていること
- 後続：システムの動作確認、必要に応じてマイグレーション実行

**影響範囲**：
- データベース全体（上書き復元）
- メディアディレクトリ全体

## バッチ種別

リストア / データ復旧

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動、緊急時のみ） |
| 実行時刻 | 任意 |
| 実行曜日 | 任意 |
| 実行日 | 任意 |
| トリガー | 手動 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Django環境 | Django環境が正しく設定されていること |
| django-dbbackup | django-dbbackupパッケージがインストールされていること |
| バックアップファイル | 復元対象のバックアップファイルが存在すること |
| GPG（復号化時） | --decrypt使用時はGPGが設定されていること |

### 実行可否判定

特別な判定ロジックなし。コマンド実行時に常に処理を実行する。指定されたバックアップファイルが存在しない場合はdjango-dbbackupがエラーを返す。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| --path | str | No | None | バックアップファイルの格納パス |
| --db-file | str | No | None | データベースバックアップファイル名（指定しない場合は最新を使用） |
| --media-file | str | No | None | メディアバックアップファイル名（指定しない場合は最新を使用） |
| --decrypt | bool | No | False | バックアップファイルを復号化（GPG必要） |
| --skip-db | bool | No | False | データベースリストアをスキップ |
| --skip-media | bool | No | False | メディアリストアをスキップ |
| --uncompress | bool | No | True | バックアップファイルを解凍 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| データベースバックアップ | ファイル | backupで作成されたDBダンプ |
| メディアバックアップ | ファイル | backupで作成されたメディアアーカイブ |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| データベース | DB | 復元されたデータ |
| メディアディレクトリ | ファイルシステム | 復元されたファイル |

### 出力ファイル仕様

本バッチはファイルを出力せず、データベースとメディアディレクトリを復元する。

## 処理フロー

### 処理シーケンス

```
1. コマンドオプションの構築
   └─ --noinput -v 2 を基本オプションとして設定
   └─ --uncompress、--decrypt、-I パスを条件に応じて追加
2. データベースリストア（skip_dbでない場合）
   └─ manage.py dbrestore コマンドを実行
   └─ --db-file指定時は -i オプションを追加
3. メディアリストア（skip_mediaでない場合）
   └─ manage.py mediarestore コマンドを実行
   └─ --media-file指定時は -i オプションを追加
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[オプション構築]
    B --> C{uncompress?}
    C -->|Yes| D[--uncompress追加]
    C -->|No| E{decrypt?}
    D --> E
    E -->|Yes| F[--decrypt追加]
    E -->|No| G{path指定?}
    F --> G
    G -->|Yes| H[-I path追加]
    G -->|No| I{skip_db?}
    H --> I
    I -->|Yes| J[DB処理スキップ]
    I -->|No| K[dbrestore実行]
    J --> L{skip_media?}
    K --> L
    L -->|Yes| M[Media処理スキップ]
    L -->|No| N[mediarestore実行]
    M --> O[バッチ終了]
    N --> O
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| dbrestore | 全テーブル | DROP/CREATE/INSERT | データベース全体を復元 |

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

drestoreはデータベース全体を復元するため、全テーブルが対象となる。既存データは上書きまたは削除される可能性がある。

**注意**: この操作は破壊的であり、現在のデータベース内容は失われる可能性がある。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | UnexpectedExit | リストアコマンド失敗 | エラーログを確認し、原因を特定 |
| - | FileNotFoundError | バックアップファイルが見つからない | ファイルパスを確認 |
| - | PermissionError | ファイル読み取り権限がない | 権限を確認 |
| - | GPGError | 復号化設定の問題 | GPG設定を確認 |
| - | IntegrityError | データ整合性エラー | バックアップファイルの完全性を確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（手動再実行） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

1. エラーメッセージを確認
2. バックアップファイルの存在と完全性を確認
3. 別のバックアップファイルでの復元を試行
4. 問題解決後に再実行

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | django-dbbackupのリストア処理に依存 |
| コミットタイミング | リストア完了時 |
| ロールバック条件 | リストア処理中のエラー発生時 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | データベース全体 + メディアファイル全体 |
| 目標処理時間 | データ量に依存（数分〜数十分） |
| メモリ使用量上限 | django-dbbackupに依存 |

## 排他制御

リストア中は他のDB操作を行わないことを強く推奨。システムを停止してからリストアを実行することを推奨。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 情報ログ | DB処理スキップ時 | "Skipping database archive..." |
| 情報ログ | DBリストア開始時 | "Restoring InvenTree database" |
| 情報ログ | Mediaスキップ時 | "Skipping media restore..." |
| 情報ログ | Mediaリストア開始時 | "Restoring InvenTree media files" |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| リストア失敗 | 1回 | システム管理者 |

## 備考

- 本コマンドは `invoke restore` で実行
- **警告**: リストア操作は破壊的であり、現在のデータを上書きする
- リストア前に現在のデータのバックアップを取得することを強く推奨
- --uncompressはデフォルトでTrue（解凍有効）
- --db-fileや--media-fileを指定しない場合、最新のバックアップファイルが使用される
- --pathで相対パスを指定した場合、プロジェクトルートからの相対パスとして解決される
- リストア後はシステムの動作確認を行うことを推奨
- リストア後に必要に応じてマイグレーションを実行する必要がある場合がある
- 暗号化されたバックアップを復元する場合は--decryptオプションが必要
