# 帳票設計書 10-Stock Item QR Label

## 概要

本ドキュメントは、InvenTreeシステムにおける在庫品目QRラベルの設計仕様を記載する。このラベルは在庫品目のQRコードを含むラベルをPDF形式で出力する帳票である。

### 本帳票の処理概要

本帳票は、在庫品目を識別するためのQRコードラベルを生成する。スキャンすることで在庫品目の詳細情報にアクセスできるQRコードを印刷可能なラベル形式で出力する。

**業務上の目的・背景**：在庫管理において、物品の迅速な識別と追跡は効率的な運用の基盤である。QRコードラベルを在庫品目に貼付することで、スマートフォンやハンディターミナルでスキャンするだけで詳細情報にアクセスでき、棚卸作業や入出庫作業の効率化を実現する。

**帳票の利用シーン**：在庫品目の受入時のラベル貼付、棚卸時のスキャン用ラベル、在庫移動時の識別、出荷品への識別ラベル貼付として利用される。

**主要な出力内容**：
1. QRコード（在庫品目データをエンコード）

**帳票の出力タイミング**：在庫品目詳細画面から、または在庫品目一覧で複数選択後にラベル印刷操作で出力される。

**帳票の利用者**：倉庫管理者、在庫管理担当者、出荷担当者、受入担当者

## 帳票種別

ラベル

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | 在庫品目詳細画面 | /stock/item/{stock_id}/ | ラベル印刷ボタン |
| - | 在庫品目一覧画面 | /stock/ | 複数選択後ラベル印刷 |
| - | ラベル印刷API | /api/label/print/ | POSTリクエスト |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | PDF |
| 用紙サイズ | カスタム（ラベルテンプレートで定義） |
| 向き | ラベルテンプレートに依存 |
| ファイル名 | output.pdf（テンプレート設定により変更可能） |
| 出力方法 | ダウンロード / ラベルプリンタ出力 |
| 文字コード | UTF-8 |

### ラベル固有設定

| 項目 | 内容 |
|-----|------|
| デフォルト幅 | 50mm（LabelTemplate設定） |
| デフォルト高さ | 20mm（LabelTemplate設定） |
| マージン | 0mm |

## 帳票レイアウト

### レイアウト概要

QRコードのみを表示するシンプルなラベル。

```
┌─────────────────────────────────────┐
│                                     │
│         ┌─────────────┐            │
│         │             │            │
│         │   QR CODE   │            │
│         │             │            │
│         └─────────────┘            │
│                                     │
└─────────────────────────────────────┘
```

### ラベル内容

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | QRコード | 在庫品目データ | qr_data | 画像（正方形、高さ=ラベル高さ） |

### QRコードの位置とサイズ

| 項目 | 値 |
|-----|-----|
| 配置 | 左上絶対位置 (0mm, 0mm) |
| 幅 | ラベル高さと同じ（正方形） |
| 高さ | ラベル高さ（テンプレート設定値） |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| stock_id | 対象在庫品目のID | Yes |
| qr_data | QRコードにエンコードするデータ | - |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| - | - | 該当なし（単一ラベル） |

### 改ページ条件

1ラベル = 1ページ

## データベース参照仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| stock_stockitem | 在庫品目情報 | 直接参照 |
| report_labeltemplate | ラベルテンプレート | template_id |

### テーブル別参照項目詳細

#### stock_stockitem

| 参照項目（カラム名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| barcode | QRデータ | - | report_context()で生成 |

#### report_labeltemplate

| 参照項目（カラム名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| width | ラベル幅 | - | mm単位 |
| height | ラベル高さ | - | mm単位 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| QRコード幅 | height (正方形) | - | ラベル高さと同じ |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[出力要求] --> B[パラメータ検証]
    B --> C[StockItem取得]
    C --> D[LabelTemplate取得]
    D --> E[コンテキスト生成]
    E --> F[qr_data生成]
    F --> G[QRコード画像生成]
    G --> H[HTMLレンダリング]
    H --> I[WeasyPrintでPDF変換]
    I --> J[プラグイン処理]
    J --> K[DataOutput保存]
    K --> L[ファイル返却]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| データなし | 指定された在庫品目が存在しない | No valid items provided to template | 有効な在庫品目IDを指定 |
