# 画面設計書 45-出荷作成画面

## 概要

本ドキュメントは、Medusa管理画面における出荷作成画面の設計を記載する。本画面は、フルフィルメントに対して出荷情報（追跡番号、追跡URL、ラベルURL）を登録し、出荷を完了させるためのモーダル形式の画面である。

### 本画面の処理概要

**業務上の目的・背景**：フルフィルメントが作成された後、実際に商品を出荷する際には追跡情報を登録する必要がある。本画面は、配送業者の追跡番号やラベル情報を登録し、フルフィルメントを「shipped」状態に更新する機能を提供する。これにより、顧客は追跡情報を通じて配送状況を確認できるようになる。

**画面へのアクセス方法**：注文詳細画面（/orders/{id}）のフルフィルメントセクションから、特定のフルフィルメントに対して「Create Shipment」アクションを選択することでアクセス。

**主要な操作・処理内容**：
1. 追跡番号の入力：配送業者から発行された追跡番号を入力
2. 追跡URLの入力：配送追跡ページのURLを入力
3. ラベルURLの入力：配送ラベルのダウンロードURLを入力
4. 追加ラベルの追加：複数の追跡情報を登録する場合に追加
5. 通知設定：顧客への通知を送信するかどうかを設定
6. 出荷の作成：設定内容で出荷を作成

**画面遷移**：
- 遷移元：注文詳細画面（/orders/{id}）
- 遷移先：注文詳細画面（出荷作成完了後）

**権限による表示制御**：管理者権限を持つユーザーのみがアクセス可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| F-001 | 出荷作成 | 主機能 | 出荷情報の登録とフルフィルメントステータス更新 |
| F-002 | 追跡情報登録 | 補助機能 | 追跡番号・URL・ラベルURLの登録 |

## 画面種別

モーダル（RouteFocusModal）

## URL/ルーティング

```
/orders/:id/fulfillments/:f_id/create-shipment
```

## 入出力項目

| 項目名 | 入出力 | 型 | 必須 | 説明 |
|--------|--------|-----|------|------|
| id | 入力 | string | ○ | 注文ID（URLパラメータ） |
| f_id | 入力 | string | ○ | フルフィルメントID（URLパラメータ） |
| labels | 入力 | array | × | 追跡情報配列 |
| labels[].tracking_number | 入力 | string | × | 追跡番号 |
| labels[].tracking_url | 入力 | string | × | 追跡URL |
| labels[].label_url | 入力 | string | × | ラベルURL |
| send_notification | 入力 | boolean | × | 顧客への通知送信フラグ |

## 表示項目

| 項目名 | 表示名 | 型 | 説明 |
|--------|--------|-----|------|
| labels[].tracking_number | Tracking Number | input | 追跡番号入力フィールド |
| labels[].tracking_url | Tracking URL | input | 追跡URL入力フィールド |
| labels[].label_url | Label URL | input | ラベルURL入力フィールド |
| send_notification | Send Notification | switch | 通知送信スイッチ |

## イベント仕様

### 1-追跡情報追加

「Add Tracking」ボタンをクリックすると、新しい追跡情報入力行が追加される。

- 処理: `useFieldArray`の`append`関数で空の追跡情報オブジェクトを追加
- 追加されるデフォルト値:
  ```json
  {
    "tracking_number": "",
    "tracking_url": "",
    "label_url": ""
  }
  ```

### 2-出荷作成

「Save」ボタンをクリックすると、出荷が作成される。

- API呼び出し: `POST /admin/orders/{id}/fulfillments/{f_id}/shipments`
- リクエストボディ:
  ```json
  {
    "items": [{ "id": "line_item_id", "quantity": 1 }],
    "labels": [
      {
        "tracking_number": "123-456-789",
        "tracking_url": "https://...",
        "label_url": "https://..."
      }
    ],
    "no_notification": false
  }
  ```
- 空の追跡情報はフィルタリングされる
- 既存のラベル情報とマージされる
- 成功時: トースト通知で成功メッセージを表示し、注文詳細画面へ遷移
- エラー時: トースト通知でエラーメッセージを表示

### 3-キャンセル

