# 画面設計書 137-サービスゾーン編集画面

## 概要

本ドキュメントは、Medusa Admin Dashboardにおけるサービスゾーン編集画面の設計仕様を定義するものである。

### 本画面の処理概要

サービスゾーン編集画面は、既存のサービスゾーンの名前を変更するための画面である。

**業務上の目的・背景**：ECサイト運営において、サービスゾーンの名称を変更する必要が生じることがある。例えば、配送エリアの見直しに伴い「国内配送」を「本州配送」に変更するなどのケースに対応する。この画面では名前の変更のみを行い、対象国の変更は別の「エリア管理画面」で行う設計となっている。

**画面へのアクセス方法**：ロケーション詳細画面 > サービスゾーンのアクションメニュー > 「Edit」をクリックすることでアクセスできる。URLパスは `/settings/locations/{location_id}/fulfillment-set/{fset_id}/service-zone/{zone_id}/edit`。

**主要な操作・処理内容**：
1. サービスゾーン名の編集（必須）
2. 「保存」ボタンで変更を反映
3. 「キャンセル」ボタンで操作を中断

**画面遷移**：
- 遷移元：ロケーション詳細画面（`/settings/locations/{location_id}`）
- 遷移先：保存完了後、ロケーション詳細画面へ自動的に戻る

**権限による表示制御**：管理者権限を持つユーザーのみがこの画面にアクセスし、サービスゾーン名を編集できる。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 42 | サービスゾーン管理 | 主機能 | サービスゾーンの編集 |

## 画面種別

編集画面（ドロワー形式）

## URL/ルーティング

- パス: `/settings/locations/:location_id/fulfillment-set/:fset_id/service-zone/:zone_id/edit`
- コンポーネント: `LocationServiceZoneEdit`
- ルートファイル: `packages/admin/dashboard/src/routes/locations/location-service-zone-edit/location-service-zone-edit.tsx`

## 入出力項目

| 項目名 | 項目ID | 入出力 | 型 | 必須 | バリデーション | 説明 |
|--------|--------|--------|-----|------|---------------|------|
| サービスゾーン名 | name | 入力 | string | Yes | 1文字以上 | サービスゾーンの名称 |

## 表示項目

| 項目名 | 説明 |
|--------|------|
| ヘッダータイトル | 「Edit Service Zone」（翻訳キー: `stockLocations.serviceZones.edit.header`） |
| ヒントメッセージ | サービスゾーンの設定についてのヒント |

## イベント仕様

### 1-保存ボタン押下

**トリガー**: 「Save」ボタンのクリック、または `Cmd/Ctrl + Enter` キーボードショートカット

**処理フロー**:
1. フォームバリデーションを実行
2. バリデーション成功時、`useUpdateFulfillmentSetServiceZone`フックを通じてAPIを呼び出し
3. APIリクエスト: `POST /admin/fulfillment-sets/{fset_id}/service-zones/{zone_id}`
4. 成功時: トースト通知を表示し、ロケーション詳細画面へ遷移
5. 失敗時: エラーメッセージをトースト通知で表示

**送信データ**:
```typescript
{
  name: string
}
```

### 2-キャンセルボタン押下

**トリガー**: 「Cancel」ボタンのクリック

**処理フロー**:
1. ドロワーを閉じる
2. ロケーション詳細画面に戻る

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | service_zone | UPDATE | サービスゾーン名の更新 |

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

#### service_zone

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | name | フォーム入力値 | サービスゾーン名 |
| UPDATE | updated_at | システム自動設定 | 更新日時 |

## メッセージ仕様

| メッセージ種別 | メッセージキー | 表示条件 | 表示内容 |
|--------------|---------------|----------|---------|
| 成功 | stockLocations.serviceZones.edit.successToast | 更新成功時 | 「{name} updated successfully」 |
| エラー | - | API呼び出し失敗時 | APIから返却されたエラーメッセージ |
| バリデーション | - | 名前未入力時 | 該当フィールドにエラー表示 |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| サービスゾーンが見つからない | 404エラーをスロー |
| ネットワークエラー | トースト通知でエラーメッセージを表示 |
| サーバーエラー（5xx） | トースト通知でエラーメッセージを表示 |
| 認証エラー（401） | ログイン画面へリダイレクト |

## 備考

- 画面はドロワー（`RouteDrawer`）として実装されている
- フォームは`react-hook-form`と`zod`によるバリデーションを使用
- 名前のみの編集に特化したシンプルな画面
- 対象国（エリア）の変更は「エリア管理画面」で行う
- `InlineTip`コンポーネントでユーザーへのヒントを表示
- `prev`プロパティでドロワーを閉じた際の遷移先を指定

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | edit-service-zone-form.tsx | `packages/admin/dashboard/src/routes/locations/location-service-zone-edit/components/edit-region-form/edit-service-zone-form.tsx` | L18-20: `EditServiceZoneSchema`でフォームスキーマを定義。名前のみ |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | location-service-zone-edit.tsx | `packages/admin/dashboard/src/routes/locations/location-service-zone-edit/location-service-zone-edit.tsx` | L9-47: URLパラメータからzone_idを取得し、サービスゾーンを検索 |

**主要処理フロー**:
1. **L11**: `useParams`でURLパラメータを取得
2. **L13-16**: `useStockLocation`でロケーションとサービスゾーン情報を取得
3. **L18-20**: URLのzone_idに一致するサービスゾーンを検索
4. **L22-27**: サービスゾーンが見つからない場合は404エラー
5. **L38-44**: フォームコンポーネントを表示

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | edit-service-zone-form.tsx | `packages/admin/dashboard/src/routes/locations/location-service-zone-edit/components/edit-region-form/edit-service-zone-form.tsx` | L22-105: フォーム初期化、API呼び出し |

**主要処理フロー**:
- **L30-34**: `useForm`でフォーム状態を初期化、既存の名前をデフォルト値として設定
- **L36-37**: `useUpdateFulfillmentSetServiceZone`フックでAPI呼び出し関数を取得
- **L39-58**: `handleSubmit`で名前を更新してAPI呼び出し

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

```
LocationServiceZoneEdit (location-service-zone-edit.tsx)
    │
    ├─ useStockLocation (サービスゾーン情報取得)
    │
    └─ EditServiceZoneForm (edit-service-zone-form.tsx)
           │
           ├─ useForm (react-hook-form)
           │      └─ defaultValues (既存サービスゾーン名)
           │
           └─ useUpdateFulfillmentSetServiceZone
                  └─ POST /admin/fulfillment-sets/{fset_id}/service-zones/{zone_id}
```

### データフロー図

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

既存データ取得 ───▶ useStockLocation ───▶ フォーム初期値設定
                                              │
名前編集 ─────────▶ zodバリデーション ───▶ バリデーションエラー表示
      │
      └─(save)──▶ useUpdateFulfillmentSetServiceZone
                          │
                          ├─(success)──▶ toast.success + 詳細画面遷移
                          │
                          └─(error)──▶ toast.error
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| location-service-zone-edit.tsx | `packages/admin/dashboard/src/routes/locations/location-service-zone-edit/location-service-zone-edit.tsx` | ソース | 画面エントリーポイント |
| edit-service-zone-form.tsx | `packages/admin/dashboard/src/routes/locations/location-service-zone-edit/components/edit-region-form/edit-service-zone-form.tsx` | ソース | フォームコンポーネント |
| fulfillment-sets.tsx | `packages/admin/dashboard/src/hooks/api/fulfillment-sets.tsx` | ソース | フルフィルメントセットAPI |
