# 画面設計書 108-ストア詳細画面

## 概要

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

### 本画面の処理概要

ストア詳細画面は、ECストアの基本情報と設定を表示・管理する中心的な設定画面である。

**業務上の目的・背景**：ECサイトの運営において、ストアの基本設定（名前、デフォルト通貨、リージョン、販売チャネル、ロケーションなど）は全ての業務の基盤となる。この画面でストア全体の設定を一元管理することで、効率的な運営と設定の一貫性を確保する。

**画面へのアクセス方法**：設定画面（/settings）から自動リダイレクト、またはサイドナビゲーションの「設定」>「ストア」からアクセスする。

**主要な操作・処理内容**：
1. ストア基本情報（名前、デフォルト通貨、デフォルトリージョン、デフォルト販売チャネル、デフォルトロケーション）の表示
2. 対応通貨一覧の表示と管理（追加・削除、税込価格設定）
3. 対応ロケール一覧の表示と管理（翻訳機能が有効な場合）
4. ストア情報の編集画面への遷移
5. メタデータおよびJSON生データの表示

**画面遷移**：
- 遷移元：設定トップ画面、サイドナビゲーション
- 遷移先：ストア編集画面、通貨追加画面、ロケール追加画面、リージョン詳細画面、販売チャネル詳細画面、ロケーション詳細画面

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 68 | ストアCRUD | 主機能 | ストア情報の表示 |
| 69 | ストア設定管理 | 補助機能 | ストア設定の表示 |

## 画面種別

詳細（SingleColumnPage形式）

## URL/ルーティング

- パス: `/settings/store`

## 入出力項目

本画面は表示専用のため、入力項目は存在しない。ただし、通貨セクションでは選択操作が可能。

## 表示項目

### 基本情報セクション（StoreGeneralSection）

| 項目名 | データソース | 表示形式 | 備考 |
|--------|-------------|---------|------|
| ヘッダータイトル | 固定値 | テキスト | 「ストア」 |
| サブタイトル | 固定値 | テキスト | 「ストア詳細を管理」 |
| 名前 | store.name | テキスト | ストア名 |
| デフォルト通貨 | supported_currencies.find(is_default).currency_code | バッジ+テキスト | 通貨コード+通貨名 |
| デフォルトリージョン | region.name | バッジ（リンク） | リージョン詳細へリンク |
| デフォルト販売チャネル | sales_channel.name | バッジ（リンク） | 販売チャネル詳細へリンク |
| デフォルトロケーション | stock_location.name | バッジ（リンク） | ロケーション詳細へリンク |

### 通貨セクション（StoreCurrencySection）

| 項目名 | データソース | 表示形式 | 備考 |
|--------|-------------|---------|------|
| ヘッダータイトル | 固定値 | テキスト | 「通貨」 |
| 通貨一覧 | currencies | DataTable | 名前、コード、税込価格フラグ |
| 税込価格 | is_tax_inclusive | ステータスバッジ | 緑（有効）/グレー（無効） |

### ロケールセクション（StoreLocaleSection）- 翻訳機能有効時のみ

| 項目名 | データソース | 表示形式 | 備考 |
|--------|-------------|---------|------|
| ヘッダータイトル | 固定値 | テキスト | 「ロケール」 |
| ロケール一覧 | store.supported_locales | DataTable | ロケールコード、表示名 |

## イベント仕様

### 1-編集ボタン押下（基本情報）

- トリガー：基本情報セクションのActionMenuで「編集」をクリック
- 処理内容：ストア編集画面へ遷移
- 画面遷移：/settings/store/edit

### 2-通貨追加ボタン押下

- トリガー：通貨セクションのActionMenuで「追加」をクリック
- 処理内容：通貨追加画面へ遷移
- 画面遷移：/settings/store/currencies

### 3-通貨選択

- トリガー：通貨一覧のチェックボックスをクリック
- 処理内容：選択状態を更新、CommandBarを表示
- 状態変化：選択された通貨の件数を表示、削除コマンドが有効化

### 4-通貨削除

