# 画面設計書 60-ドキュメント設定

## 概要

本ドキュメントは、Shopware 6 管理画面におけるドキュメント設定（sw-settings-document）画面の設計書です。注文に関連する各種ドキュメント（請求書、納品書、クレジットノートなど）のレイアウトや会社情報を設定する画面について記述します。

### 本画面の処理概要

**業務上の目的・背景**：ECサイトでは注文処理に伴い、請求書、納品書、キャンセル確認書、クレジットノートなど様々なビジネスドキュメントを発行する必要があります。本画面では、これらのドキュメントのページ設定、表示項目、会社情報、銀行情報などを設定し、法的要件を満たしたドキュメント出力を実現します。

**画面へのアクセス方法**：管理画面にログイン後、左メニューの「設定」 > 「コマース」セクション > 「ドキュメント設定」をクリックしてアクセスします。

**主要な操作・処理内容**：
1. ドキュメント設定一覧の表示・検索
2. ドキュメント設定の新規作成
3. 既存ドキュメント設定の編集
4. ドキュメントタイプとセールスチャネルの関連付け
5. ページレイアウト設定（用紙サイズ、向き、表示項目）
6. 会社情報の設定（住所、連絡先、銀行情報、税番号）
7. ドキュメントのファイル形式設定（PDF/HTML）

**画面遷移**：設定メニュー → ドキュメント設定一覧画面 → ドキュメント設定詳細画面

**権限による表示制御**：
- `document.viewer`：一覧・詳細の閲覧
- `document.editor`：設定の編集
- `document.creator`：新規設定の作成

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 24 | 注文管理 | 関連 | 注文からのドキュメント生成 |

## 画面種別

設定

## URL/ルーティング

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

## 入出力項目

### ドキュメント設定詳細画面

#### 基本情報

| 項目名 | 項目ID | 型 | 入力/出力 | 必須 | 説明 |
|--------|--------|-----|----------|------|------|
| 設定名 | name | string | 入力 | 必須 | ドキュメント設定の識別名 |
| ドキュメントタイプ | documentTypeId | string | 入力 | 必須 | 適用するドキュメントの種類 |
| セールスチャネル | salesChannels | array | 入力 | - | 設定を適用するセールスチャネル |

#### 一般設定（generalFormFields）

| 項目名 | 項目ID | 型 | 入力/出力 | 必須 | 説明 |
|--------|--------|-----|----------|------|------|
| ページ向き | pageOrientation | string | 入力 | - | portrait/landscape |
| ページサイズ | pageSize | string | 入力 | - | a4/a5/legal/letter |
| 1ページあたりの項目数 | itemsPerPage | number | 入力 | - | 1ページに表示する明細行数 |
| ファイル形式 | fileTypes | array | 入力 | - | pdf/html |
| ヘッダー表示 | displayHeader | boolean | 入力 | - | ヘッダー部分の表示有無 |
| フッター表示 | displayFooter | boolean | 入力 | - | フッター部分の表示有無 |
| ページ番号表示 | displayPageCount | boolean | 入力 | - | ページ番号の表示有無 |
| 明細表示 | displayLineItems | boolean | 入力 | - | 注文明細の表示有無 |
| 明細番号表示 | displayLineItemPosition | boolean | 入力 | - | 明細行番号の表示有無 |
| 価格表示 | displayPrices | boolean | 入力 | - | 価格情報の表示有無 |
| 顧客アカウント表示 | displayInCustomerAccount | boolean | 入力 | - | 顧客アカウント画面での表示有無 |

#### 条件付き表示項目

| 項目名 | 項目ID | 型 | 入力/出力 | 必須 | 表示条件 |
|--------|--------|-----|----------|------|---------|
| 配送先住所の相違を表示 | displayDivergentDeliveryAddress | boolean | 入力 | - | invoiceタイプの場合 |
| 配送に関する追加メモを表示 | displayAdditionalNoteDelivery | boolean | 入力 | - | storno/credit_note/invoiceタイプの場合 |

#### 会社情報設定（companyFormFields）

