# 機能設計書: ラベルテンプレート管理

## 1. 機能概要

### 1.1 機能の目的
ラベルテンプレート管理機能は、InvenTreeシステムで使用するラベル（バーコードラベル、在庫ラベル等）のテンプレートを管理するための機能である。ラベルテンプレートはJinja2ベースのHTML/CSSテンプレートとして定義され、各種ラベル印刷に使用される。

### 1.2 機能の範囲
- ラベルテンプレートの登録・更新・削除・参照
- テンプレートの有効/無効状態の管理
- モデルタイプ（適用対象）の管理
- ラベルサイズ（幅・高さ）の設定
- テンプレートファイルのアップロード

### 1.3 関連画面
| 画面ID | 画面名 | 関連操作 |
|--------|--------|----------|
| SCR-LABEL-TEMPLATE-LIST | ラベルテンプレート一覧 | テンプレートの検索・編集 |
| SCR-ADMIN | 管理画面 | テンプレート管理 |

## 2. 機能仕様

### 2.1 ラベルテンプレートのデータ項目

| フィールド名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| name | String | Yes | テンプレート名 |
| description | String | No | 説明 |
| template | FileField | Yes | テンプレートファイル（HTML） |
| model_type | String | Yes | 適用対象モデル（part, stockitem, stocklocation等） |
| enabled | Boolean | No | 有効フラグ（デフォルト: true） |
| width | Float | Yes | ラベル幅（mm） |
| height | Float | Yes | ラベル高さ（mm） |
| filters | String | No | 適用フィルタ（JSON） |

### 2.2 ラベルテンプレート一覧API

#### 2.2.1 エンドポイント
- **URL**: `GET /api/label/template/`
- **メソッド**: GET（一覧取得）, POST（新規作成）
- **シリアライザ**: `LabelTemplateSerializer`
- **権限**: スタッフ権限（読み取りは認証ユーザー可）

#### 2.2.2 フィルタパラメータ
| パラメータ名 | 型 | 説明 |
|-------------|------|------|
| enabled | Boolean | 有効/無効 |
| model_type | String | モデルタイプ |
| items | String | 適用対象アイテムID（カンマ区切り） |

#### 2.2.3 検索フィールド
- name
- description

#### 2.2.4 ソートフィールド
- name
- enabled

### 2.3 ラベルテンプレート詳細API

#### 2.3.1 エンドポイント
- **URL**: `GET/PUT/PATCH/DELETE /api/label/template/{pk}/`
- **権限**: スタッフ権限（読み取りは認証ユーザー可）

## 3. データモデル

### 3.1 LabelTemplateモデル
```python
class LabelTemplate(TemplateUploadMixin, InvenTree.models.InvenTreeMetadataModel):
    name = models.CharField(max_length=100, ...)
    description = models.CharField(max_length=250, blank=True)
    template = models.FileField(...)
    model_type = models.CharField(max_length=100, ...)
    enabled = models.BooleanField(default=True)
    width = models.FloatField(default=50, ...)
    height = models.FloatField(default=20, ...)
    filters = models.CharField(max_length=250, blank=True)
```

### 3.2 レポートテンプレートとの違い
| 項目 | LabelTemplate | ReportTemplate |
|------|---------------|----------------|
| サイズ指定 | width/height（mm） | page_size, landscape |
| 用途 | 小型ラベル印刷 | 帳票・レポート印刷 |
| 印刷プラグイン | ラベル印刷プラグイン使用 | PDF出力 |

## 4. API仕様

### 4.1 テンプレート一覧取得
```
GET /api/label/template/
```

### 4.2 有効なテンプレートのみ
```
GET /api/label/template/?enabled=true
```

### 4.3 モデルタイプでフィルタリング
```
GET /api/label/template/?model_type=stockitem
```

### 4.4 アイテムに適用可能なテンプレート
```
GET /api/label/template/?model_type=stockitem&items=1,2,3
```

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

### 5.1 推奨読解順序

1. **モデル定義**
   - `src/backend/InvenTree/report/models.py`
     - **LabelTemplate**: ラベルテンプレートモデル

2. **フィルタ定義**
   - `src/backend/InvenTree/report/api.py`
     - **35-73行目**: `ReportFilterBase` - ベースフィルタ（レポートと共通）
     - **85-92行目**: `LabelFilter` - ラベル用フィルタ

3. **APIエンドポイント**
   - `src/backend/InvenTree/report/api.py`
     - **227-235行目**: `LabelTemplateList` - 一覧API
     - **238-242行目**: `LabelTemplateDetail` - 詳細API

4. **URLルーティング**
   - `src/backend/InvenTree/report/api.py`
     - **349-370行目**: `label_api_urls` - URLルーティング

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

```
[API Request: GET /api/label/template/]
    │
    ▼
LabelTemplateList.get()
    │
    ├── queryset = LabelTemplate.objects.all() [230行目]
    │
    ├── LabelFilter [85-92行目]
    │   ├── enabled フィルタ
    │   ├── model_type フィルタ
    │   └── items フィルタ（ReportFilterBaseから継承）
    │
    └── LabelTemplateSerializer.to_representation()
        └── レスポンス生成
```

### 5.3 データフロー図

```
[ラベルテンプレート登録]
    │
    ▼
┌─────────────────────────────────────┐
│ LabelTemplateSerializer             │
│ ・name: テンプレート名             │
│ ・template: テンプレートファイル   │
│ ・model_type: 適用対象             │
│ ・width/height: ラベルサイズ       │
└─────────────────────────────────────┘
    │
    ├── バリデーション
    │   ├── 必須項目チェック
    │   └── サイズ値チェック（正の値）
    │
    ▼
┌─────────────────────────────────────┐
│ LabelTemplate Model                 │
│ ・データベースへの永続化           │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│ ラベル印刷で使用                    │
│ ・LabelPrint APIで参照             │
│ ・プラグインによる印刷実行         │
└─────────────────────────────────────┘
```

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

| ファイルパス | 種別 | 役割 |
|-------------|------|------|
| `src/backend/InvenTree/report/models.py` | Model | LabelTemplateモデル定義 |
| `src/backend/InvenTree/report/serializers.py` | Serializer | LabelTemplateSerializer定義 |
| `src/backend/InvenTree/report/api.py` | API | RESTful APIエンドポイント定義 |
| `src/backend/InvenTree/plugin/builtin/labels/` | Plugin | 組み込みラベル印刷プラグイン |

## 6. 例外処理

### 6.1 バリデーションエラー
| エラー条件 | エラーメッセージ |
|-----------|-----------------|
| nameが未指定 | "This field is required" |
| templateが未指定 | "This field is required" |
| model_typeが未指定 | "This field is required" |
| widthが0以下 | "Ensure this value is greater than 0" |
| heightが0以下 | "Ensure this value is greater than 0" |
| 無効なmodel_type | "Invalid model type" |

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

- テンプレートの作成・編集・削除にはスタッフ権限が必要
- テンプレートの参照は認証済みユーザーに許可
- テンプレートファイルはサーバー上で実行されるため、信頼できるユーザーのみがアップロード可能