- トリガー：CommandBarの「削除」またはアクションメニューの「削除」をクリック
- 処理内容：
  1. 確認ダイアログを表示
  2. 確認後、ストア更新APIを呼び出してsupported_currenciesから削除
  3. 成功時：トースト通知を表示
  4. 失敗時：エラートースト通知を表示
- 状態変化：通貨一覧から削除

### 5-税込価格設定トグル

- トリガー：通貨アクションメニューで「税込価格を有効/無効」をクリック
- 処理内容：
  1. ストア更新APIを呼び出してis_tax_inclusiveを更新
  2. 成功時：トースト通知を表示
  3. 失敗時：エラートースト通知を表示
- 状態変化：税込価格ステータスが更新

### 6-ロケール追加ボタン押下（翻訳機能有効時）

- トリガー：ロケールセクションのActionMenuで「追加」をクリック
- 処理内容：ロケール追加画面へ遷移
- 画面遷移：/settings/store/locales

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | store | SELECT | ストア情報の取得 |
| 画面表示 | region | SELECT | デフォルトリージョン情報の取得 |
| 画面表示 | sales_channel | SELECT | デフォルト販売チャネル情報の取得 |
| 画面表示 | stock_location | SELECT | デフォルトロケーション情報の取得 |
| 画面表示 | currency | SELECT | 対応通貨情報の取得 |
| 画面表示 | price_preference | SELECT | 税込価格設定の取得 |
| 通貨削除 | store | UPDATE | supported_currenciesを更新 |
| 税込価格設定 | store | UPDATE | supported_currenciesを更新 |

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

#### store

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | supported_currencies | 通貨削除時：該当通貨を除外した配列 | 通貨削除時 |
| UPDATE | supported_currencies | 税込価格変更時：該当通貨のis_tax_inclusiveを更新 | 税込価格設定時 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| store.toast.currenciesRemoved | 成功 | 通貨が削除されました | 通貨削除成功時 |
| store.toast.updatedTaxInclusivitySuccessfully | 成功 | 税込価格設定が更新されました | 税込価格設定更新成功時 |
| general.areYouSure | 確認 | よろしいですか？ | 削除確認ダイアログ |
| store.removeCurrencyWarning | 警告 | {count}件の通貨が削除されます | 削除確認ダイアログ |
| (APIエラー) | エラー | エラーメッセージ（API応答） | API呼び出し失敗時 |

## 例外処理

| 例外条件 | 処理内容 | ユーザーへの通知 |
|---------|---------|----------------|
| ストア情報取得失敗 | エラーをスロー | エラー画面表示 |
| 通貨情報取得失敗 | エラーをスロー | エラー画面表示 |
| 価格設定情報取得失敗 | エラーをスロー | エラー画面表示 |
| ローディング中 | スケルトン表示 | - |
| デフォルト通貨の削除試行 | 操作を無効化 | 削除ボタンがdisabled |

## 備考

- SingleColumnPage形式でシンプルなレイアウト
- 拡張ポイント（widgets）が設定されており、プラグインによる画面拡張が可能
  - store.details.before
  - store.details.after
- 翻訳機能（translation）のフィーチャーフラグが有効な場合のみロケールセクションを表示
- デフォルト通貨は削除不可
- ローダー（storeLoader）によるデータプリフェッチを実装
- 通貨のソートと検索機能あり

---

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

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

### 推奨読解順序

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

ストアデータの取得方法と構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | store.tsx | `packages/admin/dashboard/src/hooks/api/store.tsx` | 36-58行目のuseStoreでストア情報の取得方法を確認 |

**読解のコツ**: retrieveActiveStore関数でストア一覧から最初のストアを取得している。Medusa v2ではマルチテナント対応の名残りで一覧取得APIを使用。

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

画面全体の構造を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | store-detail.tsx | `packages/admin/dashboard/src/routes/store/store-detail/store-detail.tsx` | 画面全体の構成、データ取得、条件分岐、フィーチャーフラグを確認 |

