# 画面設計書 188-翻訳設定画面

## 概要

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

### 本画面の処理概要

翻訳設定画面は、翻訳可能なエンティティとフィールドを設定するための管理画面である。各エンティティ（商品、カテゴリなど）ごとに、どのフィールドを翻訳対象とするかを選択できる。

**業務上の目的・背景**：
多言語対応において、すべてのフィールドを翻訳対象とする必要はない場合がある。本画面では、エンティティごとに翻訳が必要なフィールドを選択し、翻訳作業の範囲を適切に管理できる。これにより、不要な翻訳作業を減らし、運用効率を向上させる。

**画面へのアクセス方法**：
翻訳一覧画面 > 「Manage translatable entities」ボタンをクリックすることでアクセスする。

**主要な操作・処理内容**：
1. 翻訳可能エンティティの一覧表示 - ツリー構造で表示
2. フィールドの選択/解除 - チェックボックスで制御
3. 検索とフィルタリング - エンティティ/フィールドの検索
4. 表示モード切替 - 全表示/選択済みのみ表示
5. ソート切替 - 昇順/降順
6. 一括選択/解除 - すべて選択/すべて解除
7. 設定の保存 - バッチ更新で一括保存

**画面遷移**：
- 遷移元：翻訳一覧画面
- 遷移先：なし（ドロワーを閉じて翻訳一覧画面に戻る）

**権限による表示制御**：
管理者権限を持つユーザーのみがアクセス可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 85 | 翻訳CRUD | 主機能 | 翻訳設定の取得・更新 |

## 画面種別

ドロワー（RouteDrawer）

## URL/ルーティング

`/settings/translations/settings`

## 入出力項目

### 入力項目

| 項目名 | 必須 | 型 | 入力形式 | 最大長 | 制約・補足 |
|--------|------|-----|---------|--------|-----------|
| selectedFields | Yes | string[] | チェックボックス | - | 選択されたフィールドの配列（entityType.fieldName形式） |

### バリデーション仕様

本画面は選択のみで、特別なバリデーションはない。

## 表示項目

### ヘッダー

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| タイトル | テキスト | "Manage translatable entities" |

### フィルターエリア

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| 検索ボックス | テキスト入力 | エンティティ/フィールド名でフィルタ |
| 表示モード | トグル | 全表示/選択済みのみ |
| ソート | トグル | 昇順/降順 |
| すべて選択/解除 | ボタン | 全エンティティの選択/解除 |
| すべて折りたたみ | ボタン | ツリーをすべて折りたたむ |

### エンティティツリー

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| エンティティ名 | ノード | Title Case形式で表示 |
| フィールド名 | リーフ | Title Case形式で表示 |
| チェックボックス | チェックボックス | 選択状態を表示 |

### フッター

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| キャンセルボタン | ボタン | ドロワーを閉じる |
| 保存ボタン | ボタン | 設定を保存 |

## イベント仕様

### 1-画面初期表示

1. `useTranslationSettings` で翻訳設定をAPIから取得
2. `transformSettingsToEntities` で設定データをEntity形式に変換
3. 初期選択状態をフォームに設定
4. ローディング中はSpinnerを表示

### 2-フィールド選択変更

1. チェックボックスの状態が変更される
2. `handleSelectionChange` で新しい選択状態をフォームに反映
3. フォームのdirty状態を更新

### 3-検索

1. 検索ボックスに入力
2. `searchQuery` 状態を更新
3. `EntitySelectorTree` がフィルタリングを適用

### 4-表示モード切替

1. 表示モードトグルをクリック
2. `viewMode` 状態を "full" または "selected" に切替
3. ツリー表示が更新される

### 5-ソート切替

1. ソートボタンをクリック
2. `sortOrder` 状態を "asc" または "desc" に切替
3. ツリー表示がソートされる

### 6-すべて選択/解除

1. すべて選択/解除ボタンをクリック
2. `treeRef.current?.selectAllToggle(selected)` を呼び出し
3. 全エンティティの選択状態を変更

### 7-すべて折りたたみ

1. 折りたたみボタンをクリック
2. `treeRef.current?.collapseAll()` を呼び出し
3. すべてのエンティティノードを折りたたむ

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

1. フォームの送信処理が実行される
2. `transformSelectedFieldsToBatchRequest` で選択状態をAPIリクエスト形式に変換
3. `useBatchTranslationSettings` でバッチ更新APIを呼び出し
4. 成功時：トースト表示、ドロワーを閉じる
5. 失敗時：エラートースト表示

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面初期表示 | translation_setting | SELECT | 翻訳設定の取得 |
| 保存ボタン押下 | translation_setting | INSERT/UPDATE | 翻訳設定のバッチ更新 |

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

#### translation_setting