| 項目名 | 項目ID | 型 | 入力/出力 | 必須 | 説明 |
|--------|--------|-----|----------|------|------|
| 返送先住所表示 | displayReturnAddress | boolean | 入力 | - | 返送先住所の表示有無 |
| 会社住所表示 | displayCompanyAddress | boolean | 入力 | - | 会社住所の表示有無 |
| 会社名 | companyName | string | 入力 | - | 会社名 |
| 番地 | companyStreet | string | 入力 | - | 会社所在地の番地 |
| 郵便番号 | companyZipcode | string | 入力 | - | 会社所在地の郵便番号 |
| 市区町村 | companyCity | string | 入力 | - | 会社所在地の市区町村 |
| 国 | companyCountryId | string | 入力 | - | 会社所在地の国 |
| メールアドレス | companyEmail | string | 入力 | - | 会社のメールアドレス |
| 電話番号 | companyPhone | string | 入力 | - | 会社の電話番号 |
| URL | companyUrl | string | 入力 | - | 会社のWebサイトURL |
| 税番号 | taxNumber | string | 入力 | - | 会社の税番号 |
| 税務署 | taxOffice | string | 入力 | - | 管轄税務署 |
| VAT ID | vatId | string | 入力 | - | 付加価値税ID |
| 銀行名 | bankName | string | 入力 | - | 取引銀行名 |
| IBAN | bankIban | string | 入力 | - | 国際銀行口座番号 |
| BIC | bankBic | string | 入力 | - | 銀行識別コード |
| 管轄地 | placeOfJurisdiction | string | 入力 | - | 法的管轄地 |
| 履行地 | placeOfFulfillment | string | 入力 | - | 契約履行地 |
| 代表取締役 | executiveDirector | string | 入力 | - | 会社代表者名 |
| 支払期日 | paymentDueDate | string | 入力 | - | 支払期日の表記 |

## 表示項目

### ドキュメント設定一覧画面

| 項目名 | 説明 |
|--------|------|
| 設定名 | ドキュメント設定の名称 |
| ドキュメントタイプ | 関連付けられたドキュメントタイプ |
| セールスチャネル | 関連付けられたセールスチャネル一覧 |

### ドキュメント設定詳細画面

| 項目名 | 説明 |
|--------|------|
| 基本情報カード | 設定名、ドキュメントタイプ、セールスチャネルの選択 |
| 一般設定カード | ページレイアウトと表示オプション |
| 会社情報カード | 会社の住所・連絡先・銀行情報 |
| カスタムフィールドカード | カスタムフィールドの設定（設定がある場合） |

## イベント仕様

### 1-一覧表示

createdComponentで一覧データを読み込みます：
1. `sw-settings-list` mixinの機能を使用してデータ取得
2. listingCriteriaでドキュメントタイプとセールスチャネルのアソシエーションを含める
3. 名前でASCソート

### 2-詳細画面表示（既存）

ユーザーが一覧から詳細画面に遷移すると、以下の処理が実行されます：
1. loadAvailableSalesChannelで利用可能なセールスチャネルを取得
2. loadEntityDataでドキュメント設定を取得（documentType、salesChannelsアソシエーション含む）
3. loadCustomFieldSetsでカスタムフィールドを取得
4. onChangeTypeでドキュメントタイプに応じた表示制御を設定

### 3-新規作成画面表示

新規作成画面を開くと、以下の処理が実行されます：
1. loadAvailableSalesChannelで利用可能なセールスチャネルを取得
2. 新しいdocumentBaseConfigエンティティを作成
3. globalをfalse、configを空オブジェクトで初期化

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

ユーザーが「保存」ボタンを押下すると、以下の処理が実行されます：
1. onChangeSalesChannelでセールスチャネルの関連付けを同期
2. documentBaseConfigRepository.saveでデータ保存
3. 新規作成の場合、詳細画面にリダイレクト
4. loadEntityDataで設定を再読み込み

### 5-ドキュメントタイプ変更