**主要処理フロー**:
1. **15行目**: useLoaderDataでプリフェッチデータを取得
2. **16行目**: useFeatureFlagで翻訳機能の有効/無効を確認
3. **18-20行目**: useStoreでストアデータを取得
4. **22行目**: useExtensionでウィジェット取得関数を取得
5. **24-30行目**: ローディング・エラー状態の処理
6. **32-47行目**: SingleColumnPageで3つのセクションをレンダリング

#### Step 3: 基本情報セクションを理解する

ストア基本情報の表示を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | store-general-section.tsx | `packages/admin/dashboard/src/routes/store/store-detail/components/store-general-section/store-general-section.tsx` | 基本情報の表示項目、関連データの取得、リンク生成を確認 |

**主要処理フロー**:
- **18-20行目**: useRegionでデフォルトリージョン情報を取得
- **24-26行目**: useSalesChannelでデフォルト販売チャネル情報を取得
- **28-36行目**: useStockLocationでデフォルトロケーション情報を取得
- **38-140行目**: Container内で各情報をBadge+Textで表示

#### Step 4: 通貨セクションを理解する

通貨管理機能を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | store-currency-section.tsx | `packages/admin/dashboard/src/routes/store/store-detail/components/store-currency-section/store-currency-section.tsx` | 通貨一覧、選択、削除、税込価格設定を確認 |

**主要処理フロー**:
- **35-52行目**: useCurrenciesでストア対応通貨の詳細情報を取得
- **54-67行目**: usePricePreferencesで税込価格設定を取得
- **70-72行目**: prefMapで通貨コードと価格設定をマッピング
- **79-98行目**: useDataTableでテーブル設定
- **104-137行目**: handleDeleteCurrenciesで一括削除処理
- **200-306行目**: CurrencyActionsで個別の削除・税込価格トグル

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

```
StoreDetail (store-detail.tsx)
    │
    ├─ useStore (store.tsx)
    │      └─ retrieveActiveStore
    │             └─ sdk.admin.store.list
    │
    ├─ useFeatureFlag (feature-flag-provider)
    │
    ├─ StoreGeneralSection (store-general-section.tsx)
    │      ├─ useRegion
    │      ├─ useSalesChannel
    │      └─ useStockLocation
    │
    ├─ StoreCurrencySection (store-currency-section.tsx)
    │      ├─ useCurrencies
    │      ├─ usePricePreferences
    │      └─ useUpdateStore
    │
    └─ StoreLocaleSection (store-locale-section.tsx) [翻訳機能有効時]
```

### データフロー図

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

(storeLoader) ───▶ useStore ───▶ store データ
                        │
                        ├─▶ StoreGeneralSection ───▶ 基本情報表示
                        │       │
                        │       ├─▶ useRegion ───▶ リージョン表示
                        │       ├─▶ useSalesChannel ───▶ 販売チャネル表示
                        │       └─▶ useStockLocation ───▶ ロケーション表示
                        │
                        ├─▶ StoreCurrencySection ───▶ 通貨一覧表示
                        │       │
                        │       └─▶ useCurrencies + usePricePreferences
                        │
                        └─▶ StoreLocaleSection ───▶ ロケール一覧表示（条件付き）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| store-detail.tsx | `packages/admin/dashboard/src/routes/store/store-detail/store-detail.tsx` | ソース | 画面エントリーポイント |
| store-general-section.tsx | `packages/admin/dashboard/src/routes/store/store-detail/components/store-general-section/store-general-section.tsx` | ソース | 基本情報表示コンポーネント |
| store-currency-section.tsx | `packages/admin/dashboard/src/routes/store/store-detail/components/store-currency-section/store-currency-section.tsx` | ソース | 通貨管理コンポーネント |
| store-locale-section.tsx | `packages/admin/dashboard/src/routes/store/store-detail/components/store-locale-section/store-locale-section.tsx` | ソース | ロケール管理コンポーネント |
| loader.ts | `packages/admin/dashboard/src/routes/store/store-detail/loader.ts` | ソース | データプリフェッチローダー |
| store.tsx | `packages/admin/dashboard/src/hooks/api/store.tsx` | ソース | ストアAPI hooks |
| index.ts | `packages/admin/dashboard/src/routes/store/store-detail/index.ts` | ソース | エクスポート定義 |
