# 画面設計書 48-クレーム作成画面

## 概要

本ドキュメントは、Medusa管理画面におけるクレーム作成画面の設計を記載する。本画面は、注文に対するクレーム（商品の不良・破損等による補償）を作成するためのモーダル形式の画面であり、返送商品（Inbound）の選択と代替商品（Outbound）の追加、それぞれの配送設定を行う。

### 本画面の処理概要

**業務上の目的・背景**：ECサイト運営において、商品の不良や破損等の問題が発生した場合、顧客への補償としてクレーム処理が必要となる。本画面は、問題のある商品を返送してもらい、代わりに新しい商品を発送する「交換型クレーム」を作成する機能を提供する。クレーム作成後は、商品の受領処理や返金・追加請求等の処理が可能となる。

**画面へのアクセス方法**：注文詳細画面（/orders/{id}）のサマリーセクションから「Create Claim」アクションを選択することでアクセス。画面表示時に自動的にクレームリクエストが初期化される。

**主要な操作・処理内容**：
1. 返送商品（Inbound）の追加：返送対象の商品を選択し、数量・理由を設定
2. 返送先ロケーションの選択：商品を受け取る倉庫・店舗を選択
3. 返送用配送オプションの設定：返送用の配送方法と送料を設定
4. 代替商品（Outbound）の追加：発送する代替商品を選択し、数量を設定
5. 発送用配送オプションの設定：代替商品の配送方法と送料を設定
6. クレームリクエストの確定：設定内容でクレームを確定

**画面遷移**：
- 遷移元：注文詳細画面（/orders/{id}）
- 遷移先：注文詳細画面（クレーム作成完了またはキャンセル後）

**権限による表示制御**：管理者権限を持つユーザーのみがアクセス可能。他のアクティブな変更がある場合はエラー表示されリダイレクト。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| F-001 | クレーム作成 | 主機能 | クレームリクエストの初期化と確定 |
| F-002 | 返送商品追加 | 補助機能 | 返送対象商品の追加 |
| F-003 | 返送商品更新 | 補助機能 | 返送数量・理由の更新 |
| F-004 | 返送商品削除 | 補助機能 | 返送対象商品の削除 |
| F-005 | 代替商品追加 | 補助機能 | 代替商品の追加 |
| F-006 | 代替商品更新 | 補助機能 | 代替商品数量の更新 |
| F-007 | 代替商品削除 | 補助機能 | 代替商品の削除 |
| F-008 | 返送送料設定 | 補助機能 | 返送用配送オプションの設定 |
| F-009 | 発送送料設定 | 補助機能 | 代替商品配送オプションの設定 |

## 画面種別

モーダル（RouteFocusModal）

## URL/ルーティング

```
/orders/:id/claims
```

## 入出力項目

| 項目名 | 入出力 | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| id | 入力 | string | ○ | 注文ID（URLパラメータ） |
| inbound_items | 入力 | array | × | 返送対象商品配列 |
| inbound_items[].item_id | 入力 | string | ○ | 商品ID |
| inbound_items[].quantity | 入力 | number | ○ | 返送数量 |
| inbound_items[].reason_id | 入力 | string | × | 返送理由ID |
| inbound_items[].note | 入力 | string | × | 内部メモ |
| outbound_items | 入力 | array | × | 代替商品配列 |
| outbound_items[].variant_id | 入力 | string | ○ | バリアントID |
| outbound_items[].quantity | 入力 | number | ○ | 発送数量 |
| location_id | 入力 | string | × | 返送先ロケーションID |
| inbound_option_id | 入力 | string | × | 返送配送オプションID |
| outbound_option_id | 入力 | string | × | 発送配送オプションID |
| send_notification | 入力 | boolean | × | 顧客への通知送信フラグ |

## 表示項目

