# 画面設計書 51-通貨設定

## 概要

本ドキュメントは、Shopware 6 管理画面における通貨設定（sw-settings-currency）画面の設計書です。ECサイトで使用する通貨の登録・編集・管理を行う画面について記述します。

### 本画面の処理概要

**業務上の目的・背景**：グローバルなECサイト運営において、複数の通貨に対応することは必須要件です。本画面では、ショップで使用可能な通貨を管理し、為替レート（換算係数）や国別の端数処理設定を行うことで、多通貨対応のECサイト運営を実現します。

**画面へのアクセス方法**：管理画面にログイン後、左メニューの「設定」 > 「ローカライズ」セクション > 「通貨」をクリックして一覧画面にアクセスします。一覧画面から新規作成ボタンまたは既存の通貨名をクリックして詳細画面に遷移します。

**主要な操作・処理内容**：
1. 通貨一覧の表示・検索・ソート
2. 新規通貨の作成（通貨名、短縮名、シンボル、換算係数の設定）
3. 既存通貨の編集
4. 端数処理設定（小数点以下桁数、丸め間隔）
5. 国別の端数処理設定（特定の国に対して異なる端数処理を適用）
6. インライン編集による迅速な更新
7. 通貨の削除

**画面遷移**：設定メニュー → 通貨一覧画面 → 通貨詳細画面。詳細画面から一覧画面への戻り遷移も可能です。

**権限による表示制御**：`currencies.viewer`権限で閲覧可能、`currencies.editor`権限で編集可能、`currencies.creator`権限で新規作成可能、`currencies.deleter`権限で削除可能です。権限がない場合、該当するボタンやアクションは無効化されます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 70 | コンテキスト切替 | 補助機能 | 対応通貨の設定 |

## 画面種別

一覧 / 詳細 / 登録 / 編集

## URL/ルーティング

| 画面 | URL | コンポーネント |
|------|-----|---------------|
| 通貨一覧 | `#/sw/settings/currency/index` | sw-settings-currency-list |
| 通貨詳細 | `#/sw/settings/currency/detail/:id` | sw-settings-currency-detail |
| 通貨新規作成 | `#/sw/settings/currency/create` | sw-settings-currency-detail |

## 入出力項目

### 一覧画面

| 項目名 | 項目ID | 型 | 入力/出力 | 必須 | 説明 |
|--------|--------|-----|----------|------|------|
| 名前 | name | string | 入出力 | ○ | 通貨の表示名 |
| 短縮名 | shortName | string | 入出力 | ○ | 通貨の短縮名（例：EUR） |
| シンボル | symbol | string | 入出力 | ○ | 通貨記号（例：€） |
| 換算係数 | factor | float | 入出力 | ○ | 基準通貨からの換算係数 |

### 詳細画面

| 項目名 | 項目ID | 型 | 入力/出力 | 必須 | 説明 |
|--------|--------|-----|----------|------|------|
| 名前 | name | string | 入力 | ○ | 通貨の表示名 |
| ISOコード | isoCode | string | 入力 | ○ | ISO 4217通貨コード |
| 短縮名 | shortName | string | 入力 | ○ | 通貨の短縮名 |
| シンボル | symbol | string | 入力 | ○ | 通貨記号 |
| 換算係数 | factor | float | 入力 | ○ | 基準通貨からの換算係数 |
| 小数点以下桁数（単品） | itemRounding.decimals | int | 入力 | ○ | 単品価格の小数点以下桁数 |
| 丸め間隔（単品） | itemRounding.interval | float | 入力 | ○ | 単品価格の丸め間隔 |
| ネット価格丸め（単品） | itemRounding.roundForNet | boolean | 入力 | - | ネット価格に対して丸めを適用 |
| 小数点以下桁数（合計） | totalRounding.decimals | int | 入力 | ○ | 合計金額の小数点以下桁数 |
| 丸め間隔（合計） | totalRounding.interval | float | 入力 | ○ | 合計金額の丸め間隔 |
| ネット価格丸め（合計） | totalRounding.roundForNet | boolean | 入力 | - | 合計のネット価格に丸めを適用 |

## 表示項目

