# 画面設計書：発注書詳細画面

## 1. 概要

本画面は発注書（Purchase Order）の詳細情報を表示・管理する画面である。発注書の基本情報、明細アイテム、受入在庫、パラメータ、添付ファイル、ノートをパネル形式で表示し、発注書のライフサイクル管理（発行・保留・完了・キャンセル）を行う。

## 2. 関連機能

| 機能ID | 機能名 | 関連種別 |
|--------|--------|----------|
| 12 | 発注書管理 | 主機能 |
| 13 | 発注書アイテム管理 | 補助機能 |
| 2 | サプライヤー管理 | 関連機能 |

## 3. URL

```
/purchasing/purchase-order/:id/*
```

### パスパラメータ

| パラメータ名 | 説明 | 必須 |
|--------------|------|------|
| id | 発注書ID | 必須 |

## 4. 入出力項目

### 4.1 入力項目（編集モーダル）

| 項目名 | 項目ID | 必須 | データ型 | 説明 |
|--------|--------|------|----------|------|
| 参照番号 | reference | 必須 | 文字列 | 発注書の参照番号 |
| サプライヤー参照 | supplier_reference | - | 文字列 | サプライヤー側の参照番号 |
| サプライヤー | supplier | 必須 | 外部キー | サプライヤー（会社） |
| 説明 | description | - | 文字列 | 発注書の説明 |
| 宛先 | destination | - | 外部キー | 受入在庫ロケーション |
| 通貨 | order_currency | - | 文字列 | 発注通貨 |
| 外部リンク | link | - | URL | 外部リンク |
| 担当者 | contact | - | 外部キー | 担当者 |
| プロジェクトコード | project_code | - | 外部キー | プロジェクトコード |
| 責任者 | responsible | - | 外部キー | 責任者 |
| 開始日 | start_date | - | 日付 | 開始日 |
| 目標日 | target_date | - | 日付 | 目標完了日 |

### 4.2 完了オプション（完了モーダル）

| 項目名 | 項目ID | 必須 | データ型 | 説明 |
|--------|--------|------|----------|------|
| 未完了を許容 | accept_incomplete | - | 真偽値 | 未完了アイテムがあっても完了を許可 |

## 5. 表示項目

### 5.1 詳細パネル（Order Details）

#### 左上（tl）

| 項目名 | データソース | 形式 |
|--------|--------------|------|
| 参照番号 | order.reference | テキスト（コピー可） |
| サプライヤー参照 | order.supplier_reference | テキスト（条件付き表示） |
| サプライヤー | order.supplier | リンク |
| 説明 | order.description | テキスト（コピー可） |
| ステータス | order.status | ステータスバッジ |
| カスタムステータス | order.status_custom_key | ステータスバッジ（条件付き表示） |

#### 右上（tr）

| 項目名 | データソース | 形式 |
|--------|--------------|------|
| 完了ラインアイテム | order.completed_lines / order.line_items | 進捗バー |
| 宛先 | order.destination | リンク（条件付き表示） |
| 発注通貨 | orderCurrency | テキスト |
| 合計金額 | order.total_price | 通貨フォーマット |

#### 左下（bl）

| 項目名 | データソース | 形式 |
|--------|--------------|------|
| 外部リンク | order.link | 外部リンク（条件付き表示） |
| 担当者 | order.contact_detail.name | テキスト（条件付き表示） |
| 担当者メール | order.contact_detail.email | テキスト（条件付き表示） |
| 担当者電話 | order.contact_detail.phone | テキスト（条件付き表示） |
| プロジェクトコード | order.project_code_label | テキスト（条件付き表示） |
| 責任者 | order.responsible | バッジ（条件付き表示） |

#### 右下（br）

| 項目名 | データソース | 形式 |
|--------|--------------|------|
| 作成日 | order.creation_date | 日付（コピー可） |
| 発行日 | order.issue_date | 日付（条件付き表示） |
| 開始日 | order.start_date | 日付（条件付き表示） |
| 目標日 | order.target_date | 日付（条件付き表示） |
| 完了日 | order.complete_date | 日付（条件付き表示） |

### 5.2 ラインアイテムパネル（Line Items）

Accordionコンポーネントで2つのテーブルを表示：

| サブパネル名 | 内容 | コンポーネント |
|--------------|------|----------------|
| Line Items | 発注明細アイテム | PurchaseOrderLineItemTable |
| Extra Line Items | 追加明細アイテム | ExtraLineItemTable |

### 5.3 受入在庫パネル（Received Stock）

| 項目名 | 説明 | コンポーネント |
|--------|------|----------------|
| 受入在庫一覧 | この発注書で受け入れた在庫アイテム | StockItemTable |

### 5.4 その他のパネル