| 項目名 | 表示名 | 型 | 説明 |
|--------|--------|-----|------|
| inbound_items | Inbound Items | list | 返送対象商品一覧 |
| inbound_items[].thumbnail | - | image | 商品サムネイル |
| inbound_items[].title | Title | string | 商品名 |
| inbound_items[].quantity | Quantity | number | 返送数量（入力） |
| inbound_items[].reason | Reason | select | 返送理由選択 |
| inbound_items[].note | Note | input | 内部メモ |
| outbound_items | Outbound Items | list | 代替商品一覧 |
| outbound_items[].thumbnail | - | image | 商品サムネイル |
| outbound_items[].title | Title | string | 商品名 |
| outbound_items[].quantity | Quantity | number | 発送数量（入力） |
| location_id | Location | select | 返送先ロケーション選択 |
| inbound_option_id | Inbound Shipping | select | 返送配送オプション選択 |
| outbound_option_id | Outbound Shipping | select | 発送配送オプション選択 |
| inbound_total | Inbound Total | number | 返送商品合計金額 |
| outbound_total | Outbound Total | number | 代替商品合計金額 |
| inbound_shipping | Inbound Shipping | number | 返送送料 |
| outbound_shipping | Outbound Shipping | number | 発送送料 |
| refund_amount | Refund Amount | number | 返金/追加請求金額 |
| send_notification | Send Notification | switch | 通知送信スイッチ |

## イベント仕様

### 1-返送商品追加

「Add Items」リンク（Inboundセクション）をクリックすると、商品選択モーダルが表示される。商品を選択して「Save」をクリックすると、返送対象商品が追加される。

- API呼び出し: `POST /admin/claims/{claim_id}/inbound/items`
- リクエストボディ:
  ```json
  {
    "items": [{ "id": "item_xxx", "quantity": 1 }]
  }
  ```

### 2-返送商品更新

返送商品の数量や理由を変更すると、クレームリクエストが更新される。

- API呼び出し: `POST /admin/claims/{claim_id}/inbound/items/{action_id}`
- リクエストボディ:
  ```json
  {
    "quantity": 2,
    "reason_id": "reason_xxx",
    "internal_note": "note"
  }
  ```

### 3-返送商品削除

返送商品の削除ボタンをクリックすると、返送対象から除外される。

- API呼び出し: `DELETE /admin/claims/{claim_id}/inbound/items/{action_id}`

### 4-ロケーション変更

ロケーションを変更すると、関連する返品リクエストのlocation_idが更新される。

- API呼び出し: `POST /admin/returns/{return_id}`
- 連動: 返送用配送オプションがロケーションでフィルタリングされる

### 5-返送配送オプション変更

返送配送オプションを変更すると、既存の返送送料が削除され、新しい配送オプションが設定される。

- API呼び出し（削除）: `DELETE /admin/claims/{claim_id}/inbound/shipping-method/{action_id}`
- API呼び出し（追加）: `POST /admin/claims/{claim_id}/inbound/shipping-method`

### 6-返送送料カスタマイズ

返送送料の編集アイコンをクリックすると、カスタム送料を入力できる。

- API呼び出し: `POST /admin/claims/{claim_id}/inbound/shipping-method/{action_id}`
- リクエストボディ:
  ```json
  {
    "custom_amount": 500
  }
  ```

### 7-代替商品追加

「Add Items」リンク（Outboundセクション）をクリックすると、商品選択モーダルが表示される。バリアントを選択して「Save」をクリックすると、代替商品が追加される。

- API呼び出し: `POST /admin/claims/{claim_id}/outbound/items`
- リクエストボディ:
  ```json
  {
    "items": [{ "variant_id": "variant_xxx", "quantity": 1 }]
  }
  ```

### 8-代替商品更新

代替商品の数量を変更すると、クレームリクエストが更新される。

- API呼び出し: `POST /admin/claims/{claim_id}/outbound/items/{action_id}`

### 9-代替商品削除

代替商品の削除ボタンをクリックすると、発送対象から除外される。

- API呼び出し: `DELETE /admin/claims/{claim_id}/outbound/items/{action_id}`

### 10-発送配送オプション変更

発送配送オプションを変更すると、既存の発送送料が削除され、新しい配送オプションが設定される。

- API呼び出し（削除）: `DELETE /admin/claims/{claim_id}/outbound/shipping-method/{action_id}`
- API呼び出し（追加）: `POST /admin/claims/{claim_id}/outbound/shipping-method`

### 11-発送送料カスタマイズ

発送送料の編集アイコンをクリックすると、カスタム送料を入力できる。

- API呼び出し: `POST /admin/claims/{claim_id}/outbound/shipping-method/{action_id}`
- リクエストボディ:
  ```json
  {
    "custom_amount": 500
  }
  ```

### 12-クレーム確定

「Confirm」ボタンをクリックすると、確認ダイアログ表示後、クレームが確定される。

