# バッチ設計書 43-export_records

## 概要

本ドキュメントは、InvenTreeの全データベースレコードをJSONファイルにエクスポートするinvokeタスク「export_records」の設計書です。

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

**業務上の目的・背景**：システムのバックアップ、環境間のデータ移行、またはデータ分析のために、InvenTreeのデータベースに格納された全レコードをポータブルなJSON形式でエクスポートする必要があります。このバッチは、Djangoのdumpdataコマンドをラップし、不要なデータの除外や権限情報の処理を自動化します。

**バッチの実行タイミング**：データバックアップ、環境移行、またはデータ分析が必要な場合に手動で実行します。

**主要な処理内容**：
1. 出力先ファイルの存在確認（上書き確認）
2. 除外対象のコンテンツタイプを設定（django_q, exchange, common等）
3. Djangoのdumpdataコマンドで一時ファイルにデータをダンプ
4. 一時ファイルを後処理（権限情報の除去、一時設定の除去）
5. 処理済みデータを最終出力ファイルに書き込み
6. 一時ファイルの削除（retain_temp=Falseの場合）

**前後の処理との関連**：import_recordsタスクと対になるデータエクスポート機能です。エクスポートしたJSONファイルはimport_recordsでインポート可能です。

**影響範囲**：読み取り専用の操作であり、データベースのデータには影響しません。出力先ファイルシステムにファイルを作成します。

## バッチ種別

データエクスポート / バックアップ

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| データベース接続 | データベースへの接続が確立されていること |
| Python環境 | 正しいPython仮想環境がアクティブであること |
| ディスク容量 | 出力ファイル用の十分なディスク容量があること |
| 書き込み権限 | 出力先ディレクトリへの書き込み権限があること |

### 実行可否判定

特別な実行可否判定はありません。前提条件が満たされていれば実行可能です。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| filename | str | No | 'data.json' | 出力ファイル名 |
| overwrite | bool | No | False | 既存ファイルを確認なしで上書きする |
| include_email | bool | No | False | メールログを出力に含める |
| include_permissions | bool | No | False | ユーザー・グループの権限情報を出力に含める |
| include_tokens | bool | No | False | APIトークンを出力に含める |
| exclude_plugins | bool | No | False | プラグインデータを出力から除外する |
| include_sso | bool | No | False | SSOトークンデータを出力に含める |
| include_session | bool | No | False | ユーザーセッションデータを出力に含める |
| retain_temp | bool | No | False | 処理終了後に一時ファイルを保持する |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| データベース | DB | InvenTreeの全テーブル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 指定ファイル | JSON | エクスポートされたデータベースレコード |
| 一時ファイル | JSON | 後処理前のダンプデータ（retain_temp=Trueの場合のみ保持） |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | パラメータで指定（デフォルト: data.json） |
| 出力先 | カレントディレクトリまたは指定されたパス |
| 文字コード | UTF-8 |
| 区切り文字 | 該当なし（JSONフォーマット） |

### 除外されるコンテンツタイプ

以下のコンテンツタイプはデフォルトで除外されます：
- contenttypes
- auth.permission
- error_report.error
- admin.logentry
- django_q.schedule, django_q.task, django_q.ormq
- exchange.rate, exchange.exchangebackend
- common.dataoutput, common.newsfeedentry, common.notificationentry, common.notificationmessage
- importer.dataimportsession, importer.dataimportcolumnmap, importer.dataimportrow

## 処理フロー

### 処理シーケンス

```
1. パス解決
   └─ 相対パスの場合は絶対パスに変換

2. ファイル存在確認
   └─ 既存ファイルがある場合、overwrite=Falseなら確認ダイアログを表示

3. 除外コンテンツ設定
   └─ パラメータに基づいて除外対象を設定

4. dumpdataコマンド実行
   └─ 一時ファイルにデータをダンプ

5. 後処理
   ├─ 一時設定（キーが_で始まる）を除外
   └─ include_permissions=Falseの場合、権限情報を空配列に置換

6. 最終出力
   └─ 処理済みデータをファイルに書き込み

7. クリーンアップ
   └─ retain_temp=Falseの場合、一時ファイルを削除
```

### フローチャート

```mermaid
flowchart TD
    A[export_records開始] --> B[パス解決]
    B --> C{ファイル存在?}
    C -->|Yes| D{overwrite=True?}
    C -->|No| F[除外コンテンツ設定]
    D -->|No| E[上書き確認]
    D -->|Yes| F
    E -->|No| Z[キャンセル]
    E -->|Yes| F
    F --> G[dumpdataコマンド実行]
    G --> H[後処理:一時設定除外]
    H --> I{include_permissions?}
    I -->|No| J[権限情報を空配列に置換]
    I -->|Yes| K[最終ファイル出力]
    J --> K
    K --> L{retain_temp?}
    L -->|No| M[一時ファイル削除]
    L -->|Yes| N[export_records完了]
    M --> N
    Z --> O[終了]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| dumpdata | 全テーブル（除外対象を除く） | SELECT | データの読み取りのみ |

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

本タスクはデータベースの読み取りのみを行い、書き込みは行いません。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | FileExistsError | ファイルが既に存在し、上書きを拒否した場合 | 別のファイル名を指定するか、--overwriteを使用 |
| - | PermissionError | 出力先への書き込み権限がない場合 | 出力先の権限を確認 |
| - | OperationalError | データベース接続失敗 | データベースサーバーの起動確認 |
| - | DiskQuotaExceeded | ディスク容量不足 | ディスク容量を確保 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（自動リトライなし） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

1. ファイル書き込み失敗：出力先のディスク容量と権限を確認
2. データベース接続失敗：データベースサーバーの状態を確認
3. 処理中断：一時ファイル（*.tmp）が残っている場合は手動で削除

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし（読み取りのみ） |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | データベースのレコード総数に依存 |
| 目標処理時間 | データ量に依存（通常数秒〜数分） |
| メモリ使用量上限 | データサイズに依存 |

## 排他制御

- 同時実行は可能（読み取りのみのため）
- ただし、エクスポート中のデータ整合性は保証されない
- 整合性が必要な場合は、メンテナンス時間帯に実行することを推奨

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | バッチ開始時 | "Exporting database records to file '{filename}'" |
| 進捗ログ | 後処理時 | "Running data post-processing step..." |
| 進捗ログ | クリーンアップ時 | "Removing temporary files" |
| 終了ログ | バッチ終了時 | "Data export completed" |
| エラーログ | エラー発生時 | エラー詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 実行時間 | 環境依存 | システム管理者 |
| 出力ファイルサイズ | 環境依存 | システム管理者 |

## 備考

- dumpdataコマンドに`--natural-foreign`オプションを使用し、外部キーを自然キーでエクスポート
- dumpdataコマンドに`--indent 2`オプションを使用し、可読性の高いJSON形式で出力
- 一時設定（キーが`_`で始まる設定）はエクスポートから除外される
- `include_permissions=False`（デフォルト）の場合、auth.groupとauth.userのpermissionsフィールドは空配列に置換される
- 一時ファイルは`{filename}.tmp`という名前で作成される
- 履歴的な理由から、デフォルト実行では2つのファイル（data.jsonとdata.json.tmp）が生成される場合がある
