# 画面設計書 41-注文一覧

## 概要

本ドキュメントは、Shopware 6 Administration（管理画面）における「注文一覧」画面の設計書です。この画面はECサイトで受け付けた注文の一覧表示、検索、フィルタリング、およびステータス管理を行う注文処理のメイン画面です。

### 本画面の処理概要

**業務上の目的・背景**：EC運営において注文管理は最も重要な業務の一つです。日々発生する多数の注文を効率的に処理するため、注文の一覧表示、検索、フィルタリング、ステータス確認といった機能が必要です。本画面は、管理者が注文状況を把握し、迅速に処理を進めるための中核となる機能を提供します。

**画面へのアクセス方法**：管理画面にログイン後、左側メニューの「注文」をクリックすることでアクセスできます。URLパスは `/admin#/sw/order/index` となります。`order.viewer` 権限を持つユーザーのみがアクセス可能です。

**主要な操作・処理内容**：
1. 注文一覧の表示 - 注文番号、顧客名、金額、ステータス、日時などを一覧表示
2. 注文の検索 - キーワード検索による注文の絞り込み
3. フィルタリング - 販売チャネル、ステータス、支払方法、配送方法、日付範囲など多様なフィルター条件での絞り込み
4. ソート - 各カラムによる昇順・降順ソート
5. 注文詳細への遷移 - 注文番号クリックで詳細画面へ遷移
6. 注文の削除 - ドキュメント未発行の注文を削除（deleter権限必要）
7. 一括編集 - 複数注文の一括ステータス変更

**画面遷移**：
- 遷移元: ダッシュボード、メニュー
- 遷移先: 注文詳細画面（sw.order.detail）、注文作成画面（sw.order.create）、一括編集画面（sw.bulk.edit.order）

**権限による表示制御**：
- `order.viewer`: 閲覧権限 - 注文一覧の表示が可能
- `order.creator`: 作成権限 - 新規注文作成ボタンが表示
- `order.editor`: 編集権限 - インライン編集が可能
- `order.deleter`: 削除権限 - 削除ボタンが表示（ドキュメント未発行の注文のみ）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 22 | 注文一覧表示 | 主機能 | 注文の一覧表示・ステータス管理 |
| 24 | 注文キャンセル | 補助機能 | 注文のキャンセル処理 |

## 画面種別

一覧

## URL/ルーティング

- **パス**: `/admin#/sw/order/index`
- **コンポーネント**: `sw-order-list`
- **ルート名**: `sw.order.index`
- **必要権限**: `order.viewer`

## 入出力項目

| 項目名 | 種別 | 型 | 必須 | 説明 |
|--------|------|-----|------|------|
| term | 入力 | string | - | 検索キーワード |
| page | 入力 | number | - | ページ番号 |
| limit | 入力 | number | - | 1ページあたりの表示件数 |
| sortBy | 入力 | string | - | ソート対象カラム（デフォルト: orderDateTime） |
| sortDirection | 入力 | string | - | ソート方向（DESC/ASC） |
| filterCriteria | 入力 | array | - | フィルター条件配列 |

## 表示項目

| 項目名 | カラム名 | 説明 | 編集可否 |
|--------|----------|------|----------|
| 注文番号 | orderNumber | 注文を識別する一意の番号、詳細へのリンク | - |
| 販売チャネル | salesChannel.name | 注文が発生した販売チャネル名（デフォルト非表示） | - |
| 顧客名 | orderCustomer.firstName/lastName | 注文した顧客の氏名 | - |
| 会社名 | orderCustomer.company | 顧客の会社名（デフォルト非表示） | - |
| 請求先住所 | billingAddress.street | 請求先住所（デフォルト非表示） | - |
| 配送先住所 | primaryOrderDelivery.shippingOrderAddress.street | 配送先住所 | - |
| 金額 | amountTotal | 注文の合計金額（通貨フォーマット） | - |
| 注文ステータス | stateMachineState.name | 注文の現在のステータス | - |
| 支払ステータス | primaryOrderTransaction.stateMachineState.name | 支払いの現在のステータス | - |
| 配送ステータス | primaryOrderDelivery.stateMachineState.name | 配送の現在のステータス | - |
| 注文日時 | orderDateTime | 注文が作成された日時 | - |
| アフィリエイトコード | affiliateCode | アフィリエイトコード（デフォルト非表示） | string |
| キャンペーンコード | campaignCode | キャンペーンコード（デフォルト非表示） | string |