- 確認ダイアログ: 「Are you sure?」メッセージを表示
- API呼び出し: `POST /admin/claims/{claim_id}/request`
- 成功時: モーダルを閉じて注文詳細画面へ遷移、成功トーストを表示
- エラー時: トースト通知でエラーメッセージを表示

### 13-キャンセル

「Cancel」ボタンをクリックまたはモーダルを閉じると、クレームリクエストがキャンセルされる。

- API呼び出し: `POST /admin/claims/{claim_id}/cancel`
- 成功時: 成功トーストを表示

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | order | SELECT | 注文データの取得 |
| クレーム初期化 | claim | INSERT | クレームの作成 |
| クレーム初期化 | return | INSERT | 返品リクエストの作成 |
| クレーム初期化 | order_change | INSERT | 注文変更の作成 |
| 返送商品追加 | order_change_action | INSERT | 返送アクションの追加 |
| 返送商品更新 | order_change_action | UPDATE | 返送アクションの更新 |
| 返送商品削除 | order_change_action | DELETE | 返送アクションの削除 |
| 代替商品追加 | order_change_action | INSERT | 発送アクションの追加 |
| 代替商品更新 | order_change_action | UPDATE | 発送アクションの更新 |
| 代替商品削除 | order_change_action | DELETE | 発送アクションの削除 |
| クレーム確定 | claim | UPDATE | ステータス更新 |
| クレーム確定 | order_change | UPDATE | 変更の確定 |
| キャンセル | claim | UPDATE | ステータス更新 |
| キャンセル | order_change | DELETE | 変更の削除 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|----------|
| orders.claims.confirmText | 確認 | Are you sure you want to confirm this claim? | クレーム確定前 |
| orders.claims.toast.confirmedSuccessfully | 成功 | Claim confirmed successfully | クレーム確定成功時 |
| orders.claims.activeChangeError | エラー | There is an active change on this order | 他の変更がアクティブな場合 |
| orders.claims.actions.cancelClaim.successToast | 成功 | Claim cancelled | キャンセル成功時 |
| orders.returns.noInventoryLevel | 警告 | No inventory level | 在庫レベルが設定されていない場合 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 他のアクティブな変更がある | エラートースト表示し、注文詳細画面へリダイレクト |
| クレーム初期化失敗 | エラートースト表示し、注文詳細画面へリダイレクト |
| API呼び出しエラー | トースト通知でエラーメッセージを表示 |
| モーダルクローズ | 未確定の場合、クレームリクエストをキャンセル |

## 備考

- 画面表示時に自動的にクレームリクエストが初期化される（createClaim API呼び出し、type: "replace"）
- 既存のアクティブなクレーム変更がある場合は、その変更を継続して編集できる
- クレームには関連する返品リクエスト（return）が自動的に作成される
- 在庫レベルが設定されていない商品には警告が表示される
- カスタム送料は通貨に応じた小数点桁数で設定される
- 返金/追加請求金額は、返送商品合計と代替商品合計の差額で計算される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | claim-create.tsx | `packages/admin/dashboard/src/routes/orders/order-create-claim/claim-create.tsx` | ページコンポーネントの構成を確認 |

**主要処理フロー**:
1. **行16**: `useParams`で注文ID取得
2. **行20-22**: `useOrder`で注文データ取得
3. **行24**: `useOrderPreview`で注文プレビュー取得
4. **行26**: `useCreateClaim`でクレーム作成フック取得
5. **行28-30**: `useClaim`でクレームデータ取得
6. **行31-33**: `useReturn`で関連する返品データ取得
7. **行35-70**: `useEffect`でクレームリクエストの初期化処理

#### Step 2: フォームコンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | claim-create-form.tsx | `packages/admin/dashboard/src/routes/orders/order-create-claim/components/claim-create-form/claim-create-form.tsx` | フォームの実装詳細 |

**主要処理フロー**:
- **行109-110**: `useClaimConfirmRequest`でクレーム確定フック取得
- **行112-113**: `useCancelClaimRequest`でキャンセルフック取得
- **行117-120**: `useUpdateReturn`で返品更新フック取得
- **行122-149**: 各種配送・商品操作フック取得
- **行379-405**: `handleSubmit`で確認ダイアログと確定処理
- **行407-438**: `onItemsSelected`で返送商品追加処理
- **行440-442**: `onLocationChange`でロケーション変更処理
- **行444-479**: `onShippingOptionChange`で配送オプション変更処理

