# 機能設計書: レポート・ラベル印刷

## 1. 機能概要

### 1.1 機能の目的
レポート・ラベル印刷機能は、InvenTreeシステムで管理されるデータを帳票やラベルとして出力するための機能である。テンプレートエンジン（Jinja2）を使用してHTML/CSSテンプレートを処理し、PDF形式のレポートまたはラベル印刷プラグインを通じた印刷出力を提供する。

### 1.2 機能の範囲
- レポート（帳票）の印刷・PDF出力
- ラベルの印刷（プラグイン経由）
- バックグラウンドタスクによる非同期印刷処理
- 印刷進捗のトラッキング
- 印刷出力の管理（DataOutput）

### 1.3 関連画面
| 画面ID | 画面名 | 関連操作 |
|--------|--------|----------|
| SCR-PART-DETAIL | 部品詳細 | ラベル印刷 |
| SCR-STOCK-DETAIL | 在庫詳細 | ラベル・レポート印刷 |
| SCR-BUILD-DETAIL | 製造オーダー詳細 | レポート印刷 |
| SCR-ORDER-DETAIL | 注文詳細 | 帳票印刷 |

## 2. 機能仕様

### 2.1 レポート印刷

#### 2.1.1 エンドポイント
- **URL**: `POST /api/report/print/`
- **メソッド**: POST
- **シリアライザ**: `ReportPrintSerializer`
- **権限**: 認証済みユーザー

#### 2.1.2 入力パラメータ
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| template | Integer | Yes | レポートテンプレートID |
| items | Array[Integer] | Yes | 印刷対象アイテムIDのリスト |

#### 2.1.3 処理フロー
1. テンプレートとアイテムのバリデーション
2. DataOutputオブジェクトの作成（進捗トラッキング用）
3. バックグラウンドタスクへのオフロード
4. DataOutput情報を即座にレスポンスとして返却
5. バックグラウンドでPDF生成・保存

#### 2.1.4 レスポンス
```json
{
  "pk": 1,
  "output_type": "report",
  "template_name": "Build Order Report",
  "complete": false,
  "progress": 0,
  "total": 3,
  "output": null
}
```

### 2.2 ラベル印刷

#### 2.2.1 エンドポイント
- **URL**: `POST /api/label/print/`
- **メソッド**: POST
- **シリアライザ**: `LabelPrintSerializer`
- **権限**: 認証済みユーザー

#### 2.2.2 入力パラメータ
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| template | Integer | Yes | ラベルテンプレートID |
| items | Array[Integer] | Yes | 印刷対象アイテムIDのリスト |
| plugin | String | No | 使用する印刷プラグイン（デフォルト: InvenTreeLabelPlugin） |
| [plugin_options] | Object | No | プラグイン固有のオプション |

#### 2.2.3 ラベルサイズバリデーション
- テンプレートのwidth > 0 かつ height > 0 であること
- 無効なサイズの場合はエラー

#### 2.2.4 処理フロー
1. テンプレートとアイテムのバリデーション
2. ラベルサイズのバリデーション
3. 印刷プラグインの解決
4. DataOutputオブジェクトの作成
5. バックグラウンドタスクへのオフロード
6. DataOutput情報を即座にレスポンスとして返却

### 2.3 印刷プラグイン

#### 2.3.1 デフォルトプラグイン
- **InvenTreeLabelPlugin**: 組み込みのラベル印刷プラグイン
- PDF出力をサポート

#### 2.3.2 プラグインの取得
```python
# プラグインの解決
plugin = registry.get_plugin(plugin_slug, active=True)

# ラベル印刷機能のチェック
if not plugin.mixin_enabled(PluginMixinEnum.LABELS):
    raise ValidationError('Plugin does not support label printing')
```

#### 2.3.3 カスタムプラグインオプション
各プラグインは独自のオプションシリアライザを提供可能：
```python
plugin.get_printing_options_serializer(request, data, context)
```

### 2.4 DataOutput（印刷出力管理）

#### 2.4.1 データ項目
| フィールド名 | 型 | 説明 |
|-------------|------|------|
| user | ForeignKey | 実行ユーザー |
| output_type | String | 出力タイプ（report/label） |
| template_name | String | テンプレート名 |
| complete | Boolean | 完了フラグ |
| progress | Integer | 進捗（処理済みアイテム数） |
| total | Integer | 総アイテム数 |
| output | FileField | 出力ファイル |
| plugin | String | 使用プラグイン（ラベルのみ） |

## 3. データモデル

