# 画面設計書 80-顧客詳細画面

## 概要

本ドキュメントは、Medusa Admin Dashboardにおける「顧客詳細画面」の画面設計書です。特定の顧客の詳細情報を表示し、編集・削除・注文管理・グループ管理・住所管理を行うための画面について記述します。

### 本画面の処理概要

この画面では、選択された顧客の詳細情報を2カラムレイアウトで表示します。メインエリアには基本情報、注文履歴、所属グループが、サイドバーには住所情報が表示されます。

**業務上の目的・背景**：顧客詳細画面は、個別の顧客に対するカスタマーサポートや顧客管理の中心となる画面です。顧客の注文履歴確認、所属グループの管理、住所情報の確認・編集など、顧客に関するあらゆる情報を一元的に確認・管理できます。

**画面へのアクセス方法**：顧客一覧画面の行クリック、またはURL `/customers/{id}` に直接アクセスすることで表示されます。

**主要な操作・処理内容**：
1. 顧客の基本情報（メールアドレス、名前、会社名、電話番号、アカウント状態）の表示
2. 注文履歴の表示と検索・フィルタリング
3. 所属顧客グループの表示と管理（追加・削除）
4. 住所情報の表示と管理（追加・削除）
5. 顧客情報の編集
6. 顧客の削除

**画面遷移**：
- 遷移元：顧客一覧画面
- 遷移先：顧客編集画面（edit）、顧客グループ追加画面（add-customer-groups）、住所作成画面（create-address）、注文詳細画面、顧客グループ詳細画面

**権限による表示制御**：認証済みユーザーのみアクセス可能です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 49 | 顧客管理 | 主機能 | 顧客詳細の表示・管理 |

## 画面種別

詳細画面（TwoColumnPage）

## URL/ルーティング

`/customers/:id`

## 入出力項目

### パスパラメータ（入力）

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| id | string | Yes | 顧客のID |

## 表示項目

### 画面レイアウト

```
+------------------------------------------+
| General Section                     [edit]|
| ----------------------------------------- |
| Email: {customer.email}   [Status Badge] |
| Name: {first_name} {last_name}           |
| Company: {company_name}                  |
| Phone: {phone}                           |
+------------------------------------------+

+------------------------------------------+
| Orders Section                           |
| ----------------------------------------- |
| [Search] [Filter] [Sort]                 |
| +-------+--------+--------+--------+     |
| | Order | Date   | Status | Total  |     |
| +-------+--------+--------+--------+     |
| | ...   | ...    | ...    | ...    |     |
| +-------+--------+--------+--------+     |
| [Pagination]                             |
+------------------------------------------+

+------------------------------------------+
| Customer Groups Section            [add] |
| ----------------------------------------- |
| [Search] [Filter]                        |
| +-------+--------+--------+              |
| | Name  | Members| Actions|              |
| +-------+--------+--------+              |
| | ...   | ...    | ...    |              |
| +-------+--------+--------+              |
+------------------------------------------+

サイドバー:
+------------------------------------------+
| Addresses Section                  [add] |
| ----------------------------------------- |
| Address 1: {address_1}      [delete]     |
| Address 2: {address_2}      [delete]     |
+------------------------------------------+
```

### General Section（基本情報）

| 項目名 | データ型 | 説明 |
|--------|---------|------|
| Email | string | メールアドレス（ヘッダー表示） |
| Status | StatusBadge | アカウント状態（Registered: green/Guest: orange） |
| Name | string | 名前（first_name + last_name） |
| Company | string | 会社名 |
| Phone | string | 電話番号 |

### Orders Section（注文履歴）

| 列名 | データ型 | 説明 |
|------|---------|------|
| Order ID | string | 注文表示ID |
| Date | Date | 注文日時 |
| Fulfillment Status | string | フルフィルメント状態 |
| Payment Status | string | 支払い状態 |
| Total | number | 合計金額 |
| Actions | ActionMenu | 所有権移転アクション |

### Customer Groups Section（顧客グループ）

| 列名 | データ型 | 説明 |
|------|---------|------|
| Checkbox | boolean | 行選択チェックボックス |
| Name | string | グループ名 |
| Members | number | メンバー数 |
| Actions | ActionMenu | 編集・削除アクション |

### Addresses Section（住所情報）

| 項目名 | データ型 | 説明 |
|--------|---------|------|
| Address Name | string | 住所の名称 |
| Address Line | string | 住所（address_1 + address_2） |

## イベント仕様