| パネル名 | 説明 | コンポーネント |
|----------|------|----------------|
| パラメータ | 発注書パラメータ一覧 | ParametersPanel |
| 添付ファイル | 発注書に関連する添付ファイル | AttachmentPanel |
| ノート | 発注書に関するノート | NotesPanel |

## 6. イベント仕様

### 6.1 アクションボタン

| ボタン名 | 表示条件 | 処理内容 |
|----------|----------|----------|
| Issue Order | ステータスがPENDINGまたはON_HOLD、かつ編集権限あり | 発注書を発行（PLACEDへ遷移） |
| Complete Order | ステータスがPLACED、かつ編集権限あり | 発注書を完了 |

### 6.2 ドロップダウンアクション

| アクション名 | 表示条件 | 処理内容 |
|--------------|----------|----------|
| Edit | 編集権限あり | 発注書編集モーダルを開く |
| Duplicate | 追加権限あり | 発注書複製モーダルを開く |
| Hold | ステータスがPENDINGまたはPLACED、かつ編集権限あり | 発注書を保留 |
| Cancel | ステータスがCANCELLED/COMPLETE以外、かつ編集権限あり | 発注書をキャンセル |

### 6.3 バーコード・印刷アクション

| アクション名 | 説明 |
|--------------|------|
| BarcodeActionDropdown | バーコードのリンク/アンリンク |
| PrintingActions | ラベル/レポート印刷 |
| AdminButton | 管理者画面へのリンク |

### 6.4 ステータス遷移

```
PENDING ─────┬──────> PLACED ──────> COMPLETE
             │           │
             │           ↓
             ├───────> ON_HOLD
             │           │
             │           ↓
             └───────> CANCELLED <──────┘
```

## 7. データベース更新仕様

### 7.1 発注書編集

| 操作 | APIエンドポイント | HTTPメソッド | 説明 |
|------|-------------------|--------------|------|
| 詳細取得 | /api/order/po/{id}/ | GET | 発注書詳細の取得（supplier_detail含む） |
| 編集 | /api/order/po/{id}/ | PUT | 発注書の更新 |
| 複製 | /api/order/po/ | POST | 発注書の新規作成（参照番号は自動生成） |

### 7.2 ステータス変更

| 操作 | APIエンドポイント | HTTPメソッド | 説明 |
|------|-------------------|--------------|------|
| 発行 | /api/order/po/{id}/issue/ | POST | 発注書の発行 |
| 保留 | /api/order/po/{id}/hold/ | POST | 発注書の保留 |
| 完了 | /api/order/po/{id}/complete/ | POST | 発注書の完了（accept_incompleteオプション） |
| キャンセル | /api/order/po/{id}/cancel/ | POST | 発注書のキャンセル |

## 8. メッセージ仕様

### 8.1 確認メッセージ

| 操作 | メッセージ | タイミング |
|------|------------|------------|
| 発行 | Issue this order | 発行モーダル表示時 |
| 保留 | Place this order on hold | 保留モーダル表示時 |
| 完了 | Mark this order as complete | 完了モーダル表示時 |
| キャンセル | Cancel this order | キャンセルモーダル表示時 |

### 8.2 成功メッセージ

| 操作 | メッセージ |
|------|------------|
| 発行 | Order issued |
| 保留 | Order placed on hold |
| 完了 | Order completed |
| キャンセル | Order cancelled |

## 9. 例外処理

| 例外 | 対応 |
|------|------|
| 権限なし | UserRoles.purchase_order権限がない場合はInstanceDetailで権限エラー表示 |
| データ取得失敗 | instanceQuery失敗時はSkeleton表示 |
| 完了API失敗 | timeout: 10000msで長時間処理に対応 |

## 10. 備考

### 10.1 明細編集可否の制御

明細アイテムの編集は以下の条件で制御される：

1. 発注書がオープン状態（PENDING/PLACED/ON_HOLD）の場合は編集可能
2. 発注書が完了/キャンセル済みでも、設定 `PURCHASEORDER_EDIT_COMPLETED_ORDERS` が有効な場合は編集可能

```typescript
const lineItemsEditable: boolean = useMemo(() => {
  if (orderOpen) {
    return true;
  } else {
    return globalSettings.isSet('PURCHASEORDER_EDIT_COMPLETED_ORDERS');
  }
}, [orderOpen, globalSettings]);
```

### 10.2 通貨の決定ロジック

発注通貨は以下の優先順位で決定される：

1. order.order_currency（発注書の通貨設定）
2. order.supplier_detail.currency（サプライヤーの通貨設定）
3. INVENTREE_DEFAULT_CURRENCY（システムデフォルト通貨）

### 10.3 複製時の参照番号処理