## イベント仕様

### 1-ページ読み込み（createdComponent）

画面初期表示時に注文一覧を取得する。

**処理フロー**:
1. `getList()` メソッドが呼び出される
2. `orderCriteria` を構築（ページネーション、ソート、フィルター条件を含む）
3. `orderRepository.search()` で注文データを取得
4. 取得結果を `orders` データに格納し表示

### 2-検索実行

検索ボックスにキーワードを入力し検索を実行。

**処理フロー**:
1. 検索キーワードが `term` にセット
2. `orderCriteria` が再構築され `setTerm()` で検索条件追加
3. `getList()` が実行され検索結果を表示

### 3-フィルター適用（updateCriteria）

各種フィルター条件を選択・適用。

**対応フィルター**:
- 注文番号フィルター
- 顧客番号フィルター
- アフィリエイトコードフィルター
- キャンペーンコードフィルター
- プロモーションコードフィルター
- ドキュメントフィルター
- 注文日フィルター
- 注文金額フィルター
- ステータスフィルター（注文/支払/配送）
- 支払方法フィルター
- 配送方法フィルター
- 販売チャネルフィルター
- 請求国フィルター
- 配送国フィルター
- 顧客グループフィルター
- タグフィルター
- 商品フィルター

### 4-注文編集（onEdit）

注文行をクリックまたは編集ボタンをクリック。

**処理フロー**:
1. 選択された注文のIDを取得
2. `$router.push()` で `sw.order.detail` へ遷移

### 5-注文削除（onConfirmDelete）

削除ボタンをクリックし確認モーダルで確定。

**処理フロー**:
1. 削除確認モーダルを表示
2. 確定時、`orderRepository.delete(id)` を実行
3. 成功後、選択解除して一覧を再取得

### 6-一括編集（onBulkEditItems）

複数注文を選択し一括編集ボタンをクリック。

**処理フロー**:
1. 選択された注文の配送情報を確認
2. 配送情報がない注文がある場合、フラグを設定
3. `sw.bulk.edit.order` 画面へ遷移

### 7-インライン編集保存（onInlineEditSave）

アフィリエイトコード/キャンペーンコードをインライン編集。

**処理フロー**:
1. 編集した注文オブジェクトの `save()` メソッドを呼び出し
2. 変更がDBに保存される

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 注文一覧取得 | order | SELECT | 注文データの取得（関連テーブル含む） |
| インライン編集保存 | order | UPDATE | affiliateCode, campaignCode の更新 |
| 注文削除 | order | DELETE | 注文データの削除 |

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

#### order

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | * | ページネーション、ソート、フィルター条件に基づく | 関連テーブルも含む |
| UPDATE | affiliate_code | 入力値 | インライン編集時 |
| UPDATE | campaign_code | 入力値 | インライン編集時 |
| DELETE | - | id指定 | ドキュメント未発行の注文のみ削除可能 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|----------|
| sw-order.list.deleteModalTitle | 確認 | 削除の確認 | 削除モーダル表示時 |
| sw-order.list.deleteModalContent | 確認 | この注文を削除してもよろしいですか？ | 削除モーダル表示時 |
| sw-privileges.tooltip.warning | 警告 | 権限がありません | 権限不足時 |

## 例外処理

| 例外ケース | 処理内容 |
|-----------|---------|
| 検索結果0件 | 「該当するデータがありません」メッセージを表示 |
| 権限不足 | 削除ボタンを無効化、ツールチップで権限不足を通知 |
| ドキュメント発行済み注文の削除試行 | 削除ボタンを無効化 |
| API通信エラー | ローディング表示を解除、エラー通知を表示 |

## 備考

- 注文にドキュメント（請求書など）が発行されている場合、その注文は削除できない仕様
- フィルター設定はユーザー設定として保存され、次回アクセス時も維持される（`grid.filter.order` キー）
- 検索はフルテキスト検索を使用し、クエリスコアリングが適用される
- v6.8.0以降、`primaryOrderTransaction`/`primaryOrderDelivery` の直接アクセスに移行予定

