# 機能設計書: 製造アウトプット管理

## 1. 機能概要

### 1.1 機能の目的
製造アウトプット管理機能は、製造オーダー（BuildOrder）における製造出力（BuildOutput）を管理するための機能である。製造出力とは、製造オーダーの結果として生成される在庫品目（StockItem）であり、製造中（is_building=True）の状態で管理される。

### 1.2 機能の範囲
- 製造出力の作成（シリアル番号付与、バッチコード管理含む）
- 製造出力の削除（キャンセル）
- 製造出力のスクラップ処理
- 製造出力の完了処理
- 追跡可能部品に対するシリアル番号管理

### 1.3 関連画面
| 画面ID | 画面名 | 関連操作 |
|--------|--------|----------|
| SCR-BUILD | 製造オーダー詳細 | 製造出力の作成・管理 |

## 2. 機能仕様

### 2.1 製造出力の作成

#### 2.1.1 処理概要
製造オーダーに対して新しい製造出力を作成する。製造出力は在庫品目（StockItem）として生成され、`is_building=True`の状態で管理される。

#### 2.1.2 入力パラメータ
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| quantity | Decimal | Yes | 製造数量（0より大きい値） |
| batch_code | String | No | バッチコード（省略時は自動生成） |
| serial_numbers | String | No | シリアル番号（追跡可能部品の場合必須） |
| location | Integer | No | 製造出力の保管場所ID |
| auto_allocate | Boolean | No | シリアル番号の自動割当（デフォルト: false） |

#### 2.1.3 ビジネスルール
1. **数量バリデーション**
   - 数量は0より大きい値でなければならない
   - 追跡可能部品（trackable=True）の場合、数量は整数でなければならない
   - BOMに追跡可能部品を含む場合も整数でなければならない

2. **シリアル番号バリデーション**
   - 追跡可能部品の場合、シリアル番号は必須
   - シリアル番号は既存のシリアル番号と重複してはならない
   - シリアル番号の数と数量は一致しなければならない

3. **バッチコード**
   - 未指定の場合は`generate_batch_code()`により自動生成

### 2.2 製造出力の削除

#### 2.2.1 処理概要
製造オーダーから製造出力を削除（キャンセル）する。

#### 2.2.2 入力パラメータ
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| outputs | Array | Yes | 削除する製造出力のリスト |

#### 2.2.3 ビジネスルール
1. 削除対象の製造出力は製造中（is_building=True）状態でなければならない
2. 削除対象の製造出力は指定された製造オーダーに紐づいていなければならない
3. 少なくとも1つの製造出力が指定されなければならない

### 2.3 製造出力のスクラップ

#### 2.3.1 処理概要
不良品等の理由で製造出力をスクラップ処理する。

#### 2.3.2 入力パラメータ
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| outputs | Array | Yes | スクラップする製造出力と数量のリスト |
| location | Integer | Yes | スクラップ品の保管場所ID |
| discard_allocations | Boolean | No | 割当済み在庫の破棄（デフォルト: false） |
| notes | String | Yes | スクラップ理由 |

#### 2.3.3 ビジネスルール
1. スクラップ数量は製造出力の数量を超えてはならない
2. スクラップ理由（notes）は必須
3. 保管場所の指定は必須

### 2.4 製造出力の完了

#### 2.4.1 処理概要
製造出力を完了状態に遷移させ、正式な在庫品目として登録する。

#### 2.4.2 入力パラメータ
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| outputs | Array | Yes | 完了する製造出力と数量のリスト |
| location | Integer | Yes | 完成品の保管場所ID |
| status_custom_key | Integer | No | 在庫ステータス（デフォルト: OK） |
| accept_incomplete_allocation | Boolean | No | 未完全割当の許可（デフォルト: false） |
| notes | String | No | メモ |

#### 2.4.3 ビジネスルール
1. 製造出力は製造中（is_building=True）状態でなければならない
2. 追跡可能部品の場合、すべての部品が割当済みでなければならない（accept_incomplete_allocation=falseの場合）
3. 設定により、必須テストに合格していない場合は完了できない
4. 完了数量は製造出力の数量を超えてはならない

## 3. データモデル

### 3.1 関連エンティティ
```
Build (製造オーダー)
├── StockItem (製造出力: is_building=True)
│   ├── serial: シリアル番号
│   ├── batch: バッチコード
│   ├── quantity: 数量
│   └── location: 保管場所
└── BuildLine (製造ライン)
    └── BuildItem (割当済み在庫)
```

### 3.2 主要フィールド
| フィールド名 | 型 | 説明 |
|-------------|------|------|
| StockItem.is_building | Boolean | 製造中フラグ |
| StockItem.build | ForeignKey | 紐づく製造オーダー |
| StockItem.serial | String | シリアル番号 |
| StockItem.batch | String | バッチコード |