#### Step 3: アウトバウンドセクションを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | claim-outbound-section.tsx | `packages/admin/dashboard/src/routes/orders/order-create-claim/components/claim-create-form/claim-outbound-section.tsx` | 代替商品セクションの実装 |

**主要処理フロー**:
- **行70-91**: 代替商品操作フック取得
- **行164-195**: `onItemsSelected`で代替商品追加処理
- **行197-232**: `onShippingOptionChange`で発送配送オプション変更処理

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

```
ClaimCreate (claim-create.tsx)
    │
    ├─ useParams (id)
    ├─ useOrder (注文データ)
    ├─ useOrderPreview (プレビュー)
    ├─ useCreateClaim (クレーム作成)
    ├─ useClaim (クレームデータ)
    ├─ useReturn (返品データ)
    │
    └─ ClaimCreateForm
           │
           ├─ useClaimConfirmRequest
           ├─ useCancelClaimRequest
           ├─ useUpdateReturn
           ├─ useAddClaimInboundShipping
           ├─ useUpdateClaimInboundShipping
           ├─ useDeleteClaimInboundShipping
           ├─ useUpdateClaimOutboundShipping
           ├─ useAddClaimInboundItems
           ├─ useUpdateClaimInboundItem
           ├─ useRemoveClaimInboundItem
           ├─ useStockLocations
           ├─ useShippingOptions
           │
           ├─ ClaimInboundItem (返送商品)
           │
           └─ ClaimOutboundSection
                  │
                  ├─ useAddClaimOutboundItems
                  ├─ useUpdateClaimOutboundItems
                  ├─ useRemoveClaimOutboundItem
                  ├─ useAddClaimOutboundShipping
                  ├─ useDeleteClaimOutboundShipping
                  ├─ useOrderShippingOptions
                  │
                  └─ ClaimOutboundItem (代替商品)
```

### データフロー図

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

URLパラメータ ───▶ useParams ──────────────▶ orderId
                          │
                          ▼
画面表示 ────────▶ createClaim ─────────────▶ クレーム作成
                          │
                          ▼
操作（Inbound）──▶ 返送商品API ─────────────▶ クレーム更新
                          │
                          ▼
操作（Outbound）─▶ 代替商品API ─────────────▶ クレーム更新
                          │
                          ▼
確定ボタン ──────▶ confirmClaimRequest ────▶ クレーム確定
                          │
                          ▼
キャンセル ──────▶ cancelClaimRequest ─────▶ クレーム取消
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| claim-create.tsx | `packages/admin/dashboard/src/routes/orders/order-create-claim/claim-create.tsx` | ソース | ページコンポーネント |
| claim-create-form.tsx | `packages/admin/dashboard/src/routes/orders/order-create-claim/components/claim-create-form/claim-create-form.tsx` | ソース | フォームコンポーネント |
| claim-outbound-section.tsx | `packages/admin/dashboard/src/routes/orders/order-create-claim/components/claim-create-form/claim-outbound-section.tsx` | ソース | 代替商品セクション |
| claim-inbound-item.tsx | `packages/admin/dashboard/src/routes/orders/order-create-claim/components/claim-create-form/claim-inbound-item.tsx` | ソース | 返送商品コンポーネント |
| claim-outbound-item.tsx | `packages/admin/dashboard/src/routes/orders/order-create-claim/components/claim-create-form/claim-outbound-item.tsx` | ソース | 代替商品コンポーネント |
| add-claim-items-table.tsx | `packages/admin/dashboard/src/routes/orders/order-create-claim/components/add-claim-items-table/add-claim-items-table.tsx` | ソース | 返送商品選択テーブル |
| add-claim-outbound-items-table.tsx | `packages/admin/dashboard/src/routes/orders/order-create-claim/components/add-claim-outbound-items-table/add-claim-outbound-items-table.tsx` | ソース | 代替商品選択テーブル |
| schema.ts | `packages/admin/dashboard/src/routes/orders/order-create-claim/components/claim-create-form/schema.ts` | ソース | バリデーションスキーマ |
| claims.tsx | `packages/admin/dashboard/src/hooks/api/claims.tsx` | ソース | API呼び出しフック |
