# 帳票設計書 15-Build Line Label

## 概要

本ドキュメントは、InvenTreeシステムにおける製造ラインラベル（Build Line Label）の設計仕様を定義するものである。

### 本帳票の処理概要

本ラベルは、製造オーダー（Build Order）の構成部品ライン（Build Line）に対して、部品のピッキングや組立作業で使用するラベルを出力する機能を提供する。

**業務上の目的・背景**：製造業において、製造オーダーの遂行には正確な部品供給が不可欠である。本ラベルは、製造オーダーの各構成部品（BOM項目）に対して、必要な部品情報と数量を明示したラベルを提供する。これにより、ピッキング作業者は正しい部品を正しい数量で集め、製造ラインに供給することができる。QRコードによる製造オーダーと部品の識別、数量情報の明示により、部品の取り違えや数量ミスを防止し、製造品質と効率を向上させる。

**帳票の利用シーン**：製造オーダーの部品ピッキング準備時、部品キット作成時、製造ライン供給時、部品トレーサビリティ管理時などに利用される。各Build Lineに対してラベルを印刷し、部品容器やトレイに貼付して使用する。

**主要な出力内容**：
1. 製造オーダー情報（参照番号、製造数量）と製造オーダーQRコード
2. 部品情報（部品名、IPN、単位数量、合計数量）と部品QRコード

**帳票の出力タイミング**：製造オーダー詳細画面からBuild Line選択後、「ラベル印刷」操作を実行した際に出力される。複数のBuild Lineを選択して一括印刷することも可能。

**帳票の利用者**：製造管理者、生産計画担当者、ピッキング作業者、製造ライン作業者、品質管理担当者

## 帳票種別

ラベル

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| - | Build Order Detail | /manufacturing/build-order/{id} | Build Line選択後「Print Label」ボタン |
| - | Build Order Line Items | /manufacturing/build-order/{id}/line-items | 複数選択後「Print Labels」ボタン |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | PDF |
| 用紙サイズ | カスタム（テンプレート設定による、デフォルト想定は中〜大サイズ） |
| 向き | - |
| ファイル名 | output.pdf（デフォルト、テンプレート設定で変更可能） |
| 出力方法 | ダウンロード / プラグインによる直接印刷 |
| 文字コード | UTF-8 |

### PDF固有設定

| 項目 | 内容 |
|-----|------|
| パスワード保護 | 無 |
| 印刷制限 | 無 |
| 電子署名 | 無 |

## 帳票レイアウト

### レイアウト概要

テーブル形式のラベルで、上段に製造オーダー情報、下段に部品情報を表示。各行の右側にQRコードを配置。

```
┌─────────────────────────────────────────────────────┐
│  ┌───────────────────────────────────┬─────────┐   │
│  │ Build Order: BO-0001              │         │   │
│  │ Build Qty: 10                     │   QR    │   │
│  │                                   │ (Build) │   │
│  ├───────────────────────────────────┼─────────┤   │
│  │ Part: Resistor 10K Ohm 1%         │         │   │
│  │ IPN: R-10K-1PCT                   │   QR    │   │
│  │ Qty / Unit: 5                     │ (Part)  │   │
│  │ Qty Total: 50                     │         │   │
│  └───────────────────────────────────┴─────────┘   │
└─────────────────────────────────────────────────────┘
```

### 製造オーダー情報部（上段）

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | Build Order | 製造オーダーの参照番号 | Build.reference（build.reference） | テキスト「Build Order: {参照番号}」 |
| 2 | Build Qty | 製造オーダーの製造数量 | Build.quantity（build.quantity） | テキスト「Build Qty: {数量}」（decimal形式） |
| 3 | Build QR | 製造オーダーのQRコード | Build.barcode（build.barcode） | 画像（28mm x 28mm） |

### 部品情報部（下段）

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | Part | 部品名 | Part.name（part.name） | テキスト「Part: {部品名}」 |
| 2 | IPN | 内部品番（設定されている場合のみ表示） | Part.IPN（part.IPN） | テキスト「IPN: {IPN}」（条件付き） |
| 3 | Qty / Unit | BOM項目の単位数量 | BomItem.quantity（bom_item.quantity） | テキスト「Qty / Unit: {数量} [{単位}]」（decimal形式） |
| 4 | Qty Total | 製造オーダー全体での必要総数量 | BuildLine.quantity（quantity） | テキスト「Qty Total: {数量} [{単位}]」（decimal形式） |
| 5 | Part QR | 部品のQRコード | Part.barcode（part.barcode） | 画像（28mm x 28mm） |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| Build Line ID | 対象となるBuild LineのID | Yes |
| テンプレートフィルタ | LabelTemplateのfiltersフィールドで定義されたフィルタ条件 | No |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| - | 指定なし（選択順） | - |

### 改ページ条件

