[4.4] 受注一覧画面 表示項目設定機能 — 実装設計

# [4.4] 受注一覧画面 表示項目設定機能 — 実装設計

> 管理画面の受注一覧画面（`/admin/order`）で表示する**項目とその表示順を、店舗管理者がカスタマイズできる機能**を本体に追加するための設計提案です。個別の進捗ではなく、取り込み時に到達すべき構成をまとめ、レビューと合意の土台とします。
>
> 既存の **CSV出力項目設定** と同等の 2 カラム（非表示項目 / 表示項目）UI を踏襲し、学習コストを抑えます。設定は専用テーブルで管理し、**初期状態は全項目表示**・**設定未登録時はデフォルトにフォールバック**します。

| 項目 | 値 |
|------|-----|
| 対象バージョン | **EC-CUBE 4.4**（Symfony 7.4 / Doctrine ORM 3.x / DBAL 4.x / PHP 8.2+） |
| 配布形態 | **本体同梱**（管理画面機能） |
| 対象画面 | 管理画面 > 受注管理 > 表示項目設定（新設） / 受注一覧（既存拡張） |
| マッピング | PHP 8 Attribute（本体現行方式に準拠） |
| 受入基準 | [§8](#8-受入基準-acceptance-criteria) |

---

## 1. 概要 (Overview)

受注一覧画面で表示される項目とその順番を、管理画面から任意にカスタマイズできるようにする機能です。

現状、受注一覧の表示項目・順序は固定されており、店舗の運用に応じた最適化ができません。「受注管理 > 表示項目設定」を新設し、表示/非表示の振り分けと並べ替えを可能にすることで、業務に合わせた一覧表示を実現します。

## 2. 背景と目的

- **背景**: 受注一覧は店舗ごとに重視する情報が異なるが、現状は全項目固定表示で取捨選択ができない。
- **目的**:
1. 店舗管理者が業務に不要な列を隠し、必要な列を任意の順序で表示できるようにする。
2. 既存の CSV 出力項目設定と同じ操作感を提供し、学習コストを最小化する。
- **方針**: 受注一覧の**表示制御のみ**を対象とし、検索・集計・出力ロジックには手を入れない。

## 3. アーキテクチャ構成

### 3.1 コンポーネント構成

| コンポーネント | 区分 | 役割 |
|---|---|---|
| `OrderDisplaySetting`（Entity） | 新規 | 表示項目設定の永続化（`field_name` / `disp_name` / `enabled` / `sort_no`） |
| `OrderDisplaySettingRepository` | 新規 | 設定の取得・保存（有効項目を `sort_no` 順で取得 / 一括保存） |
| `OrderDisplaySettingController` | 新規 | 表示項目設定画面の表示・保存（`/admin/order/display_setting`） |
| `OrderDisplaySettingItemType`（Form） | 新規 | 設定フォーム・バリデーション |
| `display_setting.twig` | 新規 | 設定画面テンプレート（2カラム + 移動/並べ替え操作） |
| `OrderController::index()` | 既存拡張 | 設定を取得し受注一覧テンプレートへ受け渡し（最小差分） |
| `Order/index.twig` | 既存拡張 | 設定に基づく列の表示/非表示・順序制御 |
| `messages.ja.yaml` | 既存拡張 | 設定画面・項目名の翻訳キー追加 |

### 3.2 動作フロー

**設定保存**: 管理者が設定画面で項目を振り分け・並べ替え → `POST /admin/order/display_setting` → バリデーション → `dtb_order_display_setting` を更新。

**一覧表示**: `GET /admin/order` → 有効設定を `sort_no` 順で取得（未登録時はデフォルト設定にフォールバック）→ テンプレートで列を動的描画。

## 4. 設定項目とデータモデル

### 4.1 設定可能項目（初期はすべて表示）

| field_name | 表示名 | 内容 |
|---|---|---|
| `order_info` | ID・注文者 | 注文番号・注文者名・注文日 |
| `payment_method` | 支払方法 | 決済方法 |
| `order_status` | 対応状況 | 受注状態 |
| `payment_info` | 購入金額 | 金額・支払日 |
| `message` | お問合せ | 注文者メッセージ・管理メモ |
| `shipping_status` | 出荷状況 | 配送状態 |
| `tracking_number` | お問い合わせ番号 | 配送追跡番号 |
| `delivery_address` | お届け先 | 配送先情報 |

※一括操作用チェックボックスは**設定対象外（常に固定表示）**。

### 4.2 テーブル `dtb_order_display_setting`

| カラム | 型 | NULL | 既定 | 説明 |
|---|---|---|---|---|
| `id` | INTEGER | NO | AUTO | 主キー |
| `field_name` | VARCHAR(255) | NO | - | フィールド識別子 |
| `disp_name` | VARCHAR(255) | NO | - | 表示名 |
| `enabled` | BOOLEAN | NO | true | 表示フラグ |
| `sort_no` | INTEGER | NO | 0 | 表示順 |
| `create_date` / `update_date` | DATETIME | NO | - | 作成・更新日時 |

テーブル定義は Entity の Attribute で管理。初期データは `import_csv`（新規インストール時）＋コントローラのデフォルトフォールバックで担保する。

## 5. ルーティング

| ルート名 | パス | メソッド | 説明 |
|---|---|---|---|
| `admin_order_display_setting` | `/admin/order/display_setting` | GET | 設定画面表示 |
| `admin_order_display_setting` | `/admin/order/display_setting` | POST | 設定保存 |

## 6. スコープ外（今回含めないこと）

- 受注一覧の**検索条件・CSV出力項目**の変更（既存機能のまま）。
- フロント側・他一覧画面（出荷一覧・会員一覧等）への横展開。
- 会員/権限ごとの個別表示設定（本機能は**店舗共通設定**）。

## 7. 技術的考慮事項

### 7.1 後方互換性
- 既存の受注一覧の挙動はデフォルト設定で**従来どおり全項目表示**となり、未設定環境でも影響しない。
- `OrderController` / `index.twig` への変更は表示制御のラップに限定し、既存ロジックを温存する。

### 7.2 初期データ・テーブル作成
- `app/DoctrineMigrations` は使用しない方針。テーブルは Entity 定義（スキーマ）と `import_csv` により提供する。

## 8. 受入基準 (Acceptance Criteria)

- [ ] 「受注管理 > 表示項目設定」画面で 8 項目の表示/非表示・順序を設定・保存できる。
- [ ] 受注一覧が設定どおりに列の表示/非表示・順序を反映する。
- [ ] チェックボックス列は設定に関わらず常に表示される。
- [ ] 設定未登録時はデフォルト（全項目表示）でフォールバックする。
- [ ] 既存の受注一覧・検索・CSV出力の挙動に影響がない。
- [ ] Entity / Repository / Form / Controller の単体・機能テストが追加され、グリーン。
- [ ] PHPStan / PHP-CS-Fixer をパスする。