---

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

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

### 推奨読解順序

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

まず、注文エンティティとその関連エンティティの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | OrderEntity | `src/Core/Checkout/Order/OrderEntity.php` | 注文エンティティの定義、リレーション |
| 1-2 | OrderDefinition | `src/Core/Checkout/Order/OrderDefinition.php` | DBスキーマ定義、関連テーブル |

**読解のコツ**: Shopwareのエンティティは`EntityDefinition`でスキーマを定義し、`Entity`クラスでランタイムのデータを保持する二層構造になっている。

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

モジュール定義とルーティングの設定を確認。

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

**主要処理フロー**:
1. **122-199行**: `Module.register('sw-order', ...)` でモジュールを登録
2. **134-146行**: `routes.index` で一覧画面のルート定義
3. **181-196行**: `navigation` でメニュー項目を定義

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | sw-order-list/index.js | `src/Administration/Resources/app/administration/src/module/sw-order/page/sw-order-list/index.js` | Vue.jsコンポーネントの定義 |

**主要処理フロー**:
- **27-65行**: `data()` - コンポーネントの状態定義（orders, filterCriteria等）
- **83-127行**: `orderCriteria` - 検索条件の構築（Criteria APIの使用）
- **356-385行**: `getList()` - 注文データ取得処理
- **404-484行**: `getOrderColumns()` - テーブルカラム定義

#### Step 4: ACL（権限制御）を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | acl/index.js | `src/Administration/Resources/app/administration/src/module/sw-order/acl/index.js` | 権限マッピング定義 |

**主要処理フロー**:
- **21-61行**: `viewer` ロール - 閲覧に必要な権限一覧
- **62-91行**: `editor` ロール - 編集に必要な追加権限
- **92-109行**: `creator` ロール - 作成に必要な追加権限
- **110-117行**: `deleter` ロール - 削除権限

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

```
sw-order-list (Vue Component)
    │
    ├─ createdComponent()
    │      └─ getList()
    │             ├─ filterService.mergeWithStoredFilters()
    │             ├─ addQueryScores()
    │             └─ orderRepository.search(criteria)
    │                    └─ Shopware API (POST /api/search/order)
    │
    ├─ onEdit(order)
    │      └─ $router.push({ name: 'sw.order.detail' })
    │
    ├─ onConfirmDelete(id)
    │      └─ orderRepository.delete(id)
    │             └─ Shopware API (DELETE /api/order/{id})
    │
    └─ onBulkEditItems()
           └─ $router.push({ name: 'sw.bulk.edit.order' })
```

### データフロー図

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

検索キーワード ─────────┐
                        │
フィルター条件 ─────────┼──▶ sw-order-list Component
                        │         │
ソート設定 ─────────────┘         ├──▶ orderCriteria構築
                                  │         │
                                  │         ▼
                                  │    Criteria API
                                  │         │
                                  │         ▼
                                  │    orderRepository.search()
                                  │         │
                                  │         ▼
                                  │    Shopware API
                                  │         │
                                  │         ▼
                                  └──▶ orders データ ──▶ 注文一覧表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.js | `src/Administration/Resources/app/administration/src/module/sw-order/index.js` | ソース | モジュール定義 |
| sw-order-list/index.js | `src/Administration/Resources/app/administration/src/module/sw-order/page/sw-order-list/index.js` | ソース | 一覧画面コンポーネント |
| sw-order-list.html.twig | `src/Administration/Resources/app/administration/src/module/sw-order/page/sw-order-list/sw-order-list.html.twig` | テンプレート | 画面テンプレート |
| sw-order-list.scss | `src/Administration/Resources/app/administration/src/module/sw-order/page/sw-order-list/sw-order-list.scss` | スタイル | 画面スタイル |
| acl/index.js | `src/Administration/Resources/app/administration/src/module/sw-order/acl/index.js` | ソース | 権限定義 |
| default-search-configuration.js | `src/Administration/Resources/app/administration/src/module/sw-order/default-search-configuration.js` | ソース | 検索設定 |
| OrderDefinition.php | `src/Core/Checkout/Order/OrderDefinition.php` | ソース | エンティティ定義 |
| OrderEntity.php | `src/Core/Checkout/Order/OrderEntity.php` | ソース | エンティティクラス |