1ラベル1ページ。複数Build Line選択時は各ラベルが個別のページとして出力される。

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

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| build_buildline | Build Line情報の取得 | PRIMARY KEY (id) |
| build_build | 製造オーダー情報の取得 | FOREIGN KEY (build_id) |
| part_bomitem | BOM項目情報の取得 | FOREIGN KEY (bom_item_id) |
| part_part | 部品情報の取得 | BomItem.sub_part |

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

#### build_buildline

| 参照項目（カラム名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| id | 内部識別用 | WHERE id = {指定ID} | - |
| build_id | 製造オーダー参照 | - | Build取得用FK |
| bom_item_id | BOM項目参照 | - | BomItem取得用FK |
| quantity | 必要総数量 | - | 製造数量×BOM数量 |

#### build_build

| 参照項目（カラム名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| reference | Build Order番号 | - | - |
| quantity | 製造数量 | - | - |
| barcode_data | Build QRコードデータ | - | JSON形式 |

#### part_bomitem

| 参照項目（カラム名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| quantity | 単位数量 | - | - |
| sub_part_id | 部品参照 | - | Part取得用FK |

#### part_part

| 参照項目（カラム名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| name | 部品名 | - | - |
| IPN | 内部品番 | - | NULLの場合は非表示 |
| units | 単位 | - | 数量表示時に使用 |
| barcode_data | Part QRコードデータ | - | JSON形式 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| QRコードサイズ | 固定: 28mm x 28mm | - | テンプレートで定義 |
| Qty Total | build.quantity × bom_item.quantity | decimalテンプレートタグで正規化 | BuildLine.quantityとして事前計算済み |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[ラベル印刷要求] --> B[LabelPrint API呼び出し]
    B --> C[テンプレート・アイテム検証]
    C --> D[DataOutput生成]
    D --> E[バックグラウンドタスク起動]
    E --> F[各Build Lineに対してループ]
    F --> G[report_context取得]
    G --> H[関連データ取得]
    H --> I[テンプレートレンダリング]
    I --> J[QRコード生成（Build/Part）]
    J --> K[HTML→PDF変換]
    K --> L{全件処理完了?}
    L -->|No| F
    L -->|Yes| M[PDF結合]
    M --> N[DataOutput更新]
    N --> O[終了]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| データなし | 指定されたBuild Lineが存在しない | No valid items provided to template | 有効なBuild Line IDを指定 |
| テンプレートエラー | テンプレートファイルが存在しない | Template file {name} does not exist | テンプレートファイルを確認 |
| テンプレート構文エラー | テンプレートの構文が不正 | Template syntax error | テンプレートを修正 |
| プラグインエラー | 印刷プラグインが見つからない | Plugin not found | プラグイン設定を確認 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 1〜50件/回（1製造オーダーあたりのBOM項目数を想定） |
| 目標出力時間 | 10件あたり5秒以内 |
| 同時出力数上限 | システム設定による |

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

- ラベル印刷はログイン済みユーザーのみ実行可能（IsAuthenticatedOrReadScope）
- QRコードには製造オーダーと部品の内部識別子のみが含まれ、機密情報は含まれない
- 製造オーダー情報、部品情報は組織内部の情報であるため、適切なアクセス制御が必要
- テンプレートの作成・編集はスタッフ権限が必要（IsStaffOrReadOnlyScope）

## 備考

- QRコードの生成には`qrcode`ライブラリを使用
- 数量表示には`decimal`テンプレートタグを使用（正規化された数値表示）
- テンプレートはDjangoテンプレート言語で記述され、カスタマイズ可能
- テンプレートファイル: `buildline_label.html`
- IPNが設定されていない部品では、IPN行は表示されない（条件分岐）
- 単位（units）が設定されている場合、数量の後ろに[単位]形式で表示

---

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

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

### 推奨読解順序

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

まず、Build LineとBuild、BomItem、Partの関係を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | models.py | `src/backend/InvenTree/build/models.py` | BuildLineReportContext（1585-1604行目）でコンテキストの型定義を確認。`build`, `bom_item`, `part`, `quantity`などが提供される |
| 1-2 | models.py | `src/backend/InvenTree/build/models.py` | BuildLine.report_context()メソッド（1635-1645行目）で実際に渡されるデータを理解 |
| 1-3 | models.py | `src/backend/InvenTree/build/models.py` | Buildモデル（76-1554行目）とBuildLineモデル（1607-1721行目）の関係を確認 |

**読解のコツ**: BuildLineは製造オーダー（Build）とBOM項目（BomItem）を紐付けるモデル。BomItemを通じてPartにアクセスする。

#### Step 2: テンプレートファイルを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | buildline_label.html | `src/backend/InvenTree/report/templates/label/buildline_label.html` | Build Lineラベルの構造。テーブルレイアウト、条件分岐、decimalタグの使用を確認 |
| 2-2 | label_base.html | `src/backend/InvenTree/report/templates/label/label_base.html` | 基底テンプレートの構造 |

