# 機能設計書: 製造進捗追跡

## 1. 機能概要

### 1.1 機能の目的
製造進捗追跡機能は、製造オーダー（Build）の進捗状況を管理・監視するための機能である。製造オーダーのステータス遷移、在庫割当状況、完了数量の追跡を行い、製造プロセス全体の可視化を実現する。

### 1.2 機能の範囲
- 製造オーダーのステータス管理（発行、保留、完了、キャンセル）
- 在庫割当・割当解除の管理
- 自動割当機能
- 在庫消費処理
- 製造オーダー完了処理
- 進捗情報のクエリ・フィルタリング

### 1.3 関連画面
| 画面ID | 画面名 | 関連操作 |
|--------|--------|----------|
| SCR-BUILD-LIST | 製造オーダー一覧 | 製造オーダーの検索・フィルタリング |
| SCR-BUILD-DETAIL | 製造オーダー詳細 | 進捗確認・ステータス変更 |

## 2. 機能仕様

### 2.1 ステータス管理

#### 2.1.1 製造オーダーのステータス
製造オーダーは以下のステータスを持つ（BuildStatus）：

| ステータス | 説明 |
|-----------|------|
| PENDING | 保留中（初期状態） |
| PRODUCTION | 製造中 |
| ON_HOLD | 一時停止 |
| CANCELLED | キャンセル |
| COMPLETE | 完了 |

#### 2.1.2 発行処理（Issue Build）
製造オーダーを「製造中」状態に遷移させる。

- **エンドポイント**: `POST /api/build/{pk}/issue/`
- **シリアライザ**: `BuildIssueSerializer`
- **前提条件**: 製造オーダーが発行可能な状態であること

#### 2.1.3 保留処理（Hold Build）
製造オーダーを「一時停止」状態に遷移させる。

- **エンドポイント**: `POST /api/build/{pk}/hold/`
- **シリアライザ**: `BuildHoldSerializer`
- **前提条件**: 製造オーダーが保留可能な状態であること

#### 2.1.4 キャンセル処理（Cancel Build）
製造オーダーをキャンセルする。

- **エンドポイント**: `POST /api/build/{pk}/cancel/`
- **シリアライザ**: `BuildCancelSerializer`

**入力パラメータ**:
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| remove_allocated_stock | Boolean | No | 割当済み在庫を消費するか（デフォルト: false） |
| remove_incomplete_outputs | Boolean | No | 未完了出力を削除するか（デフォルト: false） |

**コンテキストデータ**:
- `has_allocated_stock`: 部分的に割当済みの在庫があるか
- `incomplete_outputs`: 未完了出力の数
- `completed_outputs`: 完了済み出力の数

#### 2.1.5 完了処理（Complete Build）
製造オーダーを完了状態に遷移させる。

- **エンドポイント**: `POST /api/build/{pk}/complete/`
- **シリアライザ**: `BuildCompleteSerializer`

**入力パラメータ**:
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| accept_overallocated | String | No | 過剰割当の処理方法（reject/accept/trim） |
| accept_unallocated | Boolean | No | 未割当を許可するか |
| accept_incomplete | Boolean | No | 未完了を許可するか |

**ビジネスルール**:
1. 製造オーダーはPRODUCTION状態でなければならない
2. 未完了の製造出力が存在してはならない
3. 設定により子製造オーダーがクローズしていなければならない場合がある
4. 過剰割当がある場合、処理方法の選択が必要

### 2.2 在庫割当管理

#### 2.2.1 手動割当
製造ラインに対して在庫を手動で割り当てる。

- **エンドポイント**: `POST /api/build/{pk}/allocate/`
- **シリアライザ**: `BuildAllocationSerializer`

**入力パラメータ**:
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| items | Array | Yes | 割当アイテムのリスト |
| items[].build_line | Integer | Yes | 製造ラインID |
| items[].stock_item | Integer | Yes | 在庫品目ID |
| items[].quantity | Decimal | Yes | 割当数量 |
| items[].output | Integer | No | 製造出力ID（追跡可能部品の場合必須） |

**ビジネスルール**:
1. 割当数量は在庫品目の未割当数量を超えてはならない
2. 追跡可能部品の場合、製造出力の指定が必須
3. 非追跡可能部品の場合、製造出力は指定不可
4. 消耗品（consumable）のBOMアイテムは割当をスキップ

#### 2.2.2 自動割当
製造ラインに対して在庫を自動的に割り当てる。