### 一覧画面

| 項目名 | 説明 |
|--------|------|
| 通貨名 | 通貨の表示名（詳細画面へのリンク） |
| 短縮名 | 通貨の短縮名 |
| シンボル | 通貨記号 |
| 換算係数 | 基準通貨からの換算係数 |

### 詳細画面 - 国別端数処理一覧

| 項目名 | 説明 |
|--------|------|
| 国名 | 対象の国名 |
| 単品小数点以下桁数 | 単品価格の小数点以下桁数 |
| 単品丸め間隔 | 単品価格の丸め間隔 |
| 合計小数点以下桁数 | 合計金額の小数点以下桁数 |
| 合計丸め間隔 | 合計金額の丸め間隔 |

## イベント仕様

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

ユーザーが「保存」ボタンを押下すると、入力された通貨情報がバリデーションされ、currencyリポジトリを通じてAPIに保存リクエストが送信されます。保存成功時は成功通知が表示され、新規作成の場合は詳細画面にリダイレクトされます。

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

ユーザーが「キャンセル」ボタンを押下すると、変更を破棄して通貨一覧画面に遷移します。

### 3-削除ボタン押下

一覧画面で削除アイコンをクリックすると、削除確認モーダルが表示されます。確認後、currencyリポジトリのdeleteメソッドを通じて通貨が削除されます。

### 4-国別端数処理追加

詳細画面で「国を追加」ボタンをクリックすると、国別端数処理設定モーダルが表示されます。国を選択し、端数処理設定を入力して保存します。

### 5-インライン編集

一覧画面でセルをダブルクリックすると、インライン編集モードが有効になります。編集後、チェックマークをクリックして保存します。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | currency | INSERT/UPDATE | 通貨情報の新規作成または更新 |
| 保存ボタン押下 | currency_translation | INSERT/UPDATE | 通貨の翻訳情報 |
| 国別端数処理保存 | currency_country_rounding | INSERT/UPDATE | 国別端数処理設定 |
| 削除ボタン押下 | currency | DELETE | 通貨の削除 |
| 削除ボタン押下 | currency_country_rounding | DELETE | 関連する国別設定の削除 |

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

#### currency

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT/UPDATE | id | UUIDv4 | 新規作成時は自動生成 |
| INSERT/UPDATE | iso_code | 入力値 | ISO 4217コード |
| INSERT/UPDATE | factor | 入力値 | 換算係数 |
| INSERT/UPDATE | symbol | 入力値 | 通貨記号 |
| INSERT/UPDATE | item_rounding | JSON形式 | 単品端数処理設定 |
| INSERT/UPDATE | total_rounding | JSON形式 | 合計端数処理設定 |

#### currency_country_rounding

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT/UPDATE | id | UUIDv4 | 新規作成時は自動生成 |
| INSERT/UPDATE | currency_id | 親通貨のID | 外部キー |
| INSERT/UPDATE | country_id | 選択した国のID | 外部キー |
| INSERT/UPDATE | item_rounding | JSON形式 | 国別単品端数処理 |
| INSERT/UPDATE | total_rounding | JSON形式 | 国別合計端数処理 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|------------|------|--------------|----------|
| messageSaveSuccess | 成功 | 通貨「{name}」が正常に保存されました | 保存成功時 |
| messageSaveError | エラー | 通貨の保存中にエラーが発生しました | 保存失敗時 |
| notificationCountrySuccessMessage | 成功 | 国別設定が正常に保存されました | 国別設定保存成功時 |
| notificationCountryErrorMessage | エラー | 国別設定の保存中にエラーが発生しました | 国別設定保存失敗時 |

## 例外処理

| 例外ケース | 処理内容 |
|-----------|---------|
| 通貨が見つからない | エラー通知を表示し、一覧画面にリダイレクト |
| 権限不足 | 該当するアクションボタンを無効化し、ツールチップで警告表示 |
| 通信エラー | エラー通知を表示し、ローディング状態を解除 |
| バリデーションエラー | 該当項目にエラー表示し、保存を中止 |
| 使用中の通貨削除 | エラー通知を表示（販売チャネルで使用中の場合） |