**主要処理フロー**:
- **10-43行目**: スタイル定義
  - `.label`: 全体マージン
  - `.qr`: QRコードサイズ（28mm x 28mm）、右寄せ配置
  - `.label-table`: テーブルスタイル（罫線、パディング）
- **47-71行目**: コンテンツ構造
  - **49-57行目**: 上段（製造オーダー情報）
    - `build.reference`: 製造オーダー番号
    - `build.quantity`: 製造数量（decimalタグで正規化）
    - `build.barcode`: 製造オーダーQRコード
  - **58-70行目**: 下段（部品情報）
    - `part.name`: 部品名
    - `part.IPN`: 内部品番（条件分岐: `{% if part.IPN %}`）
    - `bom_item.quantity`: 単位数量
    - `part.units`: 単位（条件分岐: `{% if part.units %}`）
    - `quantity`: 合計数量（BuildLine.quantity）
    - `part.barcode`: 部品QRコード

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

処理フローはラベル印刷共通のため、詳細は省略。

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

#### Step 4: decimalテンプレートタグを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | inventree_extras.py | `src/backend/InvenTree/InvenTree/templatetags/inventree_extras.py`（要確認） | decimalテンプレートタグの実装。数値の正規化処理を確認 |

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

```
LabelPrint.post() [api.py:157]
    │
    ├─ serializer.is_valid() [api.py:160]
    │
    ├─ get_plugin_class() [api.py:102-125]
    │
    ├─ template.get_model().objects.filter() [api.py:177]
    │      │
    │      └─ BuildLine.objects.filter(pk__in=items)
    │
    └─ print() [api.py:187-224]
           │
           ├─ DataOutput.objects.create() [api.py:200-209]
           │
           └─ offload_task(report.tasks.print_labels) [api.py:213-220]
                  │
                  └─ LabelTemplate.print() [models.py:730]
                         │
                         ├─ plugin.before_printing()
                         │
                         ├─ plugin.print_labels()
                         │      │
                         │      └─ get_context() [models.py:704]
                         │             │
                         │             ├─ base_context()
                         │             │
                         │             └─ BuildLine.report_context()
                         │                    │
                         │                    └─ returns: build, bom_item, part, quantity, etc.
                         │
                         │      テンプレートレンダリング時:
                         │      │
                         │      ├─ {% qrcode build.barcode %} → Build QR
                         │      │
                         │      ├─ {% qrcode part.barcode %} → Part QR
                         │      │
                         │      └─ {% decimal quantity %} → 正規化数量
                         │
                         └─ plugin.after_printing()
```

### データフロー図

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

BuildLine.id ──────────▶ LabelPrint API ──────────────────▶ DataOutput
                               │
                               ▼
                         LabelTemplate
                               │
                               ▼
                    ┌─────────────────────┐
                    │   report_context()  │
                    │  - build            │◀─── BuildLine.build
                    │  - bom_item         │◀─── BuildLine.bom_item
                    │  - part             │◀─── bom_item.sub_part
                    │  - quantity         │◀─── BuildLine.quantity
                    │  - allocated_quantity│
                    │  - allocations      │
                    └─────────────────────┘
                               │
                               ▼
                    ┌─────────────────────┐
                    │ buildline_label.html │
                    │  + label_base.html  │
                    └─────────────────────┘
                               │
           ┌───────────────────┼───────────────────┐
           ▼                   ▼                   ▼
    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
    │ build info  │    │ part info   │    │ QR codes    │
    │ - reference │    │ - name      │    │ - build QR  │
    │ - quantity  │    │ - IPN       │    │ - part QR   │
    └─────────────┘    │ - qty/unit  │    └─────────────┘
                       │ - qty total │
                       └─────────────┘
                               │
                               ▼
                         WeasyPrint ────────────────────▶ PDF
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| api.py | `src/backend/InvenTree/report/api.py` | ソース | ラベル印刷APIエンドポイント |
| models.py | `src/backend/InvenTree/report/models.py` | ソース | LabelTemplateモデル定義 |
| models.py | `src/backend/InvenTree/build/models.py` | ソース | Build, BuildLineモデルとreport_context |
| models.py | `src/backend/InvenTree/part/models.py` | ソース | Part, BomItemモデル |
| barcode.py | `src/backend/InvenTree/report/templatetags/barcode.py` | ソース | QRコード生成テンプレートタグ |
| inventree_extras.py | `src/backend/InvenTree/InvenTree/templatetags/inventree_extras.py` | ソース | decimalテンプレートタグ |
| label_base.html | `src/backend/InvenTree/report/templates/label/label_base.html` | テンプレート | ラベル基底テンプレート |
| buildline_label.html | `src/backend/InvenTree/report/templates/label/buildline_label.html` | テンプレート | 本ラベルのテンプレート |
