# バッチ設計書 39-backup

## 概要

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

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

backupは、InvenTreeのデータベースとメディアファイルのバックアップを実行するinvokeタスクである。django-dbbackupを使用してデータベースダンプとメディアファイルのアーカイブを作成する。

**業務上の目的・背景**：InvenTreeは在庫管理システムであり、部品情報、在庫データ、発注履歴、添付ファイル（図面、写真など）といった重要なビジネスデータを保持している。システム障害、人為的ミス、またはマイグレーション失敗時のデータ損失を防ぐため、定期的なバックアップが不可欠である。本バッチは、データベースとメディアファイルの両方を一括でバックアップし、圧縮・暗号化オプションも提供することで、安全で効率的なバックアップ運用を可能にする。

**バッチの実行タイミング**：手動実行（CLIコマンド）。以下の場面で実行される：
- 定期的なバックアップ運用時
- `invoke update` コマンド実行時（skip_backupフラグが未設定の場合）
- システムアップデート・マイグレーション前
- 災害復旧計画の一環として

**主要な処理内容**：
1. データベースバックアップ（dbbackup）の実行
2. メディアファイルバックアップ（mediabackup）の実行
3. オプションで圧縮・暗号化処理
4. 古いバックアップファイルのクリーンアップ（オプション）

**前後の処理との関連**：
- 前提：データベース接続が確立されていること
- 後続：バックアップファイルの外部保存、restoreによるリストア

**影響範囲**：
- バックアップディレクトリへのファイル出力
- ディスク使用量

## バッチ種別

バックアップ / データ保護

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（手動）または定期実行 |
| 実行時刻 | 任意 |
| 実行曜日 | 任意 |
| 実行日 | 任意 |
| トリガー | 手動 / invoke update / スケジューラ |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Django環境 | Django環境が正しく設定されていること |
| django-dbbackup | django-dbbackupパッケージがインストールされていること |
| バックアップディレクトリ | バックアップ出力先への書き込み権限があること |
| GPG（暗号化時） | --encrypt使用時はGPGが設定されていること |

### 実行可否判定

特別な判定ロジックなし。コマンド実行時に常に処理を実行する。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| --clean | bool | No | False | 古いバックアップファイルを削除 |
| --compress | bool | No | True | バックアップファイルを圧縮 |
| --encrypt | bool | No | False | バックアップファイルを暗号化（GPG必要） |
| --path | str | No | None | バックアップファイルの出力先パス |
| --quiet | bool | No | False | 情報メッセージを抑制 |
| --skip-db | bool | No | False | データベースバックアップをスキップ |
| --skip-media | bool | No | False | メディアバックアップをスキップ |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| データベース | DB | InvenTreeデータベース全体 |
| メディアディレクトリ | ファイルシステム | アップロードされたファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| バックアップディレクトリ | ファイル | データベースダンプ |
| バックアップディレクトリ | ファイル | メディアアーカイブ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| データベースファイル | django-dbbackupの命名規則に従う |
| メディアファイル | django-dbbackupの命名規則に従う |
| 出力先 | --pathで指定またはデフォルトバックアップディレクトリ |
| 圧縮形式 | gzip（--compress時） |
| 暗号化 | GPG（--encrypt時） |

## 処理フロー

### 処理シーケンス

```
1. コマンドオプションの構築
   └─ --noinput -v 2 を基本オプションとして設定
   └─ --compress、--encrypt、-O パス、--clean、--quietを条件に応じて追加
2. データベースバックアップ（skip_dbでない場合）
   └─ manage.py dbbackup コマンドを実行
3. メディアバックアップ（skip_mediaでない場合）
   └─ manage.py mediabackup コマンドを実行
4. 完了メッセージ出力
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[オプション構築]
    B --> C{compress?}
    C -->|Yes| D[--compress追加]
    C -->|No| E{encrypt?}
    D --> E
    E -->|Yes| F[--encrypt追加]
    E -->|No| G{path指定?}
    F --> G
    G -->|Yes| H[-O path追加]
    G -->|No| I{clean?}
    H --> I
    I -->|Yes| J[--clean追加]
    I -->|No| K{quiet?}
    J --> K
    K -->|Yes| L[--quiet追加]
    K -->|No| M{skip_db?}
    L --> M
    M -->|Yes| N[DB処理スキップ]
    M -->|No| O[dbbackup実行]
    N --> P{skip_media?}
    O --> P
    P -->|Yes| Q[Media処理スキップ]
    P -->|No| R[mediabackup実行]
    Q --> S{バックアップ実行?}
    R --> S
    S -->|Yes| T[完了メッセージ]
    S -->|No| U[バッチ終了]
    T --> U
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| dbbackup | 全テーブル | SELECT（ダンプ） | データベース全体をダンプ |

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

dbbackupはデータベース全体をダンプするため、全テーブルが対象となる。読み取り専用操作であり、データの変更は行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | UnexpectedExit | バックアップコマンド失敗 | エラーログを確認し、原因を特定 |
| - | PermissionError | 出力先への書き込み権限がない | 権限を確認して再実行 |
| - | DiskFullError | ディスク容量不足 | ディスク容量を確保 |
| - | GPGError | 暗号化設定の問題 | GPG設定を確認 |

### リトライ仕様

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

### 障害時対応

1. エラーメッセージを確認
2. ディスク容量、権限、ネットワーク（リモートDB）を確認
3. 問題解決後に再実行

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | django-dbbackupのダンプ処理に依存 |
| コミットタイミング | N/A（読み取り専用） |
| ロールバック条件 | N/A |

## パフォーマンス要件

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

## 排他制御

同時実行の制御は行わない。バックアップ中のDB操作は可能だが、一貫性のあるバックアップのためには低負荷時の実行を推奨。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 情報ログ | DB処理スキップ時 | "Skipping database backup..." |
| 情報ログ | DBバックアップ開始時 | "Backing up InvenTree database..." |
| 情報ログ | Mediaスキップ時 | "Skipping media backup..." |
| 情報ログ | Mediaバックアップ開始時 | "Backing up InvenTree media files..." |
| 成功ログ | 完了時 | "Backup completed successfully" |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| バックアップ失敗 | 1回 | システム管理者 |
| ディスク使用量 | 設定による | システム管理者 |

## 備考

- 本コマンドは `invoke backup` で実行
- `invoke update` 実行時にも自動的に呼び出される（skip_backupフラグがない場合）
- django-dbbackupを使用
- --compressはデフォルトでTrue（圧縮有効）
- --pathで相対パスを指定した場合、プロジェクトルートからの相対パスとして解決される
- バックアップファイルの保持期間管理は別途設定が必要
- 暗号化を使用する場合はGPG受信者の設定が必要