### 1-基本情報編集ボタン押下

General Sectionのアクションメニューから「Edit」を選択すると、顧客編集画面（`/customers/{id}/edit`）に遷移します。

### 2-顧客削除

General Sectionのアクションメニューから「Delete」を選択すると、確認ダイアログが表示されます。メールアドレスを入力して確認後、顧客が削除され、一覧画面に遷移します。

### 3-注文行クリック

注文履歴の行をクリックすると、該当注文の詳細画面（`/orders/{order_id}`）に遷移します。

### 4-顧客グループ追加ボタン押下

Customer Groups Sectionの「Add」ボタンをクリックすると、顧客グループ追加画面（`/customers/{id}/add-customer-groups`）に遷移します。

### 5-顧客グループ削除

グループ行のアクションメニューから「Remove」を選択、または選択したグループを一括削除すると、確認ダイアログが表示されます。確認後、顧客がグループから削除されます。

### 6-住所追加ボタン押下

Addresses Sectionの「Add」リンクをクリックすると、住所作成画面（`/customers/{id}/create-address`）に遷移します。

### 7-住所削除

住所のアクションメニューから「Delete」を選択すると、確認ダイアログが表示されます。確認後、住所が削除されます。

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 画面表示 | customer | SELECT | 顧客詳細の取得（住所含む） |
| 画面表示 | order | SELECT | 注文履歴の取得 |
| 画面表示 | customer_group | SELECT | 所属グループの取得 |
| 顧客削除 | customer | DELETE | 顧客の削除 |
| グループ削除 | customer_group_customer | DELETE | グループからの削除 |
| 住所削除 | customer_address | DELETE | 住所の削除 |

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

#### customer（削除時）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | id | 現在の顧客ID | |

#### customer_group_customer（グループ削除時）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | customer_id | 現在の顧客ID | |
| DELETE | customer_group_id | 削除対象グループID | 複数指定可能 |

#### customer_address（住所削除時）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | id | 削除対象住所ID | |

## メッセージ仕様

| 種別 | 条件 | メッセージ |
|------|------|-----------|
| 成功 | 顧客削除成功時 | Customer {email} was successfully deleted. |
| 成功 | グループ削除成功時 | Customer removed from {group_names}. |
| 成功 | 住所削除成功時 | Address {address_name} was successfully deleted. |
| 確認 | 顧客削除確認時 | Are you sure you want to delete {email}? (入力確認付き) |
| 確認 | グループ削除確認時 | Are you sure you want to remove customer from {group_name}? |
| 確認 | 住所削除確認時 | Are you sure you want to delete {address_name}? (入力確認付き) |
| エラー | API呼び出し失敗時 | エラーメッセージをトースト表示 |

## 例外処理

| 状態 | 処理 |
|------|------|
| 顧客が存在しない場合 | エラーをスローし、エラーバウンダリーで捕捉 |
| データ取得中 | SingleColumnPageSkeletonを表示 |
| API エラー発生時 | エラーメッセージをトースト表示 |

## 備考

- TwoColumnPageレイアウトを使用
- showJSON=true, showMetadata=trueでJSONビューワーとメタデータを表示
- hasOutlet=trueで子ルートをサポート
- ウィジェット拡張ポイント（before/after/sideBefore/sideAfter）あり
- 注文テーブルのページサイズは10件
- 顧客グループテーブルのページサイズは10件
- useLoaderDataでデータプリフェッチをサポート

---

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

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

### 推奨読解順序

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

ページコンポーネントの構成とデータ取得処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | customer-detail.tsx | `packages/admin/dashboard/src/routes/customers/customer-detail/customer-detail.tsx` | TwoColumnPage構成、useCustomerでのデータ取得 |

**主要処理フロー**:
1. **14行目**: useParamsでURLからid取得
2. **16-18行目**: useLoaderDataでプリフェッチデータ取得
3. **19-23行目**: useCustomerで顧客データ取得（住所含む）
4. **25行目**: useExtensionでウィジェット取得
5. **36-57行目**: TwoColumnPageでレイアウト構成

#### Step 2: General Sectionを理解する

基本情報表示セクションを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | customer-general-section.tsx | `packages/admin/dashboard/src/routes/customers/customer-detail/components/customer-general-section/customer-general-section.tsx` | 基本情報表示、削除処理 |

**主要処理フロー**:
- **28行目**: useDeleteCustomerでミューテーション
- **30-32行目**: 名前の組み立て
- **34-37行目**: ステータスの色と表示テキスト
- **39-68行目**: handleDelete - 確認ダイアログと削除処理