### 3.1 処理フロー図
```
[印刷リクエスト]
    │
    ▼
┌─────────────────────────────────────┐
│ API Endpoint (ReportPrint/LabelPrint)│
│ ・シリアライザでバリデーション     │
│ ・テンプレート・アイテム取得       │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│ DataOutput 作成                     │
│ ・output_type: report/label        │
│ ・complete: False                  │
│ ・progress: 0                      │
└─────────────────────────────────────┘
    │
    ├───────────────────────────────┐
    │                               │
    ▼                               ▼
[即座にレスポンス]           [バックグラウンドタスク]
    │                               │
    │                               ├── アイテムごとに処理
    │                               ├── 進捗更新
    │                               └── 完了後にファイル保存
    │
    ▼
┌─────────────────────────────────────┐
│ クライアント                        │
│ ・DataOutput.pk でポーリング       │
│ ・complete=True で出力取得         │
└─────────────────────────────────────┘
```

## 4. API仕様

### 4.1 レポート印刷
```
POST /api/report/print/
Content-Type: application/json

{
  "template": 1,
  "items": [1, 2, 3]
}
```

### 4.2 ラベル印刷（デフォルトプラグイン）
```
POST /api/label/print/
Content-Type: application/json

{
  "template": 1,
  "items": [1, 2, 3]
}
```

### 4.3 ラベル印刷（プラグイン指定）
```
POST /api/label/print/
Content-Type: application/json

{
  "template": 1,
  "items": [1, 2, 3],
  "plugin": "custom_label_plugin",
  "copies": 2
}
```

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

### 5.1 推奨読解順序

1. **レポート印刷API**
   - `src/backend/InvenTree/report/api.py`
     - **245-300行目**: `ReportPrint` - レポート印刷エンドポイント
     - **252-269行目**: `post()` - POSTハンドラ
     - **271-300行目**: `print()` - 印刷実行メソッド

2. **ラベル印刷API**
   - `src/backend/InvenTree/report/api.py`
     - **95-224行目**: `LabelPrint` - ラベル印刷エンドポイント
     - **102-125行目**: `get_plugin_class()` - プラグイン解決
     - **157-185行目**: `post()` - POSTハンドラ
     - **187-224行目**: `print()` - 印刷実行メソッド

3. **バックグラウンドタスク**
   - `src/backend/InvenTree/report/tasks.py`
     - `print_reports()` - レポート印刷タスク
     - `print_labels()` - ラベル印刷タスク

4. **DataOutputモデル**
   - `src/backend/InvenTree/common/models.py`
     - `DataOutput` - 印刷出力管理モデル

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

```
[POST /api/label/print/]
    │
    ▼
LabelPrint.post() [157-185行目]
    │
    ├── get_serializer() [138-154行目]
    │   └── get_plugin_class() [102-125行目]
    │       └── プラグイン解決
    │
    ├── serializer.is_valid()
    │   └── テンプレート・アイテムバリデーション
    │
    ├── ラベルサイズチェック [163-165行目]
    │
    └── print() [187-224行目]
        │
        ├── DataOutput.objects.create() [199-209行目]
        │
        └── offload_task(print_labels, ...) [213-220行目]
            │
            ▼
        [バックグラウンド実行]
        print_labels()
            │
            ├── テンプレートレンダリング
            ├── プラグインによる印刷処理
            └── DataOutput更新（progress, complete, output）
```

### 5.3 関連ファイル一覧

| ファイルパス | 種別 | 役割 |
|-------------|------|------|
| `src/backend/InvenTree/report/api.py` | API | 印刷APIエンドポイント定義 |
| `src/backend/InvenTree/report/serializers.py` | Serializer | 印刷シリアライザ定義 |
| `src/backend/InvenTree/report/tasks.py` | Task | バックグラウンド印刷タスク |
| `src/backend/InvenTree/common/models.py` | Model | DataOutputモデル定義 |
| `src/backend/InvenTree/common/serializers.py` | Serializer | DataOutputSerializer定義 |
| `src/backend/InvenTree/plugin/builtin/labels/` | Plugin | 組み込みラベル印刷プラグイン |

## 6. 例外処理

### 6.1 バリデーションエラー
| エラー条件 | エラーメッセージ |
|-----------|-----------------|
| templateが未指定 | "This field is required" |
| itemsが空 | "No valid items provided to template" |
| 無効なラベルサイズ | "Invalid label dimensions" |
| プラグイン未検出 | "Plugin not found" |
| プラグインが非対応 | "Plugin does not support label printing" |

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

- APIアクセスには認証が必要
- テンプレートの実行はサーバーサイドで行われる
- 印刷出力はユーザーに紐づいて管理される
- バックグラウンドタスクは権限を引き継いで実行
