# 画面設計書 56-請求先住所編集画面

## 概要

本ドキュメントは、Medusa Admin Dashboard における「請求先住所編集画面」の設計仕様を定義するものである。

### 本画面の処理概要

**業務上の目的・背景**：EC運営において、顧客が注文後に請求先住所の変更を希望する場合や、入力ミスの修正が必要な場合がある。本画面は、管理者が注文に紐づく請求先住所を編集するためのインターフェースを提供する。これにより、請求書や領収書の送付先を適切に管理できる。

**画面へのアクセス方法**：注文詳細画面から「請求先住所編集」アクションを選択することでアクセスする。

**主要な操作・処理内容**：
1. 現在の請求先住所情報を確認する
2. 各住所フィールドを編集する
3. 保存ボタンを押下して請求先住所を更新する

**画面遷移**：
- 遷移元：注文詳細画面（`/orders/:id`）
- 遷移先：更新完了後、注文詳細画面に戻る

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 26 | 注文情報更新 | 主機能 | 請求先住所の更新 |

## 画面種別

編集（ドロワー形式）

## URL/ルーティング

```
/orders/:id/billing-address
```

## 入出力項目

| 項目名 | 項目ID | データ型 | 必須 | 入力形式 | バリデーション | 説明 |
|--------|--------|----------|------|----------|----------------|------|
| 住所1 | address_1 | string | ○ | テキスト | 最小1文字 | 番地・建物名等 |
| 住所2 | address_2 | string | - | テキスト | - | 追加住所情報 |
| 郵便番号 | postal_code | string | - | テキスト | - | 郵便番号 |
| 市区町村 | city | string | - | テキスト | - | 市区町村名 |
| 国 | country_code | string | ○ | セレクト（無効） | 2文字 | 国コード（変更不可） |
| 都道府県 | province | string | - | テキスト | - | 都道府県・州 |
| 名 | first_name | string | - | テキスト | - | 名 |
| 姓 | last_name | string | - | テキスト | - | 姓 |
| 会社名 | company | string | - | テキスト | - | 会社名 |
| 電話番号 | phone | string | - | テキスト | - | 電話番号 |

## 表示項目

| 項目名 | 表示形式 | 説明 |
|--------|----------|------|
| ヘッダータイトル | テキスト | 「請求先住所編集」 |
| 国選択 | セレクト（無効） | 現在の国コードを表示、変更不可 |

## イベント仕様

### 1-各フィールド入力

各住所フィールドに入力があった場合：
- 入力値をフォーム状態に保存
- Zodによるリアルタイムバリデーション

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

保存ボタンが押下された場合：
1. フォームバリデーションを実行
2. `useUpdateOrder`フックを使用してAPI呼び出し
3. APIエンドポイント：`POST /admin/orders/:id`
4. リクエストボディ：`{ billing_address: { address_1, address_2, ... } }`
5. 成功時：トースト通知を表示し、ドロワーを閉じる
6. 失敗時：エラーメッセージをトーストで表示

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

キャンセルボタンが押下された場合：
- フォームの変更を破棄
- ドロワーを閉じて注文詳細画面に戻る

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 保存ボタン押下 | address | UPDATE | 請求先住所の更新 |
| 保存ボタン押下 | order | UPDATE | 更新日時の更新 |

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

#### address（billing_address）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | first_name | 入力値 | 任意 |
| UPDATE | last_name | 入力値 | 任意 |
| UPDATE | address_1 | 入力値 | 必須 |
| UPDATE | address_2 | 入力値 | 任意 |
| UPDATE | city | 入力値 | 任意 |
| UPDATE | postal_code | 入力値 | 任意 |
| UPDATE | province | 入力値 | 任意 |
| UPDATE | company | 入力値 | 任意 |
| UPDATE | phone | 入力値 | 任意 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| requestSuccess | 成功 | 「請求先住所を更新しました」 | 更新成功時 |
| error | エラー | APIから返されたエラーメッセージ | 更新失敗時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 注文が見つからない | エラーをスローし、エラーページを表示 |
| 必須フィールド未入力 | フォームバリデーションエラーを表示 |
| ネットワークエラー | エラートーストを表示 |

## 備考

- 国コードは変更不可（税計算設定との整合性維持のため）
- 配送先住所編集画面とほぼ同一の構造だが、billing_addressとして送信される点が異なる
- フォームエラーがある場合、保存ボタンが無効化される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | EditOrderBillingAddressSchema | `packages/admin/dashboard/src/routes/orders/order-edit-billing-address/components/edit-order-billing-address-form/edit-order-billing-address-form.tsx` | Zodスキーマ（18-29行目） |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | OrderEditBillingAddress | `packages/admin/dashboard/src/routes/orders/order-edit-billing-address/order-edit-billing-address.tsx` | 画面コンポーネント |

**主要処理フロー**:
1. **14-16行目**: useOrderフックで注文データを取得
2. **28行目**: EditOrderBillingAddressFormコンポーネントをレンダリング

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | EditOrderBillingAddressForm | `packages/admin/dashboard/src/routes/orders/order-edit-billing-address/components/edit-order-billing-address-form/edit-order-billing-address-form.tsx` | 編集フォームの実装 |

**主要処理フロー**:
- **37-51行目**: useFormによるフォーム初期化、デフォルト値設定
- **53行目**: useUpdateOrderフックの取得
- **55-65行目**: フォーム送信ハンドラ（billing_addressとして送信）
- **241行目**: disabled条件でフォームエラー時に保存ボタン無効化

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

```
OrderEditBillingAddress (order-edit-billing-address.tsx)
    │
    ├─ useOrder (注文データ取得)
    │
    └─ EditOrderBillingAddressForm (edit-order-billing-address-form.tsx)
           │
           ├─ CountrySelect (国選択、disabled)
           │
           └─ useUpdateOrder (orders.tsx)
                  └─ sdk.admin.order.update
                         └─ POST /admin/orders/:id
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| order-edit-billing-address.tsx | `packages/admin/dashboard/src/routes/orders/order-edit-billing-address/order-edit-billing-address.tsx` | ソース | 画面コンポーネント |
| edit-order-billing-address-form.tsx | `packages/admin/dashboard/src/routes/orders/order-edit-billing-address/components/edit-order-billing-address-form/edit-order-billing-address-form.tsx` | ソース | 編集フォーム |
| orders.tsx | `packages/admin/dashboard/src/hooks/api/orders.tsx` | ソース | 注文APIフック |
| country-select.tsx | `packages/admin/dashboard/src/components/inputs/country-select/country-select.tsx` | ソース | 国選択コンポーネント |
