# 画面設計書 53-税設定

## 概要

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

### 本画面の処理概要

**業務上の目的・背景**：ECサイトにおいて、商品やサービスに適用される税率の管理は法令遵守および正確な価格計算に不可欠です。本画面では、標準税率の設定に加え、国や地域ごとに異なる税率（国別税率ルール）を設定することで、グローバルなECサイト運営における複雑な税制対応を実現します。

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

**主要な操作・処理内容**：
1. 税率一覧の表示・検索・ソート
2. 新規税率の作成（税率名、パーセンテージの設定）
3. 既存税率の編集
4. 国別税率ルールの設定（特定の国に対して異なる税率を適用）
5. デフォルト税率の指定
6. インライン編集による迅速な更新
7. 税率の削除

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 商品管理 | 参照元 | 商品に税率を適用 |

## 画面種別

一覧 / 詳細 / 登録 / 編集

## URL/ルーティング

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

## 入出力項目

### 一覧画面

| 項目名 | 項目ID | 型 | 入力/出力 | 必須 | 説明 |
|--------|--------|-----|----------|------|------|
| 名前 | name | string | 入出力 | ○ | 税率の表示名 |
| デフォルト | position | int | 出力 | - | デフォルト税率フラグ |
| 税率 | taxRate | float | 入出力 | ○ | 税率（パーセンテージ） |

### 詳細画面

| 項目名 | 項目ID | 型 | 入力/出力 | 必須 | 説明 |
|--------|--------|-----|----------|------|------|
| 名前 | name | string | 入力 | ○ | 税率の表示名 |
| 税率 | taxRate | float | 入力 | ○ | 税率（パーセンテージ） |

### 国別税率ルール

| 項目名 | 項目ID | 型 | 入力/出力 | 必須 | 説明 |
|--------|--------|-----|----------|------|------|
| 国 | countryId | uuid | 入力 | ○ | 対象国 |
| 税率タイプ | taxRuleTypeId | uuid | 入力 | ○ | 税率ルールタイプ |
| 税率 | taxRate | float | 入力 | ○ | 国別税率 |
| 起算日 | activeFrom | datetime | 入力 | - | ルール適用開始日 |

## 表示項目

### 一覧画面

| 項目名 | 説明 |
|--------|------|
| 税率名 | 税率の表示名（詳細画面へのリンク） |
| デフォルト | デフォルト税率かどうか |
| 税率 | 税率パーセンテージ |

### 詳細画面 - 国別税率ルール一覧

| 項目名 | 説明 |
|--------|------|
| 国名 | 対象の国名 |
| 税率タイプ | 適用される税率ルールタイプ |
| 税率 | 国別税率パーセンテージ |
| 起算日 | ルール適用開始日 |

## イベント仕様

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

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

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

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

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

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

### 4-国別税率ルール追加

詳細画面で「税率ルールを追加」ボタンをクリックすると、国別税率ルール入力フォームが表示されます。国、税率タイプ、税率、起算日を入力して追加します。

### 5-国別税率ルール削除

国別税率ルール一覧で削除アイコンをクリックすると、該当ルールが削除されます。

### 6-インライン編集

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

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | tax | INSERT/UPDATE | 税率情報の新規作成または更新 |
| 国別税率ルール保存 | tax_rule | INSERT/UPDATE | 国別税率ルール設定 |
| 削除ボタン押下 | tax | DELETE | 税率の削除 |
| 国別ルール削除 | tax_rule | DELETE | 国別税率ルールの削除 |

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

#### tax

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT/UPDATE | id | UUIDv4 | 新規作成時は自動生成 |
| INSERT/UPDATE | name | 入力値 | 税率名 |
| INSERT/UPDATE | tax_rate | 入力値 | 税率パーセンテージ |
| INSERT/UPDATE | position | 入力値 | 表示順/デフォルト識別 |