#### Step 3: Orders Sectionを理解する

注文履歴セクションを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | customer-order-section.tsx | `packages/admin/dashboard/src/routes/customers/customer-detail/components/customer-order-section/customer-order-section.tsx` | 注文一覧表示 |

**主要処理フロー**:
- **31-44行目**: useOrdersで注文取得（customer_idでフィルタ）
- **73-90行目**: _DataTableでテーブル表示

#### Step 4: Customer Groups Sectionを理解する

顧客グループセクションを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | customer-group-section.tsx | `packages/admin/dashboard/src/routes/customers/customer-detail/components/customer-group-section/customer-group-section.tsx` | グループ一覧表示、削除処理 |

**主要処理フロー**:
- **49-59行目**: useCustomerGroupsで所属グループ取得
- **61-62行目**: useBatchCustomerCustomerGroupsでグループ関係管理
- **82-118行目**: handleRemoveで一括削除処理

#### Step 5: Addresses Sectionを理解する

住所セクションを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | customer-address-section.tsx | `packages/admin/dashboard/src/routes/customers/customer-detail/components/customer-address-section/customer-address-section.tsx` | 住所一覧表示、削除処理 |

**主要処理フロー**:
- **22行目**: useDeleteCustomerAddressでミューテーション
- **26-55行目**: handleDelete - 確認ダイアログと削除処理

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

```
CustomerDetail (customer-detail.tsx)
    │
    ├─ useLoaderData() - プリフェッチデータ
    │
    ├─ useCustomer() - 顧客詳細取得（+*addresses）
    │
    ├─ useExtension() - ウィジェット取得
    │
    └─ TwoColumnPage
           │
           ├─ Main
           │    │
           │    ├─ CustomerGeneralSection
           │    │      │
           │    │      ├─ useDeleteCustomer()
           │    │      │
           │    │      └─ ActionMenu (Edit/Delete)
           │    │
           │    ├─ CustomerOrderSection
           │    │      │
           │    │      ├─ useOrderTableQuery()
           │    │      │
           │    │      ├─ useOrders() - 注文取得
           │    │      │
           │    │      └─ _DataTable
           │    │
           │    └─ CustomerGroupSection
           │           │
           │           ├─ useCustomerGroupTableQuery()
           │           │
           │           ├─ useCustomerGroups()
           │           │
           │           ├─ useBatchCustomerCustomerGroups()
           │           │
           │           └─ _DataTable
           │
           └─ Sidebar
                └─ CustomerAddressSection
                       │
                       ├─ useDeleteCustomerAddress()
                       │
                       └─ Listicle (住所表示)
```

### データフロー図

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

URL param (id) ──────▶ useCustomer() ──────▶ customer (with addresses)

customer.id ──────▶ useOrders() ──────▶ orders
                    (customer_id filter)

customer.id ──────▶ useCustomerGroups() ──────▶ customer_groups
                    (customers.id filter)

顧客削除 ──────▶ useDeleteCustomer()
                   │
                   └─▶ navigate("/customers")

グループ削除 ──────▶ useBatchCustomerCustomerGroups()
                      │
                      └─▶ { remove: groupIds }

住所削除 ──────▶ useDeleteCustomerAddress()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| customer-detail.tsx | `packages/admin/dashboard/src/routes/customers/customer-detail/customer-detail.tsx` | ソース | ページコンポーネント |
| customer-general-section.tsx | `packages/admin/dashboard/src/routes/customers/customer-detail/components/customer-general-section/customer-general-section.tsx` | ソース | 基本情報セクション |
| customer-order-section.tsx | `packages/admin/dashboard/src/routes/customers/customer-detail/components/customer-order-section/customer-order-section.tsx` | ソース | 注文履歴セクション |
| customer-group-section.tsx | `packages/admin/dashboard/src/routes/customers/customer-detail/components/customer-group-section/customer-group-section.tsx` | ソース | 顧客グループセクション |
| customer-address-section.tsx | `packages/admin/dashboard/src/routes/customers/customer-detail/components/customer-address-section/customer-address-section.tsx` | ソース | 住所セクション |
| customers.tsx | `packages/admin/dashboard/src/hooks/api/customers.tsx` | ソース | API呼び出しフック |
| loader.ts | `packages/admin/dashboard/src/routes/customers/customer-detail/loader.ts` | ソース | データローダー |