- **エンドポイント**: `POST /api/build/{pk}/auto-allocate/`
- **シリアライザ**: `BuildAutoAllocationSerializer`

**入力パラメータ**:
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| location | Integer | No | ソース場所（指定なしで全場所対象） |
| exclude_location | Integer | No | 除外場所 |
| interchangeable | Boolean | No | 異なる場所の在庫を交換可能として扱うか |
| substitutes | Boolean | No | 代替部品の使用を許可するか（デフォルト: true） |
| optional_items | Boolean | No | オプションBOMアイテムを割り当てるか |

#### 2.2.3 割当解除
製造オーダーから在庫割当を解除する。

- **エンドポイント**: `POST /api/build/{pk}/unallocate/`
- **シリアライザ**: `BuildUnallocationSerializer`

**入力パラメータ**:
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| build_line | Integer | No | 特定の製造ラインのみ解除 |
| output | Integer | No | 特定の製造出力のみ解除 |

### 2.3 在庫消費処理

#### 2.3.1 処理概要
割当済み在庫を消費し、製造ラインの「消費済み」数量を更新する。

- **エンドポイント**: `POST /api/build/{pk}/consume/`
- **シリアライザ**: `BuildConsumeSerializer`

**入力パラメータ**:
| パラメータ名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| items | Array | No | 消費するBuildItemのリスト |
| lines | Array | No | 消費するBuildLineのリスト |
| notes | String | No | 消費メモ |

**ビジネスルール**:
1. itemsまたはlinesのいずれか少なくとも1つは必須
2. 消費数量は割当数量を超えてはならない
3. 追跡可能部品で出力に紐づく場合は、出力完了時に消費される

### 2.4 進捗情報クエリ

#### 2.4.1 BuildLineSerializer アノテーション
製造ラインの進捗情報は以下のフィールドでアノテートされる：

| フィールド | 説明 |
|-----------|------|
| allocated | 割当済み数量 |
| on_order | 発注中数量 |
| in_production | 製造中数量 |
| scheduled_to_build | 製造予定数量 |
| available_stock | 利用可能在庫 |
| available_substitute_stock | 利用可能代替在庫 |
| available_variant_stock | 利用可能バリアント在庫 |
| external_stock | 外部在庫 |

## 3. データモデル

### 3.1 関連エンティティ
```
Build (製造オーダー)
├── status: BuildStatus
├── quantity: 製造数量
├── completed: 完了数量
├── creation_date: 作成日
├── target_date: 目標日
├── completion_date: 完了日
│
├── BuildLine (製造ライン)
│   ├── bom_item: BOMアイテム
│   ├── quantity: 必要数量
│   ├── consumed: 消費済み数量
│   └── BuildItem (割当)
│       ├── stock_item: 在庫品目
│       ├── quantity: 割当数量
│       └── install_into: 出力先（追跡可能の場合）
│
└── StockItem (製造出力)
    └── is_building: 製造中フラグ
```

### 3.2 進捗計算ロジック
- **overdue**: `target_date < today AND status != COMPLETE`
- **remaining**: `quantity - completed`
- **is_partially_allocated**: 一部の製造ラインで割当が完了していない
- **are_untracked_parts_allocated**: 非追跡部品がすべて割当済み
- **is_overallocated**: 割当数量が必要数量を超過

## 4. API仕様

### 4.1 製造オーダー一覧
- **エンドポイント**: `GET /api/build/`
- **フィルタ**: status, part, project_code, responsible, issued_by, assigned_to等
- **検索フィールド**: reference, part__name, part__IPN, part__description

### 4.2 製造オーダー詳細
- **エンドポイント**: `GET /api/build/{pk}/`
- **シリアライザ**: `BuildSerializer`
- **アノテーション**: overdue（期限超過フラグ）

### 4.3 製造ライン一覧
- **エンドポイント**: `GET /api/build/line/`
- **シリアライザ**: `BuildLineSerializer`
- **アノテーション**: 上記2.4.1参照

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

### 5.1 推奨読解順序

1. **ステータス定義**
   - `src/backend/InvenTree/build/status_codes.py`
     - BuildStatusの定義を確認

2. **モデル定義**
   - `src/backend/InvenTree/build/models.py`
     - **Build**: 製造オーダーモデル
     - **BuildLine**: 製造ラインモデル
     - **BuildItem**: 割当アイテムモデル