ドキュメントタイプを変更すると、以下の処理が実行されます：
1. セールスチャネル選択をリセット
2. documentTypesForDisplayNoteDelivery（storno, credit_note, invoice）の場合、isShowDisplayNoteDeliveryをtrue
3. invoiceタイプの場合、isShowDivergentDeliveryAddressをtrue
4. createSalesChannelSelectOptionsでセールスチャネルオプションを再構築
5. 他の設定で既に割り当て済みのセールスチャネルを取得してalreadyAssignedSalesChannelIdsToTypeに保持

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

キャンセルボタンまたはESCキーを押下すると、一覧画面に遷移します。

### 7-ファイル形式の追加・削除

- onAddDocumentTypeでファイル形式を追加
- onRemoveDocumentTypeでファイル形式を削除（1つは残す）

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 新規作成・保存 | document_base_config | INSERT/UPDATE | ドキュメント基本設定の保存 |
| 新規作成・保存 | document_base_config_sales_channel | INSERT/UPDATE/DELETE | セールスチャネル関連付けの保存 |

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

#### document_base_config

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT/UPDATE | name | 入力値 | 設定名 |
| INSERT/UPDATE | document_type_id | 選択値 | ドキュメントタイプID |
| INSERT/UPDATE | global | false | 新規作成時 |
| INSERT/UPDATE | config | JSON | 各種設定値 |

#### document_base_config_sales_channel

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | document_base_config_id | 設定ID | ドキュメント設定への参照 |
| INSERT | document_type_id | タイプID | ドキュメントタイプへの参照 |
| INSERT | sales_channel_id | チャネルID | セールスチャネルへの参照 |
| DELETE | - | 関連付け解除時 | セールスチャネルの関連付け削除 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|------------|------|--------------|----------|
| sw-settings-document.detail.titleSaveSuccess | 成功 | 保存が完了しました | 保存成功時 |
| global.default.error | エラー | エラーが発生しました | 一般エラー時 |

## 例外処理

| 例外ケース | 処理内容 |
|-----------|---------|
| 権限不足 | 画面へのアクセスを拒否 |
| 設定名未入力 | documentBaseConfigNameErrorを表示 |
| ドキュメントタイプ未選択 | documentBaseConfigDocumentTypeIdErrorを表示 |
| データ取得失敗 | エラー通知を表示 |
| 保存失敗 | エラー通知を表示し、ローディング状態を解除 |

## 備考

- ドキュメントタイプ選択時、ZUGFeRD形式（technicalNameがzugferd_で始まるもの）はフィルタで除外される（NEXT-40492対応）
- セールスチャネルは同一ドキュメントタイプで複数の設定に重複して割り当てることができない
- ページサイズオプション：A4、A5、Legal、Letter
- ページ向きオプション：Portrait（縦）、Landscape（横）
- ファイル形式オプション：PDF、HTML
- 配送に関する追加メモ表示は、storno（キャンセル）、credit_note（クレジットノート）、invoice（請求書）タイプでのみ利用可能
- 配送先住所の相違表示は、invoiceタイプでのみ利用可能
- ショートカットキー：SYSTEMKEY+Sで保存、ESCでキャンセル

---

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

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

### 推奨読解順序

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

ドキュメント設定はdocument_base_configテーブルとdocument_base_config_sales_channelテーブルで管理されます。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | DocumentBaseConfigDefinition.php | `src/Core/Checkout/Document/Aggregate/DocumentBaseConfig/` | ドキュメント基本設定エンティティ |
| 1-2 | DocumentBaseConfigSalesChannelDefinition.php | `src/Core/Checkout/Document/Aggregate/DocumentBaseConfigSalesChannel/` | セールスチャネル関連付けエンティティ |
| 1-3 | DocumentTypeDefinition.php | `src/Core/Checkout/Document/Aggregate/DocumentType/` | ドキュメントタイプエンティティ |

**読解のコツ**: configフィールドはJSON型で、ページ設定や会社情報などを柔軟に格納します。

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

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

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

**主要処理フロー**:
1. **14-60行目**: Module.registerでモジュール登録
2. **24-52行目**: routes定義（index, detail, create）
3. **54-59行目**: settingsItem定義（設定メニューへの追加、commerceグループ）

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

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

