# 画面設計書 24-返品オーダー詳細画面

## 概要

本ドキュメントは、InvenTreeシステムの返品オーダー詳細画面(ReturnOrderDetail)の設計仕様を定義するものである。

### 本画面の処理概要

返品オーダー詳細画面は、個別の返品オーダー（Return Order）に関する詳細情報の表示・編集・管理を行うための画面である。顧客からの返品処理を管理し、返品明細、受入処理、ステータス管理などの機能を提供する。

**業務上の目的・背景**：販売業務において、顧客からの返品対応は品質管理と顧客満足度維持の重要な要素である。本画面は、返品オーダーの作成から完了までのライフサイクルを管理し、どの商品がどのような理由で返品されたかを追跡可能にする。返品品の受入処理、在庫への再登録、返金処理の管理などを支援し、返品プロセス全体の可視化と効率化を実現する。

**画面へのアクセス方法**：販売インデックス画面の返品オーダー一覧から対象の行をクリック、または顧客詳細画面から遷移、あるいは直接URL `/sales/return-order/:id/*` にアクセスすることで本画面を表示できる。

**主要な操作・処理内容**：
1. 返品オーダー基本情報の表示・編集（顧客、参照番号、説明、日付等）
2. 返品明細アイテムの追加・編集・削除
3. 追加明細（Extra Line Items）の管理
4. 返品オーダーのステータス管理（発行、保留、キャンセル、完了）
5. バーコード操作、印刷（レポート・ラベル）
6. 添付ファイル・メモの管理

**画面遷移**：
- 遷移元：販売インデックス画面、顧客詳細画面
- 遷移先：顧客詳細画面、在庫アイテム詳細画面

**権限による表示制御**：
- `UserRoles.return_order` のView権限がない場合、本画面にアクセスできない
- `UserRoles.return_order` のChange権限がない場合、編集操作が無効化
- `UserRoles.return_order` のAdd権限がない場合、複製操作が無効化

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 18 | 返品注文管理 | 主機能 | 返品オーダーの詳細表示・編集・処理 |
| 8 | 在庫アイテム管理 | API連携 | 返品在庫の受入処理 |
| 47 | 添付ファイル管理 | 補助機能 | 添付ファイルの表示・アップロード・削除 |
| 48 | メモ・ノート管理 | 補助機能 | 返品オーダーメモの表示・編集 |

## 画面種別

詳細画面（タブ切替型）

## URL/ルーティング

| パス | 説明 |
|------|------|
| `/sales/return-order/:id/*` | 返品オーダー詳細画面（:idは返品オーダーのPK） |

## 入出力項目

### 返品オーダー編集フォーム

| 項目名 | 項目ID | データ型 | 必須 | 説明 |
|--------|--------|----------|------|------|
| 参照番号 | reference | string | ○ | 返品オーダーの参照番号（自動採番可） |
| 顧客 | customer | number | ○ | 顧客会社ID |
| 顧客参照 | customer_reference | string | - | 顧客側の参照番号 |
| 説明 | description | string | - | 返品オーダーの説明 |
| プロジェクトコード | project_code | number | - | プロジェクトコードID |
| 担当者 | responsible | number | - | 担当者（オーナー）ID |
| 返品先住所 | address | number | - | 返品先住所ID |
| 連絡先 | contact | number | - | 連絡先ID |
| 目標日 | target_date | date | - | 目標完了日 |
| 開始日 | start_date | date | - | 開始日 |
| 外部リンク | link | string | - | 外部参照URL |

## 表示項目

### 詳細パネル - 左上（基本情報）

| 項目名 | フィールド | データ型 | 説明 |
|--------|-----------|----------|------|
| 参照番号 | reference | string | 返品オーダーの参照番号（コピー可能） |
| 顧客参照 | customer_reference | string | 顧客側の参照番号 |
| 顧客 | customer | link | 顧客会社へのリンク |
| 説明 | description | string | 返品オーダーの説明 |
| ステータス | status | status | 返品オーダーステータス |
| カスタムステータス | status_custom_key | status | カスタムステータス（異なる場合のみ表示） |

### 詳細パネル - 右上（進捗・金額）

