# 機能設計書: レポートテンプレート管理

## 1. 機能概要

### 1.1 機能の目的
レポートテンプレート管理機能は、InvenTreeシステムで使用するレポート（帳票）のテンプレートを管理するための機能である。レポートテンプレートはJinja2ベースのHTML/CSSテンプレートとして定義され、注文書、納品書、部品リスト等の各種帳票出力に使用される。

### 1.2 機能の範囲
- レポートテンプレートの登録・更新・削除・参照
- テンプレートの有効/無効状態の管理
- モデルタイプ（適用対象）の管理
- テンプレートファイルのアップロード
- レポートアセット（画像等）の管理
- レポートスニペット（再利用可能なコード断片）の管理

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

## 2. 機能仕様

### 2.1 レポートテンプレートのデータ項目

| フィールド名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| name | String | Yes | テンプレート名 |
| description | String | No | 説明 |
| template | FileField | Yes | テンプレートファイル（HTML） |
| model_type | String | Yes | 適用対象モデル（build, part, stockitem等） |
| enabled | Boolean | No | 有効フラグ（デフォルト: true） |
| revision | Integer | No | リビジョン番号 |
| landscape | Boolean | No | 横向き印刷フラグ |
| page_size | String | No | 用紙サイズ（A4, Letter等） |
| filters | String | No | 適用フィルタ（JSON） |

### 2.2 レポートテンプレート一覧API

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

#### 2.2.2 フィルタパラメータ
| パラメータ名 | 型 | 説明 |
|-------------|------|------|
| enabled | Boolean | 有効/無効 |
| model_type | String | モデルタイプ |
| landscape | Boolean | 横向きフラグ |
| 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/report/template/{pk}/`
- **権限**: スタッフ権限（読み取りは認証ユーザー可）

### 2.4 レポートアセット管理

#### 2.4.1 データ項目
| フィールド名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| asset | FileField | Yes | アセットファイル（画像等） |
| description | String | No | 説明 |

#### 2.4.2 API
- **一覧**: `GET /api/report/asset/`
- **詳細**: `GET /api/report/asset/{pk}/`

### 2.5 レポートスニペット管理

#### 2.5.1 データ項目
| フィールド名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| snippet | FileField | Yes | スニペットファイル（HTML断片） |
| description | String | No | 説明 |

#### 2.5.2 API
- **一覧**: `GET /api/report/snippet/`
- **詳細**: `GET /api/report/snippet/{pk}/`

## 3. データモデル

### 3.1 ReportTemplateモデル
```python
class ReportTemplate(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)
    revision = models.PositiveIntegerField(default=1)
    landscape = models.BooleanField(default=False)
    page_size = models.CharField(max_length=20, default='A4')
    filters = models.CharField(max_length=250, blank=True)
```

### 3.2 ReportAssetモデル
```python
class ReportAsset(InvenTree.models.InvenTreeModel):
    asset = models.FileField(...)
    description = models.CharField(max_length=250, blank=True)
```

### 3.3 ReportSnippetモデル
```python
class ReportSnippet(InvenTree.models.InvenTreeModel):
    snippet = models.FileField(...)
    description = models.CharField(max_length=250, blank=True)
```

## 4. API仕様

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

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

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

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

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

### 5.1 推奨読解順序

1. **モデル定義**
   - `src/backend/InvenTree/report/models.py`
     - **ReportTemplate**: レポートテンプレートモデル
     - **ReportAsset**: アセットモデル
     - **ReportSnippet**: スニペットモデル

2. **フィルタ定義**
   - `src/backend/InvenTree/report/api.py`
     - **35-73行目**: `ReportFilterBase` - ベースフィルタ
     - **75-82行目**: `ReportFilter` - レポート用フィルタ

3. **APIエンドポイント**
   - `src/backend/InvenTree/report/api.py`
     - **303-311行目**: `ReportTemplateList` - 一覧API
     - **314-318行目**: `ReportTemplateDetail` - 詳細API
     - **335-339行目**: `ReportAssetList` - アセット一覧
     - **342-346行目**: `ReportAssetDetail` - アセット詳細
     - **321-325行目**: `ReportSnippetList` - スニペット一覧
     - **328-332行目**: `ReportSnippetDetail` - スニペット詳細

4. **URLルーティング**
   - `src/backend/InvenTree/report/api.py`
     - **372-415行目**: `report_api_urls` - URLルーティング

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

```
[API Request: GET /api/report/template/]
    │
    ▼
ReportTemplateList.get()
    │
    ├── queryset = ReportTemplate.objects.all() [306行目]
    │
    ├── ReportFilter [75-82行目]
    │   ├── enabled フィルタ
    │   ├── model_type フィルタ
    │   └── items フィルタ（46-72行目）
    │
    └── ReportTemplateSerializer.to_representation()
        └── レスポンス生成
```

### 5.3 アイテムフィルタの動作

```
[items フィルタ処理]
    │
    ▼
filter_items() [46-72行目]
    │
    ├── model_type から対象モデルクラスを取得
    │
    ├── items パラメータをカンマで分割
    │
    ├── 各テンプレートのフィルタ条件を評価
    │   └── template.get_filters() でフィルタ取得
    │
    └── すべてのアイテムにマッチするテンプレートを返却
```

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

| ファイルパス | 種別 | 役割 |
|-------------|------|------|
| `src/backend/InvenTree/report/models.py` | Model | ReportTemplate, ReportAsset, ReportSnippetモデル定義 |
| `src/backend/InvenTree/report/serializers.py` | Serializer | テンプレートシリアライザ定義 |
| `src/backend/InvenTree/report/api.py` | API | RESTful APIエンドポイント定義 |
| `src/backend/InvenTree/report/helpers.py` | Helper | モデルタイプ解決等のヘルパー関数 |

## 6. 例外処理

### 6.1 バリデーションエラー
| エラー条件 | エラーメッセージ |
|-----------|-----------------|
| nameが未指定 | "This field is required" |
| templateが未指定 | "This field is required" |
| model_typeが未指定 | "This field is required" |
| 無効なmodel_type | "Invalid model type" |

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

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