# 機能設計書 41-バーコード生成

## 概要

本ドキュメントは、InvenTreeシステムにおけるバーコード生成機能の設計仕様を定義する。この機能は、部品、在庫アイテム、ロケーションなど様々なオブジェクトに対してバーコード（QRコード等）を生成し、ラベル印刷やスキャン操作を可能にする。

### 本機能の処理概要

**業務上の目的・背景**：
製造業・倉庫管理において、部品や在庫の識別・追跡は重要な業務課題である。バーコードを活用することで、手作業による入力ミスを削減し、在庫カウント・入出庫処理・部品検索などの業務効率を大幅に向上させることができる。本機能は、InvenTreeが管理する各種オブジェクトに対して一意のバーコードを生成し、物理的なラベルとして印刷可能にすることで、デジタルデータと物理的なアイテムを紐づける基盤を提供する。

**機能の利用シーン**：
- 新規部品や在庫アイテムを登録した際に、識別用のQRコードラベルを印刷する
- 保管棚・ロケーションにバーコードラベルを貼付し、在庫管理を効率化する
- 発注書・販売注文などの帳票にバーコードを含めて印刷する
- モバイルアプリからバーコードをスキャンして迅速にアイテムを検索する

**主要な処理内容**：
1. 対象オブジェクト（Part, StockItem, StockLocation等）からバーコードデータを生成
2. InvenTree独自の内部バーコードフォーマットまたはサードパーティフォーマットをサポート
3. プラグインシステムを介したバーコード生成アルゴリズムのカスタマイズ
4. 生成されたバーコードデータのラベルテンプレートへの埋め込み

**関連システム・外部連携**：
- プラグインシステム（BarcodeMixin）によるカスタムバーコード生成
- ラベル印刷機能との連携（LabelTemplate）
- モバイルアプリでのスキャン機能との連携

**権限による制御**：
- バーコード生成APIは認証済みユーザーまたは読み取りスコープを持つトークンでアクセス可能
- オブジェクトへのバーコード割り当ては、対象モデルの変更権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 12 | バーコードスキャン画面 | API連携 | スキャン結果からのオブジェクト情報取得 |
| 14 | 部品詳細画面 | 補助機能 | 部品バーコードの生成・印刷 |
| 16 | 在庫アイテム詳細画面 | 補助機能 | 在庫アイテムバーコードの生成・印刷 |
| 35 | システム設定画面 | 補助機能 | バーコード設定 |

## 機能種別

データ連携 / 計算処理 / ラベル出力

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| model | string | Yes | モデルタイプ（part, stockitem, stocklocation等） | サポートされているモデルタイプのみ |
| pk | integer | Yes | オブジェクトのプライマリキー | 正の整数 |

### 入力データソース

- APIリクエスト（POST /api/barcode/generate/）
- モデルインスタンスのformat_barcode()メソッド呼び出し

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| barcode | string | 生成されたバーコードデータ文字列 |

### 出力先

- APIレスポンス（JSON形式）
- ラベルテンプレート内でのバーコードフィールド

## 処理フロー

### 処理シーケンス

```
1. バーコード生成リクエストの受信
   └─ BarcodeGenerate APIエンドポイント
2. リクエストパラメータのバリデーション
   └─ モデルタイプとPKの検証
3. 対象モデルインスタンスの取得
   └─ データベースからオブジェクトを取得
4. バーコード生成プラグインの選択
   └─ グローバル設定BARCODE_GENERATION_PLUGINを参照
5. プラグインによるバーコード文字列の生成
   └─ plugin.generate(model_instance)の呼び出し
6. 生成されたバーコードデータの返却
   └─ JSON形式でレスポンス
```

### フローチャート

