# 機能設計書 40-データエクスポート

## 概要

本ドキュメントは、InvenTreeシステムにおけるデータエクスポート機能の設計を定義する。InvenTreeデータベースから外部ファイル（CSV、Excel等）へのデータ出力を行う機能を提供する。

### 本機能の処理概要

データエクスポート機能は、InvenTreeシステムに保存されている部品、在庫、オーダー情報などを外部ファイルとしてエクスポートする。DataExportViewMixinとDataExportSerializerMixinを通じて、APIエンドポイントにエクスポート機能を追加し、プラグインによる拡張も可能とする。

**業務上の目的・背景**：在庫データや部品リストを外部システムに連携したり、帳票出力やレポート作成のためにデータを抽出したりする必要がある。CSV/Excel形式でエクスポートすることで、他のシステムやExcelでの分析が容易になる。

**機能の利用シーン**：
- 部品マスタの外部システムへの連携
- 在庫一覧のExcelエクスポート
- 発注データの会計システム連携
- 定期レポート用データ出力
- バックアップ目的でのデータ抽出

**主要な処理内容**：
1. エクスポートリクエストの受付
2. エクスポート対象データのクエリセット取得
3. シリアライザによるデータ変換
4. プラグインによるデータ加工（オプション）
5. ファイル形式への変換（CSV/Excel/JSON等）
6. ファイルダウンロード提供

**関連システム・外部連携**：
- tablibライブラリ（CSV/Excel出力）
- プラグインシステム（ExporterMixin）
- Django-Qバックグラウンドタスク

**権限による制御**：エクスポート対象モデルへの閲覧権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 11 | 部品一覧画面 | 主画面 | 部品データのエクスポート |
| 17 | 在庫アイテム一覧画面 | 主画面 | 在庫データのエクスポート |
| 18 | 発注一覧画面 | 主画面 | 発注データのエクスポート |
| 20 | 受注一覧画面 | 主画面 | 受注データのエクスポート |

## 機能種別

バッチ処理 / データ出力

## 入力仕様

### エクスポート入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| export | bool | Yes | エクスポートモード有効化 | true |
| export_format | str | No | 出力形式（csv/xlsx/json等） | サポートされた形式 |
| export_plugin | str | No | 使用するエクスポートプラグイン | 有効なプラグインスラッグ |
| export_* | any | No | プラグイン固有のオプション | プラグイン定義による |

### 入力データソース

- 一覧画面からのエクスポートボタン
- REST API経由のGETリクエスト（export=true）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| output | file | エクスポートされたファイル |
| filename | str | ファイル名 |
| total | int | エクスポートされたレコード数 |
| progress | int | 進捗率 |
| complete | bool | 完了フラグ |

### 出力先

- ファイルダウンロード（ブラウザ）
- DataOutputモデル（ダウンロードリンク）

## 処理フロー

### 処理シーケンス

```
1. エクスポートリクエスト受信
   └─ export=trueパラメータ確認
2. エクスポートオプション検証
   └─ DataExportOptionsSerializer
3. DataOutput作成
   └─ エクスポート結果の保存先
4. バックグラウンドタスク起動
   └─ export_dataタスクをオフロード
5. データ取得
   └─ filter_queryset()で対象データ取得
6. データシリアライズ
   └─ プラグインによる加工（オプション）
7. ファイル生成
   └─ export_to_file()でファイル変換
8. 完了通知
   └─ DataOutput.mark_complete()
```

### フローチャート

```mermaid
flowchart TD
    A[エクスポートリクエスト] --> B{export=true?}
    B -->|No| C[通常のGETレスポンス]
    B -->|Yes| D[エクスポートオプション検証]
    D --> E[DataOutput作成]
    E --> F[バックグラウンドタスク起動]
    F --> G[クエリセット取得]
    G --> H{プラグイン指定?}
    H -->|Yes| I[プラグインでデータ加工]
    H -->|No| J[シリアライザでデータ変換]
    I --> J
    J --> K[ファイル形式変換]
    K --> L[DataOutput完了]
    L --> M[ダウンロードリンク返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-40-01 | 権限チェック | エクスポート対象モデルへの閲覧権限が必要 | エクスポート実行時 |
| BR-40-02 | 形式サポート | CSV, TSV, XLS, XLSX, JSON形式をサポート | ファイル出力時 |
| BR-40-03 | プラグイン拡張 | ExporterMixinプラグインでカスタマイズ可能 | プラグイン指定時 |
| BR-40-04 | バックグラウンド処理 | 大量データはバックグラウンドで処理 | エクスポート実行時 |
| BR-40-05 | フィルタ適用 | 一覧画面のフィルタがエクスポートにも適用 | エクスポート実行時 |

### 計算ロジック

エクスポート進捗率:
```python
progress = exported_count / total_count * 100
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| DataOutput作成 | common_dataoutput | INSERT | エクスポート結果の保存先作成 |
| DataOutput更新 | common_dataoutput | UPDATE | 進捗・完了状態更新 |
| データ取得 | エクスポート対象テーブル | SELECT | エクスポートデータ取得 |

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