| ラベルサイズ不正 | 幅または高さが0以下 | Invalid label dimensions | 有効なテンプレートを選択 |
| プラグインエラー | プラグインが見つからない | Plugin not found | プラグイン設定を確認 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 1回あたり最大100ラベル |
| 目標出力時間 | 10秒以内（100ラベル） |
| 同時出力数上限 | システム設定による |

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

- 認証済みユーザーのみがラベルを出力可能
- 在庫品目データへのアクセス権限は既存の権限モデルに従う
- QRコードには在庫品目の識別情報のみを含む（機密情報は含まない）
- 出力ログはDataOutputモデルに記録

## 備考

- テンプレートファイル: `src/backend/InvenTree/report/templates/label/stockitem_qr.html`
- 基底テンプレート: `label_base.html`を継承（ラベル用）
- QRコード生成は`qrcode`テンプレートタグを使用
- ラベル印刷はLabelPrint APIを使用（ReportPrintとは別）
- プラグイン対応（InvenTreeLabelPlugin等）
- i18n対応済み（多言語対応）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | models.py | `src/backend/InvenTree/stock/models.py` | StockItemReportContext（349-396行目）でqr_data項目を確認 |
| 1-2 | models.py | `src/backend/InvenTree/report/models.py` | LabelTemplate（656-794行目）でラベルモデル定義を確認 |

**読解のコツ**: qr_dataはStockItemのbarcode属性から取得される。LabelTemplateはReportTemplateとは別のモデルで、width/heightを持つ。

#### Step 2: ラベル印刷APIを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | api.py | `src/backend/InvenTree/report/api.py` | LabelPrint（95-224行目）がラベル印刷のエントリーポイント |

**主要処理フロー**:
- **157-159行目**: POSTリクエスト受付、シリアライザでバリデーション
- **164-165行目**: テンプレートサイズ検証
- **186-224行目**: print()メソッドでバックグラウンドタスクへオフロード

#### Step 3: テンプレートを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | stockitem_qr.html | `src/backend/InvenTree/report/templates/label/` | ラベルテンプレート |

**主要処理フロー**:
- **1行目**: label_base.html継承
- **5-15行目**: スタイル定義（QRコード位置・サイズ）
- **19-21行目**: QRコード画像表示（qrcodeテンプレートタグ）

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

```
LabelPrint.post() [api.py:157]
    │
    ├─ get_serializer() → LabelPrintSerializer
    │
    ├─ template.get_model().objects.filter()
    │
    └─ print() [api.py:187]
           │
           ├─ DataOutput.objects.create() [api.py:200]
           │
           └─ offload_task(report.tasks.print_labels) [api.py:213]
                  │
                  └─ LabelTemplate.print() [report/models.py:730]
                         │
                         ├─ get_context() [report/models.py:704]
                         │      │
                         │      └─ stockitem.report_context()
                         │             └─ qr_data
                         │
                         ├─ plugin.print_labels()
                         │      │
                         │      └─ InvenTreeLabelPlugin or custom plugin
                         │
                         └─ → DataOutput with PDF
```

### データフロー図

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

Stock ID ─────────▶ StockItem.objects.get() ────────▶ StockItem インスタンス
                           │
                           ▼
                    stockitem.report_context()
                           │
                           └─▶ qr_data (barcode属性)
                           │
                           ▼
                    LabelTemplate.get_context()
                           │
                           ├─▶ width, height
                           └─▶ page_style (@page CSS)
                           │
                           ▼
                    {% qrcode qr_data %}
                           │
                           ▼
                    HTML → PDF (WeasyPrint/Plugin) ──▶ ラベル PDF
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| stockitem_qr.html | `src/backend/InvenTree/report/templates/label/` | テンプレート | 在庫品目QRラベルのHTMLテンプレート |
| label_base.html | `src/backend/InvenTree/report/templates/label/` | テンプレート | ラベル共通基底テンプレート |
| models.py | `src/backend/InvenTree/report/` | ソース | LabelTemplateモデル定義 |
| api.py | `src/backend/InvenTree/report/` | ソース | LabelPrint API定義 |
| models.py | `src/backend/InvenTree/stock/` | ソース | StockItemモデル定義 |
| inventree_label.py | `src/backend/InvenTree/plugin/builtin/labels/` | プラグイン | デフォルトラベル印刷プラグイン |
