# 画面設計書 109-ストア編集画面

## 概要

本ドキュメントは、Medusa Admin Dashboard におけるストア編集画面の設計仕様を定義する。

### 本画面の処理概要

ストア編集画面は、ECストアの基本情報を編集するためのドロワー形式の画面である。

**業務上の目的・背景**：ECサイトの運営において、ストア名やデフォルト設定（通貨、リージョン、販売チャネル、ロケーション）の変更が必要になる場合がある。この画面により、管理者はストアの基本設定を迅速に更新でき、ビジネス要件の変化に対応できる。

**画面へのアクセス方法**：ストア詳細画面（/settings/store）の基本情報セクションのアクションメニューから「編集」を選択してアクセスする。

**主要な操作・処理内容**：
1. ストア名の編集
2. デフォルト通貨の変更（対応通貨から選択）
3. デフォルトリージョンの変更
4. デフォルト販売チャネルの変更
5. デフォルトロケーションの変更
6. 変更の保存

**画面遷移**：
- 遷移元：ストア詳細画面
- 遷移先：保存成功時はストア詳細画面に戻る

**権限による表示制御**：認証済みの管理者ユーザーのみアクセス可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 68 | ストアCRUD | 主機能 | ストア情報の編集 |

## 画面種別

編集（モーダル/ドロワー形式）

## URL/ルーティング

- パス: `/settings/store/edit`

## 入出力項目

| 項目名 | 項目ID | 入力/出力 | 必須 | データ型 | バリデーション | 備考 |
|--------|--------|----------|------|---------|---------------|------|
| ストア名 | name | 入力 | 必須 | string | 最小1文字 | Inputで入力 |
| デフォルト通貨 | default_currency_code | 入力 | 任意 | string | - | Selectで選択（対応通貨から） |
| デフォルトリージョン | default_region_id | 入力 | 任意 | string | - | Comboboxで検索・選択 |
| デフォルト販売チャネル | default_sales_channel_id | 入力 | 任意 | string | - | Comboboxで検索・選択 |
| デフォルトロケーション | default_location_id | 入力 | 任意 | string | - | Comboboxで検索・選択 |

## 表示項目

| 項目名 | データソース | 表示形式 | 備考 |
|--------|-------------|---------|------|
| ヘッダータイトル | 固定値 | テキスト | 「ストア編集」 |

## イベント仕様

### 1-デフォルト通貨選択

- トリガー：デフォルト通貨Selectで値を変更
- 処理内容：フォーム状態を更新
- 状態変化：選択された通貨コードがフォームに反映

### 2-デフォルトリージョン検索・選択

- トリガー：リージョンComboboxで検索または選択
- 処理内容：
  1. 検索時：APIでリージョン一覧を動的取得
  2. 選択時：フォーム状態を更新
- 状態変化：選択されたリージョンIDがフォームに反映

### 3-デフォルト販売チャネル検索・選択

- トリガー：販売チャネルComboboxで検索または選択
- 処理内容：
  1. 検索時：APIで販売チャネル一覧を動的取得
  2. 選択時：フォーム状態を更新
- 状態変化：選択された販売チャネルIDがフォームに反映

### 4-デフォルトロケーション検索・選択

- トリガー：ロケーションComboboxで検索または選択
- 処理内容：
  1. 検索時：APIでロケーション一覧を動的取得
  2. 選択時：フォーム状態を更新
- 状態変化：選択されたロケーションIDがフォームに反映

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

- トリガー：「保存」ボタンをクリック
- 処理内容：
  1. フォームバリデーション実行
  2. supported_currenciesのis_defaultフラグを更新
  3. ストア更新APIを呼び出し（useUpdateStore）
  4. 成功時：トースト通知を表示し、ドロワーを閉じる
  5. 失敗時：エラートースト通知を表示
- 画面遷移：保存成功時はストア詳細画面に戻る

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

- トリガー：「キャンセル」ボタンをクリック
- 処理内容：ドロワーを閉じる
- 画面遷移：ストア詳細画面に戻る

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | store | UPDATE | ストア情報を更新 |

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

#### store

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | name | フォーム入力値 | ストア名 |
| UPDATE | default_region_id | フォーム入力値 | デフォルトリージョンID |
| UPDATE | default_sales_channel_id | フォーム入力値 | デフォルト販売チャネルID |
| UPDATE | default_location_id | フォーム入力値 | デフォルトロケーションID |
| UPDATE | supported_currencies | is_defaultフラグを更新した配列 | デフォルト通貨の変更 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| store.toast.update | 成功 | ストアが正常に更新されました | ストア更新成功時 |
| (APIエラー) | エラー | エラーメッセージ（API応答） | API呼び出し失敗時 |

## 例外処理