**主要処理フロー**:
- **19行目**: sw-settings-list mixinを使用
- **24-26行目**: entityNameとsortByの定義
- **49-61行目**: listingCriteria - ドキュメントタイプとセールスチャネルのアソシエーション

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

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

**主要処理フロー**:
- **9-13行目**: documentTypesForDisplayNoteDelivery - 配送メモ表示対象タイプ
- **34-37行目**: ショートカットキー定義
- **64-180行目**: generalFormFields - 一般設定フィールド定義
- **181-348行目**: companyFormFields - 会社情報フィールド定義
- **450-465行目**: createdComponent() - 初期化処理
- **467-494行目**: loadEntityData() - データ読み込み
- **510-550行目**: onChangeType() - ドキュメントタイプ変更処理
- **581-597行目**: onSave() - 保存処理
- **603-632行目**: createSalesChannelSelectOptions() - セールスチャネル選択オプション生成

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

```
sw-settings-document (モジュール)
    │
    ├─ sw-settings-document-list (一覧画面)
    │     ├─ sw-settings-list mixin
    │     │     └─ listingCriteria で document_base_config を取得
    │     └─ documentType, salesChannels アソシエーション
    │
    └─ sw-settings-document-detail (詳細画面)
           ├─ createdComponent()
           │     ├─ loadAvailableSalesChannel()
           │     ├─ loadEntityData() / 新規エンティティ作成
           │     └─ loadCustomFieldSets()
           │
           ├─ onChangeType()
           │     ├─ isShowDisplayNoteDelivery 判定
           │     ├─ isShowDivergentDeliveryAddress 判定
           │     ├─ createSalesChannelSelectOptions()
           │     └─ alreadyAssignedSalesChannelIdsToType 取得
           │
           ├─ onChangeSalesChannel()
           │     └─ salesChannels アソシエーション同期
           │
           └─ onSave()
                 └─ documentBaseConfigRepository.save()
```

### データフロー図

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

ドキュメント設定フォーム ──▶ sw-settings-document-detail ──▶ document_base_config
                              │
ドキュメントタイプ選択 ──▶    ├─▶ onChangeType()
                              │     ├─▶ 配送メモ/住所相違表示判定
                              │     └─▶ セールスチャネルオプション生成
                              │
一般設定入力 ────────────▶    ├─▶ config オブジェクトに格納
                              │     └─▶ generalFormFields の値
                              │
会社情報入力 ────────────▶    ├─▶ config オブジェクトに格納
                              │     └─▶ companyFormFields の値
                              │
セールスチャネル選択 ───▶     ├─▶ onChangeSalesChannel()
                              │     └─▶ salesChannels アソシエーション更新
                              │
                              └─▶ documentBaseConfigRepository.save()
                                        │
                                        ▼
                              Admin API (/api/document-base-config)
                                        │
                                        ▼
                              document_base_config テーブル
                              document_base_config_sales_channel テーブル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-document/index.js` | ソース | モジュール定義 |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-document/page/sw-settings-document-list/index.js` | ソース | 一覧画面ロジック |
| sw-settings-document-list.html.twig | `src/Administration/Resources/app/administration/src/module/sw-settings-document/page/sw-settings-document-list/sw-settings-document-list.html.twig` | テンプレート | 一覧画面UI |
| index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-document/page/sw-settings-document-detail/index.js` | ソース | 詳細画面ロジック |
| sw-settings-document-detail.html.twig | `src/Administration/Resources/app/administration/src/module/sw-settings-document/page/sw-settings-document-detail/sw-settings-document-detail.html.twig` | テンプレート | 詳細画面UI |
| sw-settings-document-detail.scss | `src/Administration/Resources/app/administration/src/module/sw-settings-document/page/sw-settings-document-detail/sw-settings-document-detail.scss` | スタイル | 詳細画面スタイル |
| acl/index.js | `src/Administration/Resources/app/administration/src/module/sw-settings-document/acl/index.js` | ソース | ACL権限定義 |