| 項目名 | フィールド | データ型 | 説明 |
|--------|-----------|----------|------|
| 明細アイテム数 | line_items | number | 明細アイテムの総数 |
| 完了明細 | completed_lines | progressbar | 明細アイテムの完了進捗 |
| 注文通貨 | order_currency | string | 注文の通貨 |
| 合計金額 | total_price | currency | 返品合計金額 |

### 詳細パネル - 左下（連絡先・プロジェクト）

| 項目名 | フィールド | データ型 | 説明 |
|--------|-----------|----------|------|
| 外部リンク | link | link | 外部参照URL |
| 返品先住所 | address_detail | address | 返品先住所 |
| 連絡先 | contact_detail.name | string | 連絡先名 |
| 連絡先メール | contact_detail.email | string | 連絡先メールアドレス |
| 連絡先電話 | contact_detail.phone | string | 連絡先電話番号 |
| プロジェクトコード | project_code_label | string | プロジェクトコード |
| 担当者 | responsible | badge | 担当者 |

### 詳細パネル - 右下（日付）

| 項目名 | フィールド | データ型 | 説明 |
|--------|-----------|----------|------|
| 作成日 | creation_date | date | 作成日 |
| 発行日 | issue_date | date | 発行日 |
| 開始日 | start_date | date | 開始日 |
| 目標日 | target_date | date | 目標完了日 |
| 完了日 | complete_date | date | 完了日 |

### タブ構成

| タブ名 | 内容 |
|--------|------|
| Order Details | 返品オーダーの詳細情報 |
| Line Items | 返品明細アイテム一覧と追加明細 |
| Parameters | パラメータ一覧 |
| Attachments | 添付ファイル一覧 |
| Notes | メモ |

## イベント仕様

### 01-返品オーダー発行ボタン押下

**トリガー**：「Issue Order」ボタンをクリック

**前提条件**：
- `UserRoles.return_order` のChange権限を保持
- ステータスがPENDINGまたはON_HOLD

**処理フロー**：
1. 確認モーダルを表示（「Issue this order」）
2. 確認後、`POST /api/order/ro/:id/issue/` を実行
3. 成功時、ステータスがIN_PROGRESSに変更
4. 画面をリフレッシュ

### 02-返品オーダー完了ボタン押下

**トリガー**：「Complete Order」ボタンをクリック

**前提条件**：
- `UserRoles.return_order` のChange権限を保持
- ステータスがIN_PROGRESS

**処理フロー**：
1. 完了確認モーダルを表示（「Mark this order as complete」）
2. 確認後、`POST /api/order/ro/:id/complete/` を実行
3. 成功時、ステータスがCOMPLETEに変更
4. 画面をリフレッシュ

### 03-返品オーダー保留ボタン押下

**トリガー**：「Hold order」メニューをクリック

**前提条件**：
- `UserRoles.return_order` のChange権限を保持
- ステータスがPENDING、PLACED、またはIN_PROGRESS

**処理フロー**：
1. 保留確認モーダルを表示
2. 確認後、`POST /api/order/ro/:id/hold/` を実行
3. 成功時、ステータスがON_HOLDに変更

### 04-返品オーダーキャンセルボタン押下

**トリガー**：「Cancel order」メニューをクリック

**前提条件**：
- `UserRoles.return_order` のChange権限を保持
- ステータスがPENDING、IN_PROGRESS、またはON_HOLD

**処理フロー**：
1. キャンセル確認モーダルを表示
2. 確認後、`POST /api/order/ro/:id/cancel/` を実行
3. 成功時、ステータスがCANCELLEDに変更

### 05-返品オーダー編集ボタン押下

**トリガー**：「Edit」ボタン/メニューをクリック

**前提条件**：`UserRoles.return_order` のChange権限を保持

**処理フロー**：
1. 編集フォームモーダルを表示
2. 各項目を編集
3. 保存ボタン押下で `PATCH /api/order/ro/:id/` を実行
4. 成功時、画面をリフレッシュ

### 06-返品オーダー複製ボタン押下

**トリガー**：「Duplicate order」メニューをクリック