```mermaid
flowchart TD
    A[バーコード生成リクエスト] --> B{パラメータ検証}
    B -->|無効| C[エラーレスポンス]
    B -->|有効| D[モデルインスタンス取得]
    D --> E{インスタンス存在?}
    E -->|No| F[404エラー]
    E -->|Yes| G[バーコード生成プラグイン取得]
    G --> H[プラグインでバーコード生成]
    H --> I[バーコードデータ返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-41-01 | サポートモデル制限 | InvenTreeBarcodeMixinを継承したモデルのみバーコード生成可能 | 全てのバーコード生成リクエスト |
| BR-41-02 | プラグイン選択 | グローバル設定BARCODE_GENERATION_PLUGINで指定されたプラグインを使用 | バーコード生成時 |
| BR-41-03 | モデルタイプコード | 各モデルは2文字の短縮コードを持ち、バーコードフォーマットに使用 | 内部バーコードフォーマット使用時 |

### 計算ロジック

バーコードデータの生成は、選択されたプラグインのgenerate()メソッドに委譲される。デフォルトのInvenTreeバーコードプラグインは、以下のフォーマットでバーコードを生成する：

```
{model_type_code}{pk}
例: SI123 (StockItem ID 123)
```

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| バーコード生成 | 対象モデルテーブル | SELECT | モデルインスタンスの取得 |
| プラグイン設定取得 | common_inventreesetting | SELECT | BARCODE_GENERATION_PLUGIN設定の取得 |

### テーブル別操作詳細

#### 対象モデルテーブル（part_part, stock_stockitem等）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | pk, barcode_data, barcode_hash | pk = 指定されたPK | バーコード生成に必要な情報を取得 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 400 | ValidationError | サポートされていないモデルタイプ | 正しいモデルタイプを指定 |
| 404 | NotFound | 指定されたPKのインスタンスが存在しない | 正しいPKを指定 |
| 500 | InternalError | プラグインエラー | システム管理者に連絡 |

### リトライ仕様

バーコード生成は冪等な操作であり、エラー時は再リクエストが可能。

## トランザクション仕様

バーコード生成は読み取り専用操作のため、トランザクション管理は不要。

## パフォーマンス要件

- バーコード生成レスポンス時間：100ms以内
- 複数アイテムのバーコード生成時はバッチ処理を推奨

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

- 認証済みユーザーまたは適切なAPIスコープが必要
- バーコードデータに機密情報は含めない
- 生成されたバーコードはオブジェクトの識別子のみを含む

## 備考

- バーコード生成プラグインはPluginMixinEnumのBARCODE mixinを使用
- サポートされるモデルはInvenTreeBarcodeMixinを継承する必要がある

---

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

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

### 推奨読解順序

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

バーコード機能の基盤となるMixinクラスを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | models.py | `src/backend/InvenTree/InvenTree/models.py` | InvenTreeBarcodeMixinクラス（1237-1373行目）の構造を理解 |

**読解のコツ**:
- `barcode_data`と`barcode_hash`フィールドが外部バーコード割り当て用
- `barcode_model_type()`と`barcode_model_type_code()`がモデル識別に使用
- `format_barcode()`がバーコード文字列生成のエントリーポイント

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

バーコード生成APIエンドポイントの処理フローを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | api.py | `src/backend/InvenTree/plugin/base/barcodes/api.py` | BarcodeGenerate APIクラス（227-264行目） |

**主要処理フロー**:
1. **242-246行目**: リクエストのバリデーション
2. **247-259行目**: モデルインスタンスの取得
3. **261行目**: バーコード生成ヘルパー関数の呼び出し
4. **263行目**: レスポンスの返却

#### Step 3: バーコード生成ヘルパーを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | helper.py | `src/backend/InvenTree/plugin/base/barcodes/helper.py` | generate_barcode関数（32-43行目） |

**主要処理フロー**:
- **39行目**: グローバル設定からプラグインスラッグを取得
- **41行目**: プラグインレジストリからプラグインインスタンスを取得
- **43行目**: プラグインのgenerate()メソッドを呼び出し

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

```
BarcodeGenerate.create()
    │
    ├─ BarcodeGenerateSerializer.is_valid()
    │      └─ モデルタイプとPKの検証
    │
    ├─ get_supported_barcode_models_map()
    │      └─ サポートされるモデルのマッピング取得
    │
    └─ generate_barcode(model_instance)
           │
           ├─ get_global_setting('BARCODE_GENERATION_PLUGIN')
           │      └─ プラグイン設定の取得
           │
           ├─ registry.get_plugin(slug)
           │      └─ プラグインインスタンスの取得
           │
           └─ plugin.generate(model_instance)
                  └─ バーコード文字列の生成
```

### データフロー図

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

POST Request    ───▶ BarcodeGenerate      ───▶ JSON Response
  model: "part"       APIエンドポイント          barcode: "PT123"
  pk: 123
                        │
                        ▼
                 generate_barcode()
                        │
                        ▼
                 プラグイン.generate()
                        │
                        ▼
                 バーコード文字列生成
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| models.py | `src/backend/InvenTree/InvenTree/models.py` | ソース | InvenTreeBarcodeMixinの定義 |
| api.py | `src/backend/InvenTree/plugin/base/barcodes/api.py` | ソース | バーコードAPIエンドポイント |
| helper.py | `src/backend/InvenTree/plugin/base/barcodes/helper.py` | ソース | バーコード生成ヘルパー関数 |
| serializers.py | `src/backend/InvenTree/plugin/base/barcodes/serializers.py` | ソース | APIリクエスト/レスポンスシリアライザ |