3. **シリアライザ（ステータス遷移）**
   - `src/backend/InvenTree/build/serializers.py`
     - **644-656行目**: `BuildIssueSerializer` - 発行処理
     - **658-670行目**: `BuildHoldSerializer` - 保留処理
     - **673-716行目**: `BuildCancelSerializer` - キャンセル処理
     - **733-841行目**: `BuildCompleteSerializer` - 完了処理

4. **シリアライザ（在庫割当）**
   - `src/backend/InvenTree/build/serializers.py`
     - **844-894行目**: `BuildUnallocationSerializer` - 割当解除
     - **897-1005行目**: `BuildAllocationItemSerializer` - 割当アイテム
     - **1008-1065行目**: `BuildAllocationSerializer` - 割当処理
     - **1068-1138行目**: `BuildAutoAllocationSerializer` - 自動割当

5. **シリアライザ（在庫消費）**
   - `src/backend/InvenTree/build/serializers.py`
     - **1692-1727行目**: `BuildConsumeAllocationSerializer`
     - **1730-1740行目**: `BuildConsumeLineItemSerializer`
     - **1743-1863行目**: `BuildConsumeSerializer`

6. **進捗計算ロジック**
   - `src/backend/InvenTree/build/serializers.py`
     - **1514-1689行目**: `BuildLineSerializer.annotate_queryset()` - 進捗アノテーション

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

```
[Complete Build Request]
    │
    ▼
BuildCompleteSerializer.validate()
    │
    ├── validate_accept_overallocated() [765-772行目]
    │   └── 過剰割当チェック
    │
    ├── validate_accept_unallocated() [783-789行目]
    │   └── 未割当チェック
    │
    ├── validate_accept_incomplete() [801-807行目]
    │   └── 未完了チェック
    │
    └── validate() [810-826行目]
        ├── 子オーダーのクローズチェック
        ├── ステータスチェック（PRODUCTION必須）
        └── 未完了出力チェック
            │
            ▼
BuildCompleteSerializer.save()
    │
    ▼
Build.complete_build() [models.py]
    │
    ├── trim_allocated_stock（オプション）
    │   └── 過剰割当の削減
    │
    └── ステータス更新 → COMPLETE
```

### 5.3 データフロー図（自動割当）

```
[自動割当リクエスト]
    │
    ▼
┌─────────────────────────────────────┐
│ BuildAutoAllocationSerializer       │
│ ・location: ソース場所             │
│ ・exclude_location: 除外場所       │
│ ・interchangeable: 交換可能フラグ │
│ ・substitutes: 代替許可フラグ     │
│ ・optional_items: オプション許可   │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│ offload_task(auto_allocate_build)   │
│ ・バックグラウンドタスクとして実行 │
└─────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────┐
│ build.tasks.auto_allocate_build     │
│ ・各BuildLineに対して             │
│ ・利用可能在庫を検索             │
│ ・BuildItemを作成                 │
└─────────────────────────────────────┘
```

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

| ファイルパス | 種別 | 役割 |
|-------------|------|------|
| `src/backend/InvenTree/build/models.py` | Model | Build, BuildLine, BuildItemモデル定義 |
| `src/backend/InvenTree/build/serializers.py` | Serializer | 進捗管理関連シリアライザ |
| `src/backend/InvenTree/build/api.py` | API | RESTful APIエンドポイント定義 |
| `src/backend/InvenTree/build/status_codes.py` | Enum | BuildStatusの定義 |
| `src/backend/InvenTree/build/tasks.py` | Task | 自動割当等のバックグラウンドタスク |
| `src/backend/InvenTree/part/filters.py` | Filter | 在庫・発注等のアノテーションフィルタ |

## 6. 例外処理

### 6.1 バリデーションエラー
| エラー条件 | エラーメッセージ |
|-----------|-----------------|
| 過剰割当でreject選択 | "Some stock items have been overallocated" |
| 未割当で許可なし | "Required stock has not been fully allocated" |
| 未完了で許可なし | "Required build quantity has not been completed" |
| 子オーダー未クローズ | "Build order has open child build orders" |
| PRODUCTION以外で完了 | "Build order must be in production state" |
| 未完了出力あり | "Build order has incomplete outputs" |
| 割当数量超過 | "Available quantity ({q}) exceeded" |
| 追跡部品で出力未指定 | "Build output must be specified for allocation of tracked parts" |

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

- APIアクセスには認証が必要
- 製造オーダーに対する権限チェックが実施される
- 自動割当はバックグラウンドタスクとして実行され、長時間処理に対応