**前提条件**：`UserRoles.return_order` のChange権限を保持

**処理フロー**：
1. 複製フォームモーダルを表示（参照番号以外を複製）
2. 必要に応じて編集
3. 保存ボタン押下で `POST /api/order/ro/` を実行
4. 成功時、新規作成された返品オーダーの詳細画面に遷移

### 07-返品明細アイテム追加

**トリガー**：明細タブ内の「Add line item」ボタンをクリック

**処理フロー**：
1. 明細追加フォームモーダルを表示
2. 返品アイテム情報を入力
3. 保存ボタン押下で `POST /api/order/ro-line/` を実行
4. 成功時、明細一覧をリフレッシュ

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 返品オーダー編集 | ReturnOrder | UPDATE | 返品オーダー情報の更新 |
| 返品オーダー発行 | ReturnOrder | UPDATE | ステータスをIN_PROGRESSに更新 |
| 返品オーダー保留 | ReturnOrder | UPDATE | ステータスをON_HOLDに更新 |
| 返品オーダーキャンセル | ReturnOrder | UPDATE | ステータスをCANCELLEDに更新 |
| 返品オーダー完了 | ReturnOrder | UPDATE | ステータスをCOMPLETEに更新 |
| 返品オーダー複製 | ReturnOrder | INSERT | 新規返品オーダーの作成 |
| 明細追加 | ReturnOrderLineItem | INSERT | 明細アイテムの追加 |
| 明細編集 | ReturnOrderLineItem | UPDATE | 明細アイテムの更新 |
| 明細削除 | ReturnOrderLineItem | DELETE | 明細アイテムの削除 |

### テーブル別更新項目詳細

#### ReturnOrder（返品オーダー編集時）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | reference | フォーム入力値 | 参照番号 |
| UPDATE | customer | フォーム選択値 | 顧客会社ID |
| UPDATE | customer_reference | フォーム入力値 | 顧客参照番号 |
| UPDATE | description | フォーム入力値 | 説明 |
| UPDATE | target_date | フォーム入力値 | 目標日 |
| UPDATE | start_date | フォーム入力値 | 開始日 |
| UPDATE | project_code | フォーム選択値 | プロジェクトコードID |
| UPDATE | responsible | フォーム選択値 | 担当者ID |
| UPDATE | address | フォーム選択値 | 住所ID |
| UPDATE | contact | フォーム選択値 | 連絡先ID |
| UPDATE | link | フォーム入力値 | 外部リンク |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| MSG-RO-010 | 成功 | Order issued | 返品オーダー発行成功時 |
| MSG-RO-011 | 成功 | Order placed on hold | 返品オーダー保留成功時 |
| MSG-RO-012 | 成功 | Order cancelled | 返品オーダーキャンセル成功時 |
| MSG-RO-013 | 成功 | Order completed | 返品オーダー完了成功時 |
| MSG-RO-014 | 警告 | Issue this order | 発行確認時 |
| MSG-RO-015 | 警告 | Place this order on hold | 保留確認時 |
| MSG-RO-016 | 警告 | Cancel this order | キャンセル確認時 |
| MSG-RO-017 | 警告 | Mark this order as complete | 完了確認時 |

## 例外処理

| 例外条件 | 表示内容 | 処理 |
|----------|---------|------|
| 権限不足 | InstanceDetail権限チェック | return_order権限がない場合 |
| 返品オーダー未存在 | 404エラー | 指定IDの返品オーダーが存在しない場合 |
| API通信エラー | エラー通知 | 各種操作失敗時 |
| 明細編集不可 | 編集ボタン非表示 | ステータスがCOMPLETEまたはCANCELLEDかつRETURNORDER_EDIT_COMPLETED_ORDERS設定が無効の場合 |

## 備考