#### tax_rule

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT/UPDATE | id | UUIDv4 | 新規作成時は自動生成 |
| INSERT/UPDATE | tax_id | 親税率のID | 外部キー |
| INSERT/UPDATE | country_id | 選択した国のID | 外部キー |
| INSERT/UPDATE | tax_rule_type_id | 選択した税率タイプのID | 外部キー |
| INSERT/UPDATE | tax_rate | 入力値 | 国別税率 |
| INSERT/UPDATE | active_from | 入力値 | 適用開始日 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|------------|------|--------------|----------|
| messageSaveSuccess | 成功 | 税率「{name}」が正常に保存されました | 保存成功時 |
| messageSaveError | エラー | 税率の保存中にエラーが発生しました | 保存失敗時 |
| messageDeleteSuccess | 成功 | 税率が正常に削除されました | 削除成功時 |
| messageDeleteError | エラー | 税率の削除中にエラーが発生しました | 削除失敗時 |

## 例外処理

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

## 備考

- デフォルト税率は position = 1 として識別されます
- 国別税率ルールは tax_rule テーブルで管理されます
- 税率ルールタイプ（tax_rule_type）により、どのような条件で税率が適用されるかが決定されます
- カスタムフィールドセットが定義されている場合、詳細画面にカスタムフィールドセクションが表示されます

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | TaxDefinition.php | `src/Core/System/Tax/` | 税率エンティティの定義 |
| 1-2 | TaxRuleDefinition.php | `src/Core/System/Tax/Aggregate/TaxRule/` | 国別税率ルールの関連エンティティ |
| 1-3 | TaxRuleTypeDefinition.php | `src/Core/System/Tax/Aggregate/TaxRuleType/` | 税率ルールタイプの定義 |

**読解のコツ**: 税率ルールは国、税率タイプ、起算日の組み合わせで構成されます。

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

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

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

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

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

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

**主要処理フロー**:
- **36-56行目**: listCriteria - 税率一覧取得条件
- **58-95行目**: columns - グリッドカラム定義
- **114-137行目**: getList() - 税率一覧の取得

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

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

**主要処理フロー**:
- **114-126行目**: createdComponent() - 初期化処理
- **128-143行目**: loadEntityData() - 税率データの読み込み
- **151-167行目**: onSave() - 保存処理
- **193-207行目**: onAddCountryBasedTaxRule() - 国別税率ルール追加

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

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

### データフロー図

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

税率フォーム入力 ───▶ sw-settings-tax-detail ───────▶ tax テーブル
                              │
国別税率ルール入力 ───▶       ├─▶ バリデーション
                              │
                              └─▶ taxRepository.save()
                                        │
                                        ▼
                              Admin API (/api/tax)
                                        │
                                        ▼
                              TaxRepository (PHP)
                                        │
                                        ├─▶ データベース (tax)
                                        └─▶ データベース (tax_rule)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-tax/index.js` | ソース | モジュール定義 |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-tax/page/sw-settings-tax-list/index.js` | ソース | 一覧画面ロジック |
| sw-settings-tax-list.html.twig | `src/Administration/Resources/app/administration/src/module/sw-settings-tax/page/sw-settings-tax-list/sw-settings-tax-list.html.twig` | テンプレート | 一覧画面UI |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-tax/page/sw-settings-tax-detail/index.js` | ソース | 詳細画面ロジック |
| sw-settings-tax-detail.html.twig | `src/Administration/Resources/app/administration/src/module/sw-settings-tax/page/sw-settings-tax-detail/sw-settings-tax-detail.html.twig` | テンプレート | 詳細画面UI |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-tax/component/sw-settings-tax-rule-modal/index.js` | ソース | 税率ルールモーダル |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-tax/component/sw-settings-tax-rule-type-individual-states/index.js` | ソース | 州別税率タイプ |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-tax/component/sw-settings-tax-rule-type-zip-code/index.js` | ソース | 郵便番号別税率タイプ |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-tax/component/sw-settings-tax-rule-type-zip-code-range/index.js` | ソース | 郵便番号範囲税率タイプ |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-tax/acl/index.js` | ソース | 権限定義 |
