# 画面設計書 110-通貨追加画面

## 概要

本ドキュメントは、Medusa Admin Dashboard における通貨追加画面の設計仕様を定義する。

### 本画面の処理概要

通貨追加画面は、ECストアで対応する通貨を追加するためのフォーカスモーダル形式の画面である。

**業務上の目的・背景**：ECサイトのグローバル展開において、複数の通貨での価格表示・決済が必要になる。この画面により、管理者はストアでサポートする通貨を簡単に追加でき、各通貨に対して税込価格設定を個別に行うことができる。

**画面へのアクセス方法**：ストア詳細画面（/settings/store）の通貨セクションの「通貨を追加」ボタンからアクセスする。

**主要な操作・処理内容**：
1. 追加可能な通貨一覧の表示
2. 通貨の検索・フィルタリング
3. 追加する通貨の選択（複数選択可）
4. 各通貨の税込価格設定の切り替え
5. 選択した通貨の保存

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 67 | 通貨CRUD | 主機能 | ストアに通貨を追加 |

## 画面種別

作成（モーダル/フォーカスモーダル形式）

## URL/ルーティング

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

## 入出力項目

| 項目名 | 項目ID | 入力/出力 | 必須 | データ型 | バリデーション | 備考 |
|--------|--------|----------|------|---------|---------------|------|
| 通貨選択 | currencies | 入力 | 必須 | string[] | 最小1件 | チェックボックスで複数選択 |
| 税込価格設定 | pricePreferences | 入力 | 任意 | Record<string, boolean> | - | 各通貨ごとのSwitch |

## 表示項目

| 項目名 | データソース | 表示形式 | 備考 |
|--------|-------------|---------|------|
| 通貨名 | currencies API | テキスト | 通貨の表示名 |
| 通貨コード | currencies API | テキスト | ISO 4217形式 |
| 税込価格設定 | pricePreferences API | Switch | 追加済み通貨は無効 |

## イベント仕様

### 1-通貨検索

- トリガー：検索ボックスに入力
- 処理内容：入力値で通貨一覧をフィルタリング
- 状態変化：検索結果に該当する通貨のみ表示

### 2-通貨ソート

- トリガー：ソートオプション（名前またはコード）を選択
- 処理内容：選択したキーで通貨一覧をソート
- 状態変化：ソート順に従って一覧を再表示

### 3-通貨選択

- トリガー：通貨行のチェックボックスをクリック
- 処理内容：
  1. 選択状態を更新
  2. フォームのcurrenciesフィールドを更新
- 状態変化：選択された通貨がフォームに反映
- 備考：既に追加済みの通貨は選択不可（Tooltipで通知）

### 4-全選択/全解除

- トリガー：ヘッダーのチェックボックスをクリック
- 処理内容：表示中のページの全通貨を選択/解除
- 状態変化：ページ内の全通貨の選択状態が一括変更
- 備考：追加済み通貨は対象外

### 5-税込価格設定の切り替え

- トリガー：通貨行の税込価格Switchをトグル
- 処理内容：pricePreferencesの該当通貨の設定を更新
- 状態変化：Switchの状態が変更される
- 備考：追加済み通貨のSwitchは無効

### 6-ページネーション

- トリガー：ページ切り替え操作
- 処理内容：指定ページの通貨一覧を取得
- 状態変化：表示される通貨一覧が切り替わる
- 備考：1ページあたり50件表示

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

- トリガー：「保存」ボタンをクリック
- 処理内容：
  1. バリデーション実行（最低1通貨選択）
  2. 新規選択通貨と既存通貨をマージ
  3. デフォルト通貨の確認・設定
  4. ストア更新APIを呼び出し（useUpdateStore）
  5. 成功時：トースト通知、pricePreferencesキャッシュ無効化、モーダルを閉じる
  6. 失敗時：エラートースト通知
- 画面遷移：保存成功時はストア詳細画面に戻る

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

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

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

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

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

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

#### store

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | supported_currencies | 新規選択通貨と既存通貨をマージした配列 | 各要素にcurrency_code, is_default, is_tax_inclusiveを含む |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------||
| store.toast.currenciesUpdated | 成功 | 通貨が正常に更新されました | 通貨追加成功時 |
| (APIエラー) | エラー | エラーメッセージ（API応答） | API呼び出し失敗時 |
| store.currencyAlreadyAdded | 情報 | この通貨は既に追加されています | 追加済み通貨のチェックボックスをホバー時 |

## 例外処理

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

## 備考

- フォーカスモーダル（RouteFocusModal）形式でフルスクリーンに近い表示
- zodによるスキーマバリデーション（AddCurrenciesSchema）を実装
- react-hook-formによるフォーム管理
- TanStack Table（DataTable）による高機能テーブル表示
- keepPreviousDataオプションによるスムーズなページネーション
- 既存通貨はチェックボックスが無効化され、Tooltipで理由を表示
- デフォルト通貨が削除される場合は、追加される通貨の最初の通貨をデフォルトに設定
- pricePreferencesQueryKeysの全クエリを無効化して即時反映を保証

---

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

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

### 推奨読解順序

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

通貨追加のバリデーションスキーマを理解する。

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