#### common_dataoutput

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | user_id, output_type, plugin, total | 初期値 | output_type=EXPORT |
| UPDATE | progress, complete, output | 処理結果 | |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 400 | ValidationError | 無効なエクスポート形式 | サポートされた形式を指定 |
| 403 | PermissionDenied | 閲覧権限なし | 必要な権限を付与 |
| 500 | ExportError | エクスポート処理失敗 | エラーログを確認 |

### リトライ仕様

- バックグラウンドタスクのエラーはDataOutputに記録
- 手動でのリトライが必要

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

- エクスポートは読み取り専用処理
- DataOutputの更新は個別トランザクション

## パフォーマンス要件

- エクスポート開始：即座にレスポンス返却（バックグラウンド処理）
- 進捗更新：リアルタイム
- ファイルサイズ：メモリ効率を考慮した処理

## セキュリティ考慮事項

- エクスポート対象モデルへの閲覧権限チェック
- 機密データのエクスポート制限（設定による）
- ダウンロードリンクのユーザー認証

## 備考

DataExportViewMixinの主要メソッド:
- is_exporting(): エクスポートモードかどうか判定
- get_plugin(): エクスポートプラグインを取得
- export_data(): エクスポート処理の実行

DataExportSerializerMixinの主要属性:
- export_only_fields: エクスポート時のみ含めるフィールド
- export_exclude_fields: エクスポート時に除外するフィールド
- export_child_fields: 子フィールドのエクスポート定義

サポートされるファイル形式:
- CSV (.csv)
- TSV (.tsv)
- Excel (.xls, .xlsx)
- JSON (.json)

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

エクスポート機能のミックスインを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | mixins.py | `src/backend/InvenTree/data_exporter/mixins.py` | DataExportSerializerMixin（27-211行目）の構造 |
| 1-2 | mixins.py | `src/backend/InvenTree/data_exporter/mixins.py` | DataExportViewMixin（213-490行目）のAPI拡張 |

**読解のコツ**:
- **27-40行目**: DataExportSerializerMixinの属性定義（export_only_fields等）
- **42-71行目**: __init__でエクスポートモードによるフィールド調整
- **72-104行目**: get_exportable_fields()でエクスポート可能フィールド取得
- **158-188行目**: generate_headers()でヘッダー生成
- **189-210行目**: export_to_file()でファイル出力

#### Step 2: エントリーポイントを理解する

APIビューのエクスポート拡張を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | mixins.py | `src/backend/InvenTree/data_exporter/mixins.py` | DataExportViewMixin.get()（417-489行目） |
| 2-2 | mixins.py | `src/backend/InvenTree/data_exporter/mixins.py` | export_data()（297-416行目） |

**主要処理フロー**:
- **225-233行目**: is_exporting()でエクスポートモード判定
- **234-254行目**: get_plugin()でプラグイン取得
- **255-296行目**: get_serializer()でエクスポート用シリアライザ取得
- **417-489行目**: get()でエクスポートリクエスト処理

#### Step 3: バックグラウンド処理を理解する

エクスポートタスクの処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | tasks.py | `src/backend/InvenTree/data_exporter/tasks.py` | export_dataタスク |

#### Step 4: プラグイン拡張を理解する

エクスポートプラグインの仕組みを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | 該当プラグイン | プラグインディレクトリ | ExporterMixinの実装例 |

### プログラム呼び出し階層図

```
DataExportViewMixin.get(request)
    │
    ├─ is_exporting()
    │      └─ export=trueチェック
    │
    ├─ get_serializer(exporting=True)
    │      └─ DataExportOptionsSerializer
    │
    ├─ serializer.is_valid()
    │
    ├─ get_plugin(plugin_slug)
    │      └─ registry.get_plugin()
    │
    ├─ DataOutput.objects.create()
    │
    └─ offload_task(export_data)
           │
           └─ export_data_task
                  │
                  ├─ view.export_data()
                  │      ├─ filter_queryset()
                  │      ├─ plugin.filter_queryset()
                  │      ├─ plugin.export_data()
                  │      ├─ serializer.generate_headers()
                  │      ├─ plugin.update_headers()
                  │      └─ serializer.export_to_file()
                  │
                  └─ output.mark_complete()
```

### データフロー図

```
[入力]                    [処理]                           [出力]

GETリクエスト ───▶ is_exporting() ───▶ エクスポートモード
  + export=true                             │
  + export_format                           ▼
  + export_plugin            DataExportOptionsSerializer
                                            │
                                            ▼
                             DataOutput作成 ───▶ DB保存
                                            │
                                            ▼
                            バックグラウンドタスク起動
                                            │
                                            ▼
                             filter_queryset() ───▶ データ取得
                                            │
                                            ▼
                             プラグイン処理（オプション）
                                            │
                                            ▼
                             export_to_file() ───▶ ファイル生成
                                            │
                                            ▼
                             mark_complete() ───▶ ダウンロードリンク
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| mixins.py | `src/backend/InvenTree/data_exporter/mixins.py` | ソース | エクスポートミックスイン |
| serializers.py | `src/backend/InvenTree/data_exporter/serializers.py` | ソース | エクスポートシリアライザ |
| tasks.py | `src/backend/InvenTree/data_exporter/tasks.py` | ソース | バックグラウンドタスク |
| models.py | `src/backend/InvenTree/common/models.py` | ソース | DataOutputモデル |