「Cancel」ボタンをクリックすると、モーダルを閉じて注文詳細画面に戻る。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | order | SELECT | 注文データの取得 |
| 画面表示 | fulfillment | SELECT | フルフィルメントデータの取得 |
| 出荷作成 | fulfillment | UPDATE | shipped_atの更新 |
| 出荷作成 | fulfillment_label | INSERT | 追跡情報の登録 |

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

#### fulfillment

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | shipped_at | 現在日時 | 出荷日時 |

#### fulfillment_label

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | fulfillment_id | フルフィルメントID | 対象フルフィルメント |
| INSERT | tracking_number | 入力値 | 追跡番号 |
| INSERT | tracking_url | 入力値または"#" | 追跡URL |
| INSERT | label_url | 入力値または"#" | ラベルURL |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|----------|
| orders.shipment.toastCreated | 成功 | Shipment created | 出荷作成成功時 |
| エラーメッセージ | エラー | API返却のエラーメッセージ | API呼び出しエラー時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 注文が見つからない | エラーをthrowしてエラーバウンダリで処理 |
| フルフィルメントが見つからない | フォームが表示されない |
| API呼び出しエラー | トースト通知でエラーメッセージを表示 |

## 備考

- 追跡URL・ラベルURLが空の場合は"#"が設定される
- 既存のラベル情報は保持され、新しいラベルとマージされる
- send_notificationのデフォルト値は、注文のno_notificationフラグの逆値
- レスポンシブ対応：モバイル表示時はラベルが各入力フィールドに表示される

---

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

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

### 推奨読解順序

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

まず、出荷作成に必要なデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | constants.ts | `packages/admin/dashboard/src/routes/orders/order-create-shipment/components/order-create-shipment-form/constants.ts` | CreateShipmentSchemaでバリデーションスキーマを確認 |

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

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

**主要処理フロー**:
1. **行8**: `useParams`で注文IDとフルフィルメントIDを取得
2. **行10-12**: `useOrder`で注文データを取得（fulfillments関連を含む）
3. **行23-26**: `OrderCreateShipmentForm`コンポーネントをレンダリング

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

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

**主要処理フロー**:
- **行30-31**: `useCreateOrderShipment`でAPIフック取得
- **行33-38**: `useForm`でフォーム状態管理
- **行40-43**: `useFieldArray`でlabels配列を管理
- **行45-72**: `handleSubmit`で出荷作成処理
- **行46-52**: 追跡情報のフィルタリングとデフォルト値設定
- **行169-182**: 「Add Tracking」ボタンで追跡情報を追加

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

```
OrderCreateShipment (order-create-shipment.tsx)
    │
    ├─ useParams (id, f_id)
    ├─ useOrder (注文データ + fulfillments)
    │
    └─ OrderCreateShipmentForm
           │
           ├─ useCreateOrderShipment (APIフック)
           ├─ useForm (フォーム状態)
           ├─ useFieldArray (labels配列)
           │
           └─ handleSubmit
                  └─ createShipment → API呼び出し
```

### データフロー図

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

URLパラメータ ───▶ useParams ──────────────▶ id, f_id
                          │
                          ▼
注文ID ──────────▶ useOrder ──────────────▶ order, fulfillment
                          │
                          ▼
フォーム入力 ────▶ handleSubmit ───────────▶ API呼び出し
                          │
                          ├─ フィルタリング（空の追跡情報除去）
                          ├─ デフォルト値設定（"#"）
                          └─ 既存ラベルとマージ
                          │
                          ▼
API結果 ─────────▶ toast/navigate ─────────▶ フィードバック/遷移
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| order-create-shipment.tsx | `packages/admin/dashboard/src/routes/orders/order-create-shipment/order-create-shipment.tsx` | ソース | ページコンポーネント |
| order-create-shipment-form.tsx | `packages/admin/dashboard/src/routes/orders/order-create-shipment/components/order-create-shipment-form/order-create-shipment-form.tsx` | ソース | フォームコンポーネント |
| constants.ts | `packages/admin/dashboard/src/routes/orders/order-create-shipment/components/order-create-shipment-form/constants.ts` | ソース | 定数・スキーマ定義 |
| orders.tsx | `packages/admin/dashboard/src/hooks/api/orders.tsx` | ソース | API呼び出しフック |