| 例外条件 | 処理内容 | ユーザーへの通知 |
|---------|---------|----------------|
| ストア情報取得失敗 | エラーをスロー | エラー画面表示 |
| API通信エラー | 処理を中断 | エラートースト表示 |

## 備考

- ドロワー（RouteDrawer）形式でサイドパネルとして表示
- zodによるスキーマバリデーション（EditStoreSchema）を実装
- react-hook-formによるフォーム管理
- useComboboxDataフックを使用して、リージョン、販売チャネル、ロケーションの動的検索を実装
- デフォルト通貨の変更は、supported_currenciesの各通貨のis_defaultフラグを更新する形で実装
- フィールドのid,nameのみを取得するフィールドオプションで最適化

---

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

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

### 推奨読解順序

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

ストア編集のバリデーションスキーマを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | edit-store-form.tsx | `packages/admin/dashboard/src/routes/store/store-edit/components/edit-store-form/edit-store-form.tsx` | 21-27行目のEditStoreSchemaでバリデーションルールを確認 |

**読解のコツ**: nameはz.string().min(1)で必須、その他はz.string().optional()でオプション。

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

画面のエントリーポイントとデータ取得ロジックを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | store-edit.tsx | `packages/admin/dashboard/src/routes/store/store-edit/store-edit.tsx` | 画面構成とデータ取得フローを確認 |

**主要処理フロー**:
1. **9行目**: useStoreでストアデータを取得
2. **11-13行目**: エラー処理
3. **15行目**: データ準備完了の判定
4. **17-24行目**: RouteDrawerでドロワー表示、EditStoreFormをレンダリング

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

フォームの実装詳細を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | edit-store-form.tsx | `packages/admin/dashboard/src/routes/store/store-edit/components/edit-store-form/edit-store-form.tsx` | フォーム実装、Comboboxデータ取得、API呼び出しを確認 |

**主要処理フロー**:
- **33-44行目**: useFormでフォーム初期化（ストア情報をデフォルト値に設定）
- **46行目**: useUpdateStoreで更新mutation取得
- **48-55行目**: regionsComboboxでリージョン一覧の動的取得
- **57-64行目**: salesChannelsComboboxで販売チャネル一覧の動的取得
- **66-73行目**: locationsComboboxでロケーション一覧の動的取得
- **75-94行目**: handleSubmitでsupported_currenciesのis_default更新とAPI呼び出し

#### Step 4: API hooks を理解する

APIとの通信処理を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | store.tsx | `packages/admin/dashboard/src/hooks/api/store.tsx` | 60-83行目のuseUpdateStoreでストア更新APIの呼び出し方法とキャッシュ無効化を確認 |

**主要処理フロー**:
- **69行目**: sdk.admin.store.updateでAPI呼び出し
- **70-77行目**: 成功時のキャッシュ無効化（価格設定、ストア詳細）

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

```
StoreEdit (store-edit.tsx)
    │
    ├─ useStore (store.tsx)
    │      └─ retrieveActiveStore
    │
    └─ EditStoreForm (edit-store-form.tsx)
           │
           ├─ useComboboxData (リージョン)
           │      └─ sdk.admin.region.list
           │
           ├─ useComboboxData (販売チャネル)
           │      └─ sdk.admin.salesChannel.list
           │
           ├─ useComboboxData (ロケーション)
           │      └─ sdk.admin.stockLocation.list
           │
           └─ useUpdateStore (store.tsx)
                  └─ sdk.admin.store.update
```

### データフロー図

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

(useStore) ───▶ store データ ───▶ フォーム初期値
         │
         ├─▶ リージョン検索 ───▶ useComboboxData ───▶ リージョン選択肢
         │
         ├─▶ 販売チャネル検索 ───▶ useComboboxData ───▶ 販売チャネル選択肢
         │
         ├─▶ ロケーション検索 ───▶ useComboboxData ───▶ ロケーション選択肢
         │
         ▼
保存ボタン ─────────┬─▶ supported_currencies更新
                   │   (is_defaultフラグ調整)
                   │
                   └─▶ useUpdateStore ───▶ ストア詳細画面に戻る
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| store-edit.tsx | `packages/admin/dashboard/src/routes/store/store-edit/store-edit.tsx` | ソース | 画面エントリーポイント |
| edit-store-form.tsx | `packages/admin/dashboard/src/routes/store/store-edit/components/edit-store-form/edit-store-form.tsx` | ソース | フォーム実装、バリデーション、API呼び出し |
| store.tsx | `packages/admin/dashboard/src/hooks/api/store.tsx` | ソース | ストアAPI hooks |
| use-combobox-data.tsx | `packages/admin/dashboard/src/hooks/use-combobox-data.tsx` | ソース | Combobox動的データ取得フック |
| index.ts | `packages/admin/dashboard/src/routes/store/store-edit/index.ts` | ソース | エクスポート定義 |