**読解のコツ**: currenciesはz.array(z.string()).min(1)で最低1つ必須、pricePreferencesはz.record(z.boolean())で通貨コードをキーとした真偽値マップ。

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

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

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

**主要処理フロー**:
1. **7行目**: useStoreでストアデータを取得
2. **14-22行目**: usePricePreferencesで既存の税込価格設定を取得
3. **24-25行目**: データ準備完了の判定
4. **27-33行目**: エラー処理
5. **35-41行目**: RouteFocusModalでモーダル表示、AddCurrenciesFormをレンダリング

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | add-currencies-form.tsx | `packages/admin/dashboard/src/routes/store/store-add-currencies/components/add-currencies-form/add-currencies-form.tsx` | フォーム実装、テーブル構成、API呼び出しを確認 |

**主要処理フロー**:
- **49-52行目**: useCurrenciesTableQueryで検索・ページネーションパラメータを生成
- **54-62行目**: useCurrenciesで通貨一覧を取得
- **64-79行目**: useFormでフォーム初期化（既存の価格設定をデフォルト値に設定）
- **86-96行目**: updaterで行選択をフォームのcurrenciesフィールドに同期
- **98-99行目**: 既存通貨リストを取得（選択不可にするため）
- **110-123行目**: useDataTableでテーブル設定（行選択、ページネーション等）
- **125行目**: useUpdateStoreで更新mutation取得
- **127-165行目**: handleSubmitで既存通貨とのマージ、デフォルト通貨処理、API呼び出し

#### Step 4: テーブルカラム定義を理解する

カスタムカラムの実装を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | add-currencies-form.tsx | `packages/admin/dashboard/src/routes/store/store-add-currencies/components/add-currencies-form/add-currencies-form.tsx` | 225-308行目のuseColumnsでカラム定義を確認 |

**主要処理フロー**:
- **234-275行目**: selectカラム - チェックボックスと追加済み通貨のTooltip
- **277-304行目**: is_tax_inclusiveカラム - 税込価格設定のSwitch

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

```
StoreAddCurrencies (store-add-currencies.tsx)
    │
    ├─ useStore (store.tsx)
    │      └─ retrieveActiveStore
    │
    ├─ usePricePreferences (price-preferences.tsx)
    │      └─ listPricePreferences
    │
    └─ AddCurrenciesForm (add-currencies-form.tsx)
           │
           ├─ useCurrenciesTableQuery (use-currencies-table-query.tsx)
           │      └─ URLパラメータ処理
           │
           ├─ useCurrencies (currencies.tsx)
           │      └─ sdk.admin.currency.list
           │
           ├─ useDataTable (use-data-table.tsx)
           │      └─ TanStack Table設定
           │
           ├─ useColumns
           │      ├─ useCurrenciesTableColumns (base columns)
           │      ├─ select column (Checkbox + Tooltip)
           │      └─ is_tax_inclusive column (Switch)
           │
           └─ useUpdateStore (store.tsx)
                  └─ sdk.admin.store.update
```

### データフロー図

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

(useStore) ───▶ store データ ───▶ 既存通貨リスト (preSelectedRows)
         │
         └─▶ (usePricePreferences) ───▶ 既存税込設定 ───▶ フォームデフォルト値
         │
(useCurrencies) ───▶ 全通貨リスト ───▶ DataTable表示
         │
         ├─▶ 検索/ソート ───▶ useCurrenciesTableQuery ───▶ フィルタ結果
         │
         ├─▶ 行選択 ───▶ updater ───▶ form.currencies更新
         │
         ├─▶ Switch操作 ───▶ setPricePreferences ───▶ form.pricePreferences更新
         │
         ▼
保存ボタン ─────────┬─▶ 既存通貨 + 新規選択をマージ
                   │
                   ├─▶ デフォルト通貨の確認・設定
                   │
                   └─▶ useUpdateStore ───▶ キャッシュ無効化 ───▶ モーダルを閉じる
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| store-add-currencies.tsx | `packages/admin/dashboard/src/routes/store/store-add-currencies/store-add-currencies.tsx` | ソース | 画面エントリーポイント |
| add-currencies-form.tsx | `packages/admin/dashboard/src/routes/store/store-add-currencies/components/add-currencies-form/add-currencies-form.tsx` | ソース | フォーム実装、テーブル、バリデーション、API呼び出し |
| store.tsx | `packages/admin/dashboard/src/hooks/api/store.tsx` | ソース | ストアAPI hooks |
| currencies.tsx | `packages/admin/dashboard/src/hooks/api/currencies.tsx` | ソース | 通貨API hooks |
| price-preferences.tsx | `packages/admin/dashboard/src/hooks/api/price-preferences.tsx` | ソース | 価格設定API hooks |
| use-currencies-table-query.tsx | `packages/admin/dashboard/src/routes/store/common/hooks/use-currencies-table-query.tsx` | ソース | テーブルクエリフック |
| use-currencies-table-columns.tsx | `packages/admin/dashboard/src/routes/store/common/hooks/use-currencies-table-columns.tsx` | ソース | テーブルカラム定義フック |
| use-data-table.tsx | `packages/admin/dashboard/src/hooks/use-data-table.tsx` | ソース | データテーブルフック |
| index.ts | `packages/admin/dashboard/src/routes/store/store-add-currencies/index.ts` | ソース | エクスポート定義 |