発注書を複製する際、参照番号（reference）はフォームデータから削除される。これにより、参照番号パターンに基づいて自動生成される。

---

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

### 関連ファイル一覧

| ファイル名 | 役割 | 行数 |
|------------|------|------|
| `src/frontend/src/pages/purchasing/PurchaseOrderDetail.tsx` | 発注書詳細画面メインコンポーネント | 584行 |
| `src/frontend/src/forms/PurchaseOrderForms.tsx` | 発注書フォームフィールド定義 | - |
| `src/frontend/src/tables/purchasing/PurchaseOrderLineItemTable.tsx` | 発注書明細テーブル | - |
| `src/frontend/src/tables/general/ExtraLineItemTable.tsx` | 追加明細テーブル | - |
| `src/frontend/src/tables/stock/StockItemTable.tsx` | 在庫アイテムテーブル | - |

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

```
PurchaseOrderDetail (エントリーポイント)
├── useInstance (データ取得)
│   └── ApiEndpoints.purchase_order_list + supplier_detail
├── useStatusCodes (ステータスコード)
│   └── ModelType.purchaseorder
├── usePurchaseOrderFields (フォームフィールド定義)
├── useEditApiFormModal (編集モーダル)
├── useCreateApiFormModal x5
│   ├── duplicatePurchaseOrder (複製)
│   ├── issueOrder (発行)
│   ├── cancelOrder (キャンセル)
│   ├── holdOrder (保留)
│   └── completeOrder (完了)
├── PageDetail (ページヘッダー)
│   ├── PrimaryActionButton x2 (Issue/Complete)
│   ├── AdminButton
│   ├── BarcodeActionDropdown
│   ├── PrintingActions
│   └── OptionsActionDropdown
│       ├── EditItemAction
│       ├── DuplicateItemAction
│       ├── HoldItemAction
│       └── CancelItemAction
└── PanelGroup (パネルグループ)
    ├── detail (詳細パネル)
    │   └── ItemDetailsGrid + DetailsTable x4
    ├── line-items (明細パネル)
    │   └── Accordion
    │       ├── PurchaseOrderLineItemTable
    │       └── ExtraLineItemTable
    ├── received-stock (受入在庫パネル)
    │   └── StockItemTable (purchase_order=id)
    ├── ParametersPanel
    ├── AttachmentPanel
    └── NotesPanel
```

### データフロー図

```
[URLパラメータ id]
        │
        ▼
[useInstance: purchase_order_list]
        │
        ├─────────────────────────────────────┐
        ▼                                     ▼
[order (発注書データ)]           [orderCurrency (通貨決定)]
        │                                     │
        ├─────────────────┬───────────────────┤
        ▼                 ▼                   ▼
[detailsPanel]     [orderPanels]        [poActions]
(4領域の詳細表示)   (6つのパネル)       (ステータス変更ボタン)
        │                 │                   │
        └─────────────────┴───────────────────┘
                          │
                          ▼
                [PanelGroup で統合表示]
```

### 重要な処理の行番号参照

| 処理 | 行番号 | 説明 |
|------|--------|------|
| useInstance（発注書取得） | 60-71行 | supplier_detail付きで詳細取得 |
| orderCurrency決定 | 73-79行 | 通貨の優先順位ロジック |
| 編集モーダル定義 | 87-95行 | useEditApiFormModal |
| orderOpen判定 | 99-105行 | PENDING/PLACED/ON_HOLDを判定 |
| lineItemsEditable判定 | 107-113行 | 編集可否の条件判定 |
| 複製時のreference削除 | 115-122行 | 参照番号を削除して自動生成 |
| detailsPanel定義 | 133-328行 | 4領域（tl,tr,bl,br）の表示項目 |
| orderPanels定義 | 330-407行 | 6つのパネル定義 |
| ラインアイテムパネル | 338-379行 | Accordion内に2テーブル |
| issueOrder モーダル | 409-415行 | 発行処理 |
| cancelOrder モーダル | 417-423行 | キャンセル処理 |
| holdOrder モーダル | 425-431行 | 保留処理 |
| completeOrder モーダル | 433-443行 | 完了処理（accept_incompleteオプション） |
| poActions定義 | 445-518行 | アクションボタン・メニュー |
| canIssue条件 | 448-450行 | PENDING/ON_HOLDで発行可 |
| canHold条件 | 452-454行 | PENDING/PLACEDで保留可 |
| canComplete条件 | 456行 | PLACEDで完了可 |
| canCancel条件 | 458-461行 | CANCELLED/COMPLETE以外でキャンセル可 |
| PageDetail | 555-570行 | ページヘッダー、パンくずリスト |
| PanelGroup | 571-578行 | pageKey='purchaseorder' |