## 備考

- 基準通貨（デフォルト通貨）は換算係数が1.0に設定されます
- 国別端数処理は、通貨が保存された後にのみ設定可能です（新規作成時は設定不可）
- 端数処理のデフォルト値は小数点以下2桁、間隔0.01です
- カスタムフィールドセットが定義されている場合、詳細画面にカスタムフィールドタブが表示されます

---

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

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

### 推奨読解順序

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

通貨エンティティとその関連データの構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | currency.entity.ts | `src/Core/System/Currency/` | 通貨エンティティの定義、フィールド構成 |
| 1-2 | currency_country_rounding.entity.ts | `src/Core/System/Currency/Aggregate/` | 国別端数処理の関連エンティティ |

**読解のコツ**: Shopwareのエンティティ定義はPHPで記述されており、プロパティのアノテーションからデータ型や関連を読み取れます。

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

モジュール登録とルーティング設定を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-currency/index.js` | モジュール登録、ルート定義、権限設定 |

**主要処理フロー**:
1. **19-69行目**: Module.registerでモジュール登録
2. **29-61行目**: routes定義（index, detail, create）
3. **63-68行目**: settingsItem定義（設定メニューへの追加）

#### Step 3: 一覧画面コンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-currency/page/sw-settings-currency-list/index.js` | 一覧画面のロジック |

**主要処理フロー**:
- **54-74行目**: getList()メソッド - 通貨一覧の取得
- **76-79行目**: onChangeLanguage() - 言語切り替え時の処理
- **81-94行目**: onInlineEditSave() - インライン編集の保存
- **112-139行目**: getCurrencyColumns() - グリッドカラム定義

#### Step 4: 詳細画面コンポーネントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-currency/page/sw-settings-currency-detail/index.js` | 詳細画面のロジック |

**主要処理フロー**:
- **200-225行目**: createdComponent() - 初期化処理
- **227-243行目**: loadEntityData() - 通貨データの読み込み
- **268-294行目**: onSave() - 保存処理
- **317-322行目**: onAddCountry() - 国別設定追加

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

```
sw-settings-currency (モジュール)
    │
    ├─ sw-settings-currency-list (一覧画面)
    │      ├─ currencyRepository.search() - 一覧取得
    │      ├─ currencyRepository.delete() - 削除
    │      └─ inline-edit → currencyRepository.save()
    │
    └─ sw-settings-currency-detail (詳細画面)
           ├─ currencyRepository.get() - 詳細取得
           ├─ currencyRepository.create() - 新規作成
           ├─ currencyRepository.save() - 保存
           ├─ currencyCountryRoundingRepository.search() - 国別設定取得
           └─ currencyCountryRoundingRepository.save() - 国別設定保存
```

### データフロー図

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

通貨フォーム入力 ───▶ sw-settings-currency-detail ───▶ currency テーブル
                              │
                              ├─▶ バリデーション
                              │
                              └─▶ currencyRepository.save()
                                        │
                                        ▼
                              Admin API (/api/currency)
                                        │
                                        ▼
                              CurrencyRepository (PHP)
                                        │
                                        ▼
                              データベース (currency)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-currency/index.js` | ソース | モジュール定義 |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-currency/page/sw-settings-currency-list/index.js` | ソース | 一覧画面ロジック |
| sw-settings-currency-list.html.twig | `src/Administration/Resources/app/administration/src/module/sw-settings-currency/page/sw-settings-currency-list/sw-settings-currency-list.html.twig` | テンプレート | 一覧画面UI |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-currency/page/sw-settings-currency-detail/index.js` | ソース | 詳細画面ロジック |
| sw-settings-currency-detail.html.twig | `src/Administration/Resources/app/administration/src/module/sw-settings-currency/page/sw-settings-currency-detail/sw-settings-currency-detail.html.twig` | テンプレート | 詳細画面UI |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-currency/component/sw-settings-price-rounding/index.js` | ソース | 端数処理コンポーネント |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-currency/component/sw-settings-currency-country-modal/index.js` | ソース | 国別設定モーダル |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-currency/acl/index.js` | ソース | 権限定義 |
