# 画面設計書 15-チェックアウト住所選択画面

## 概要

本ドキュメントは、Bagisto eコマースモバイルアプリにおけるチェックアウト住所選択画面の設計仕様を定義するものです。チェックアウト住所選択画面は、チェックアウトプロセス中に登録済み住所から配送先を選択するための画面です。

### 本画面の処理概要

チェックアウト住所選択画面は、ログインユーザーがチェックアウト時に登録済みの住所一覧から配送先または請求先住所を選択するための画面です。

**業務上の目的・背景**：チェックアウトプロセスにおいて、配送先住所の指定は必須です。ユーザーが事前に登録した複数の住所から選択できるようにすることで、住所入力の手間を省き、スムーズな購入体験を提供します。新規住所の追加や既存住所の編集も可能にすることで、柔軟な住所管理を実現します。

**画面へのアクセス方法**：
- チェックアウト画面のステップ1（住所選択）で「住所を変更」をタップ
- チェックアウト画面の住所選択ビューから遷移

**主要な操作・処理内容**：
1. 登録済み住所の一覧表示
2. 住所のタップで選択し、前画面に戻る
3. 住所情報（名前、住所、電話番号）の表示

**画面遷移**：
- 遷移元：チェックアウト画面（ステップ1）
- 遷移先：住所追加・編集画面、前画面（住所選択完了時）

**権限による表示制御**：本画面はログインユーザー専用です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 37 | 配送先住所選択 | 主機能 | チェックアウト時の配送先住所選択 |
| 52 | 住所一覧表示 | 補助機能 | 登録済み住所の一覧から選択 |

## 画面種別

一覧（選択）

## URL/ルーティング

```dart
const String checkOutAddressList = 'checkOutAddressList';
```

ルート定義：`Navigator.pushNamed(context, checkOutAddressList, arguments: addressModel)`

## 入出力項目

| 項目名 | 入力/出力 | 型 | 必須 | 説明 |
|--------|----------|-----|------|------|
| addressModel | 入力 | AddressModel | ○ | 現在の住所一覧データ |
| - | 出力（pop） | AddressData | ○ | 選択した住所データ |

## 表示項目

| No | 項目名 | 型 | 表示条件 | 説明 |
|----|--------|-----|----------|------|
| 1 | AppBar | AppBar | 常時 | タイトル「住所」 |
| 2 | 住所リスト | ListView | 住所あり | 登録済み住所の一覧 |
| 3 | 住所カード | Card | 住所あり | 各住所の詳細情報を表示 |
| 4 | 名前 | Text | 住所あり | 姓・名の表示 |
| 5 | 住所詳細 | Text | 住所あり | 住所、市区町村、都道府県、国、郵便番号 |
| 6 | 電話番号 | Text | 住所あり | Mobile: xxx形式で表示 |
| 7 | ローディング | Loader | 読み込み中 | データ取得中の表示 |

## イベント仕様

### 1-住所一覧取得

**トリガー**：画面初期表示時

**処理フロー**：
1. 入力パラメータの`addressModel`を初期値として設定
2. `CheckOutBloc`に`CheckOutAddressEvent`を発行（最新データ取得）
3. 取得したデータを`AddressModel`モデルに変換
4. `CheckOutAddressState`を発行しUIを更新

### 2-住所選択

**トリガー**：住所カードをタップ

**処理フロー**：
1. タップした住所の`AddressData`を取得
2. `Navigator.of(context).pop(addressData)`で前画面に選択結果を返す
3. チェックアウト画面で選択した住所を設定

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 住所一覧取得 | customer_addresses | SELECT | ユーザーの登録済み住所を取得 |

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

#### customer_addresses

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, first_name, last_name, address1, city, state_name, country_name, postcode, phone | customer_idで絞り込み | 全住所取得 |

## メッセージ仕様

| No | メッセージID | メッセージ内容 | 表示タイミング | 種別 |
|----|------------|---------------|--------------|------|
| 1 | address | 住所 | AppBarタイトル | 情報 |
| 2 | Mobile: | Mobile: {電話番号} | 電話番号表示 | 情報 |

## 例外処理

| No | 例外状況 | 対応処理 |
|----|---------|---------|
| 1 | 住所データが空 | 空の一覧表示（住所追加を促す） |
| 2 | API通信エラー | 前画面のデータを使用して表示継続 |

## 備考

- 本画面は`Navigator.pop`で選択結果を返すダイアログ的な使用法
- 住所表示は`_getFormattedAddress`メソッドでフォーマット
- 住所文字列の`[]`を除去して表示（APIレスポンスの形式対応）
- BlocBuilderで住所一覧の状態を監視
- ローディング中はLoaderを表示

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | address_model.dart | `lib/screens/address_list/data_model/address_model.dart` | AddressModel、AddressDataクラスの構造 |

**読解のコツ**: `AddressData`には氏名、住所、郵便番号、電話番号等の住所情報が含まれます。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | checkout_address_list.dart | `lib/screens/checkout/checkout_addres/view/widget/checkout_address_list.dart` | CheckoutAddressListクラス |

**主要処理フロー**:
1. **行23-33**: initStateでaddressModelを設定、Blocを取得しイベント発行
2. **行35-46**: buildメソッドでScaffold構築
3. **行48-122**: `_getAddressList`でBlocBuilderによる住所一覧表示
4. **行68-70**: InkWellのonTapで`Navigator.pop(addressData)`
5. **行125-133**: `_getFormattedAddress`で住所フォーマット

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

```
CheckoutAddressList (checkout_address_list.dart)
    │
    ├─ CheckOutBloc (checkout_address_bloc.dart)
    │      │
    │      └─ CheckOutAddressEvent
    │             └─ CheckOutRepository.getAddressList()
    │
    └─ ListView.builder
           └─ Card (住所表示)
                  └─ InkWell (タップで選択)
                         └─ Navigator.pop(addressData)
```

### データフロー図

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

CheckoutScreen           CheckoutAddressList            CheckoutScreen
      │                        │                              │
      │ addressModel           │                              │
      └──────────▶ 初期表示 ─────────▶ 住所一覧               │
                        │                                     │
                        │ ユーザー選択                         │
                        │                                     │
                        └─── Navigator.pop(addressData) ─────▶│
                                                              │
                                                         選択住所設定
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| checkout_address_list.dart | `lib/screens/checkout/checkout_addres/view/widget/checkout_address_list.dart` | ソース | メイン画面ウィジェット |
| checkout_address_bloc.dart | `lib/screens/checkout/checkout_addres/bloc/checkout_address_bloc.dart` | ソース | 状態管理BLoC |
| checkout_address_event.dart | `lib/screens/checkout/checkout_addres/bloc/checkout_address_event.dart` | ソース | イベント定義 |
| checkout_address_state.dart | `lib/screens/checkout/checkout_addres/bloc/checkout_address_state.dart` | ソース | 状態定義 |
| checkout_address_repository.dart | `lib/screens/checkout/checkout_addres/bloc/checkout_address_repository.dart` | ソース | API通信 |
| address_model.dart | `lib/screens/address_list/data_model/address_model.dart` | ソース | 住所データモデル |
| route_constants.dart | `lib/utils/route_constants.dart` | 設定 | ルート定数定義 |