- RETURNORDER_EDIT_COMPLETED_ORDERS設定により、完了済み返品オーダーの明細編集可否が制御される
- 返品オーダー通貨は、オーダー設定 > 顧客設定 > グローバルデフォルトの優先順位で決定
- 複製時、参照番号は参照番号パターンに基づいて自動生成される
- orderOpen判定はPENDING、PLACED、IN_PROGRESS、ON_HOLDのステータスで有効

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ApiEndpoints.tsx | `src/frontend/lib/enums/ApiEndpoints.tsx` | return_order関連エンドポイント（190-197行目） |
| 1-2 | ModelType.ts | `src/frontend/lib/enums/ModelType.ts` | returnorderモデルタイプ定義 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ReturnOrderDetail.tsx | `src/frontend/src/pages/sales/ReturnOrderDetail.tsx` | 画面全体の構成 |

**主要処理フロー**:
1. **61-71行目**: useInstanceフックで返品オーダーデータを取得
2. **73-82行目**: orderOpen判定（編集可能かどうかの判定）
3. **84-98行目**: 明細編集可能判定、通貨決定ロジック
4. **100-306行目**: 詳細パネルの定義
5. **308-372行目**: タブパネル定義
6. **374-384行目**: ステータスバッジ定義
7. **420-450行目**: ステータス変更モーダルの定義
8. **452-529行目**: アクションボタンの定義

#### Step 3: 関連テーブルコンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ReturnOrderLineItemTable.tsx | `src/frontend/src/tables/sales/ReturnOrderLineItemTable.tsx` | 返品明細一覧テーブル |
| 3-2 | ExtraLineItemTable.tsx | `src/frontend/src/tables/general/ExtraLineItemTable.tsx` | 追加明細一覧 |

#### Step 4: フォーム定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | ReturnOrderForms.tsx | `src/frontend/src/forms/ReturnOrderForms.tsx` | useReturnOrderFieldsフック |

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

```
ReturnOrderDetail.tsx
    │
    ├─ useInstance (返品オーダーデータ取得)
    │      └─ GET /api/order/ro/:id/
    │
    ├─ PageDetail (ページヘッダー)
    │      ├─ StatusRenderer (ステータスバッジ)
    │      └─ Actions
    │             ├─ PrimaryActionButton (Issue/Complete)
    │             ├─ AdminButton
    │             ├─ BarcodeActionDropdown
    │             ├─ PrintingActions
    │             └─ OptionsActionDropdown
    │
    └─ PanelGroup
           │
           ├─ Panel (detail)
           │      └─ ItemDetailsGrid
           │             └─ DetailsTable × 4
           │
           ├─ Panel (line-items)
           │      ├─ ReturnOrderLineItemTable
           │      └─ ExtraLineItemTable
           │
           ├─ ParametersPanel
           ├─ AttachmentPanel
           └─ NotesPanel
```

### データフロー図

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

URL /:id ────────────────────▶ useInstance ────────────────────▶ 詳細表示
                                GET /api/order/ro/:id/

Issue/Complete ──────────────▶ useCreateApiFormModal ──────────▶ ステータス更新
                                POST /api/order/ro/:id/issue/
                                POST /api/order/ro/:id/hold/
                                POST /api/order/ro/:id/cancel/
                                POST /api/order/ro/:id/complete/

Edit ────────────────────────▶ useEditApiFormModal ────────────▶ オーダー更新
                                PATCH /api/order/ro/:id/

Duplicate ───────────────────▶ useCreateApiFormModal ──────────▶ 新規作成
                                POST /api/order/ro/                → 詳細画面遷移
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ReturnOrderDetail.tsx | `src/frontend/src/pages/sales/ReturnOrderDetail.tsx` | ソース | メイン画面コンポーネント |
| ReturnOrderLineItemTable.tsx | `src/frontend/src/tables/sales/ReturnOrderLineItemTable.tsx` | ソース | 返品明細一覧テーブル |
| ReturnOrderForms.tsx | `src/frontend/src/forms/ReturnOrderForms.tsx` | ソース | フォーム定義 |
| ExtraLineItemTable.tsx | `src/frontend/src/tables/general/ExtraLineItemTable.tsx` | ソース | 追加明細一覧 |
| UseStatusCodes.tsx | `src/frontend/src/hooks/UseStatusCodes.tsx` | ソース | ステータスコード取得フック |
| SettingsStates.ts | `src/frontend/src/states/SettingsStates.ts` | ソース | グローバル設定状態 |