## 4. API仕様

### 4.1 製造出力作成
- **エンドポイント**: `POST /api/build/{pk}/create-output/`
- **シリアライザ**: `BuildOutputCreateSerializer`
- **権限**: 認証済みユーザー

### 4.2 製造出力削除
- **エンドポイント**: `POST /api/build/{pk}/delete-outputs/`
- **シリアライザ**: `BuildOutputDeleteSerializer`
- **権限**: 認証済みユーザー

### 4.3 製造出力スクラップ
- **エンドポイント**: `POST /api/build/{pk}/scrap-outputs/`
- **シリアライザ**: `BuildOutputScrapSerializer`
- **権限**: 認証済みユーザー

### 4.4 製造出力完了
- **エンドポイント**: `POST /api/build/{pk}/complete-outputs/`
- **シリアライザ**: `BuildOutputCompleteSerializer`
- **権限**: 認証済みユーザー

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

### 5.1 推奨読解順序

1. **データモデル理解**
   - `src/backend/InvenTree/build/models.py`
     - **Build.create_build_output()**: 製造出力作成のコアロジック
     - **Build.delete_output()**: 製造出力削除のコアロジック
     - **Build.scrap_build_output()**: スクラップ処理のコアロジック
     - **Build.complete_build_output()**: 完了処理のコアロジック

2. **シリアライザ（バリデーションロジック）**
   - `src/backend/InvenTree/build/serializers.py`
     - **193-245行目**: `BuildOutputSerializer` - 製造出力の基本シリアライザ
     - **286-435行目**: `BuildOutputCreateSerializer` - 作成時のバリデーション
     - **438-469行目**: `BuildOutputDeleteSerializer` - 削除時のバリデーション
     - **472-534行目**: `BuildOutputScrapSerializer` - スクラップ時のバリデーション
     - **537-641行目**: `BuildOutputCompleteSerializer` - 完了時のバリデーション

3. **APIエンドポイント**
   - `src/backend/InvenTree/build/api.py`
     - 各エンドポイントのView定義

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

```
[API Request]
    │
    ▼
BuildOutputCreateSerializer.validate()
    │
    ├── validate_quantity() [322-343行目]
    │   └── 追跡可能部品の場合の整数チェック
    │
    ├── validate_serial_numbers() [368-372行目]
    │   └── シリアル番号の正規化
    │
    └── validate() [384-419行目]
        └── シリアル番号の重複チェック
            │
            ▼
BuildOutputCreateSerializer.save()
    │
    ▼
Build.create_build_output() [models.py]
    │
    ├── StockItem.objects.create()
    │   └── is_building=True で作成
    │
    └── auto_allocate_stock() (オプション)
```

### 5.3 データフロー図

```
[ユーザー入力]
    │
    ▼
┌─────────────────────────────────────┐
│ BuildOutputCreateSerializer         │
│ ・quantity: 製造数量               │
│ ・batch_code: バッチコード         │
│ ・serial_numbers: シリアル番号     │
│ ・location: 保管場所               │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│ Build.create_build_output()         │
│ ・シリアル番号のパース             │
│ ・在庫品目の作成                   │
│ ・自動割当（オプション）           │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│ StockItem (is_building=True)        │
│ ・製造オーダーとの紐付け           │
│ ・シリアル番号/バッチコード設定   │
└─────────────────────────────────────┘
```

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

| ファイルパス | 種別 | 役割 |
|-------------|------|------|
| `src/backend/InvenTree/build/models.py` | Model | Buildモデル定義、製造出力管理メソッド |
| `src/backend/InvenTree/build/serializers.py` | Serializer | API入出力のバリデーション・シリアライズ |
| `src/backend/InvenTree/build/api.py` | API | RESTful APIエンドポイント定義 |
| `src/backend/InvenTree/stock/models.py` | Model | StockItemモデル定義 |
| `src/backend/InvenTree/stock/generators.py` | Utility | バッチコード自動生成 |

## 6. 例外処理

### 6.1 バリデーションエラー
| エラー条件 | エラーメッセージ |
|-----------|-----------------|
| 数量が0以下 | "Quantity must be greater than zero" |
| 追跡可能部品で非整数 | "Integer quantity required for trackable parts" |
| シリアル番号重複 | "The following serial numbers already exist or are invalid" |
| シリアル番号未指定（追跡可能部品） | "Serial numbers must be provided for trackable parts" |
| 製造出力リストが空 | "A list of build outputs must be provided" |
| 未完全割当 | "This build output is not fully allocated" |

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

- APIアクセスには認証が必要
- 製造オーダーに対する権限チェックが実施される
- シリアル番号の重複チェックにより、追跡可能性が保証される