| 列名 | INSERT | UPDATE | 備考 |
|------|--------|--------|------|
| id | - | 更新対象のキー | UUIDを使用 |
| entity_type | 必須 | - | エンティティタイプ（例：product） |
| fields | 必須 | 更新可 | 翻訳対象フィールドの配列 |
| is_active | 必須 | 更新可 | フィールドが選択されている場合はtrue |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| translations.settings.successToast | 成功 | 設定が保存されました | 保存成功時 |
| - | エラー | APIエラーメッセージ | 保存失敗時 |

## 例外処理

| 例外ケース | 処理内容 |
|-----------|----------|
| API通信エラー | エラーをスローし、エラーバウンダリでキャッチ |
| データ取得中 | ドロワー内にSpinnerを表示 |
| 保存中 | 保存ボタンにローディング表示 |

## 備考

- RouteDrawerレイアウトを使用
- EntitySelectorTreeコンポーネントでツリー構造を表示
- エンティティ名・フィールド名はsnake_caseからTitle Caseに変換
- バッチリクエストはcreate（新規作成）とupdate（更新）を区別して送信
- フィールドが選択されていないエンティティはis_active=falseで更新

---

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

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

### 推奨読解順序

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

まず、翻訳設定のデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | batch-translation-settings-form.tsx | `packages/admin/dashboard/src/routes/translations/settings/components/batch-translation-settings-form/batch-translation-settings-form.tsx` | 22-24行目: BatchTranslationSettingsSchemaの定義 |
| 1-2 | entity-selector-tree.tsx | `.../components/entity-selector-tree/entity-selector-tree.tsx` | Entity, EntityField型の定義 |

**読解のコツ**: selectedFieldsは "entityType.fieldName" 形式の文字列配列。

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

画面のメインコンポーネントを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | settings.tsx | `packages/admin/dashboard/src/routes/translations/settings/settings.tsx` | 全体構造 |

**主要処理フロー**:
1. **8-9行目**: useTranslationSettingsで翻訳設定を取得
2. **11-13行目**: エラー時はエラーをスロー
3. **22-32行目**: ローディング中はSpinner、それ以外はフォームを表示

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

メインのフォームコンポーネントを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | batch-translation-settings-form.tsx | `.../components/batch-translation-settings-form/batch-translation-settings-form.tsx` | フォーム処理全体 |

**主要処理フロー**:
- **30-35行目**: format関数でsnake_caseをTitle Caseに変換
- **40-61行目**: transformSettingsToEntitiesでAPIレスポンスをEntity形式に変換
- **66-110行目**: transformSelectedFieldsToBatchRequestで選択状態をAPIリクエスト形式に変換
- **126行目**: useBatchTranslationSettingsでバッチ更新
- **128-147行目**: entitiesとinitialSelectedIdsの計算
- **153-158行目**: React Hook Formのセットアップ
- **178-197行目**: handleSubmitで保存処理

#### Step 4: API連携を理解する

APIフックの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | translations.tsx | `packages/admin/dashboard/src/hooks/api/translations.tsx` | 翻訳関連のAPIフック |

**主要処理フロー**:
- **157-176行目**: useTranslationSettingsで設定取得
- **178-199行目**: useBatchTranslationSettingsでバッチ更新（create/update）

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

```
Settings (settings.tsx)
    │
    ├─ useTranslationSettings() - 翻訳設定取得
    │      └─ sdk.admin.translation.settings()
    │
    └─ BatchTranslationSettingsForm
           │
           ├─ transformSettingsToEntities() - データ変換
           │
           ├─ React Hook Form
           │      └─ form.setValue("selectedFields", ...)
           │
           ├─ SelectorTreeFilter - フィルター・ソート
           │
           ├─ EntitySelectorTree - ツリー表示
           │      ├─ selectAllToggle() - 一括選択
           │      └─ collapseAll() - 一括折りたたみ
           │
           └─ handleSubmit
                  ├─ transformSelectedFieldsToBatchRequest()
                  └─ useBatchTranslationSettings()
                         └─ sdk.admin.translation.batchSettings()
```

### データフロー図

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

翻訳設定API ───▶ transformSettings ───▶ EntitySelectorTree
                   ToEntities

チェックボックス ───▶ handleSelectionChange ───▶ フォーム状態更新
    操作

保存ボタン ───▶ transformSelectedFields ───▶ バッチAPI呼び出し
                ToBatchRequest
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| settings.tsx | `packages/admin/dashboard/src/routes/translations/settings/settings.tsx` | ソース | 設定画面のエントリーポイント |
| batch-translation-settings-form.tsx | `.../components/batch-translation-settings-form/batch-translation-settings-form.tsx` | ソース | 設定フォーム |
| entity-selector-tree.tsx | `.../components/entity-selector-tree/entity-selector-tree.tsx` | ソース | エンティティツリー |
| selector-tree-filter.tsx | `.../components/selector-tree-filter/selector-tree-filter.tsx` | ソース | フィルター・ソートUI |
| translations.tsx | `packages/admin/dashboard/src/hooks/api/translations.tsx` | ソース | 翻訳APIフック |
| RouteDrawer | `packages/admin/dashboard/src/components/modals` | ソース | ドロワーコンポーネント |
