# 画面設計書 20-配送詳細画面

## 概要

本ドキュメントは、Bagisto eコマースモバイルアプリにおける配送詳細画面の設計仕様を定義するものです。配送詳細画面は、注文に関連する配送情報（トラッキング番号、配送商品一覧）の詳細を表示する画面です。

### 本画面の処理概要

配送詳細画面は、注文の配送追跡情報（トラッキング番号、配送商品の一覧）を表示する画面です。

**業務上の目的・背景**：配送詳細画面は、ユーザーが注文した商品の配送状況を確認するための画面です。トラッキング番号を表示することで、ユーザーが配送業者のサイトで荷物を追跡できるようにします。また、どの商品が配送されたかの明細を確認できます。複数回に分けて配送される場合も、各配送（Shipment）の情報を個別に表示します。

**画面へのアクセス方法**：
- 注文詳細画面から「配送」ボタンをタップ

**主要な操作・処理内容**：
1. 配送情報の取得・表示
2. トラッキング番号の表示
3. 配送ID（Shipment #ID）の表示
4. 配送商品の明細表示（SKU、名前、数量）
5. 配送先・支払い情報の表示

**画面遷移**：
- 遷移元：注文詳細画面
- 遷移先：なし（情報表示のみ）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 46 | 配送詳細表示 | 主機能 | 注文の配送追跡情報表示（トラッキング番号、配送商品一覧） |

## 画面種別

詳細

## URL/ルーティング

```dart
const String shipmentDetails = "shipmentDetails";
```

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

## 入出力項目

| 項目名 | 入力/出力 | 型 | 必須 | 説明 |
|--------|----------|-----|------|------|
| orderDetailsModel | 入力 | OrderDetail? | ○ | 注文詳細データ（注文IDを含む） |

## 表示項目

| No | 項目名 | 型 | 表示条件 | 説明 |
|----|--------|-----|----------|------|
| 1 | AppBar | AppBar | 常時 | タイトル「配送」 |
| 2 | トラッキング番号 | Text | 常時 | 「Tracking Number: xxx」形式で表示 |
| 3 | 配送ID | Text | 常時 | 「Shipment #ID」形式で表示 |
| 4 | 商品一覧 | ListView | 常時 | 配送商品のリスト |
| 5 | SKU | Text | 常時 | 商品SKUコード |
| 6 | 商品名 | Text | 常時 | 商品名 |
| 7 | 数量 | Text | 常時 | 配送数量 |
| 8 | 配送・支払い情報 | ShippingAndPaymentInfo | 常時 | 配送先、支払い方法 |
| 9 | ローディング | Loader | 読み込み中 | データ取得中の表示 |
| 10 | 空状態表示 | EmptyDataView | 配送情報なし | 配送情報がない場合の表示 |

## イベント仕様

### 1-配送データ取得

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

**処理フロー**：
1. `OrderShipmentsBloc`に`OrderShipmentsFetchDataEvent(orderId)`を発行
2. `OrderShipmentsRepositoryImp.getShipmentsList(orderId)`でAPIを呼び出し
3. 取得したデータを`ShipmentModel`モデルに変換
4. `OrderShipmentsListDataState.success`を発行しUIを更新

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 配送情報取得 | order_shipments, order_shipment_items | SELECT | 注文の配送情報を取得 |

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

#### order_shipments

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, track_number | order_idで絞り込み | 配送情報取得 |

#### order_shipment_items

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | sku, name, qty | shipment_idで絞り込み | 配送商品明細取得 |

## メッセージ仕様

| No | メッセージID | メッセージ内容 | 表示タイミング | 種別 |
|----|------------|---------------|--------------|------|
| 1 | shipment | 配送 | AppBarタイトル | 情報 |
| 2 | trackingNumber | Tracking Number | トラッキング番号ラベル | 情報 |
| 3 | sku | SKU | 商品詳細ラベル | 情報 |
| 4 | name | 名前 | 商品詳細ラベル | 情報 |
| 5 | qty | 数量 | 商品詳細ラベル | 情報 |

## 例外処理

| No | 例外状況 | 対応処理 |
|----|---------|---------|
| 1 | 配送データなし | `EmptyDataView`を表示 |
| 2 | API通信エラー | エラー表示 |

## 備考

- 配送は注文に対して複数発生する可能性あり（分割配送など）
- 各配送（Shipment）の商品明細を`ListView.separated`で表示
- トラッキング番号は太字で強調表示
- `ShippingAndPaymentInfo`コンポーネントで配送先・支払い情報を共通表示
- `NeverScrollableScrollPhysics()`で内部ListViewのスクロールを無効化
- 請求書詳細画面とUIパターンが類似

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | shipment_model.dart | `lib/screens/order_shipping/data_model/shipment_model.dart`（推定） | ShipmentModel、ViewShipments、Items構造 |

**読解のコツ**: `ShipmentModel`には`viewShipments`（配送リスト）が含まれ、各配送には`trackNumber`と`items`（配送商品明細）が含まれます。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | shipments_details.dart | `lib/screens/order_shipping/shipments_details.dart` | OrderShipmentsScreenクラス |

**主要処理フロー**:
1. **行18-23**: initStateでBloc取得、`OrderShipmentsFetchDataEvent`発行
2. **行25-37**: buildメソッドでScaffold構築
3. **行39-55**: BlocConsumerで状態に応じたUI構築
4. **行57-83**: `shipmentsDetails`で配送詳細表示
5. **行106-150**: `getShipments`で配送リスト表示

#### Step 3: 状態管理（BLoC）を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | order_shipments_bloc.dart | `lib/screens/order_shipping/bloc/order_shipments_bloc.dart` | 配送情報取得処理 |
| 3-2 | order_shipments_event.dart | `lib/screens/order_shipping/bloc/order_shipments_event.dart` | イベント定義 |
| 3-3 | order_shipments_state.dart | `lib/screens/order_shipping/bloc/order_shipments_state.dart` | 状態定義 |

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

```
OrderShipmentsScreen (shipments_details.dart)
    │
    ├─ OrderShipmentsBloc (order_shipments_bloc.dart)
    │      │
    │      └─ OrderShipmentsFetchDataEvent
    │             └─ OrderShipmentsRepositoryImp.getShipmentsList()
    │
    └─ shipmentsDetails()
           ├─ getShipments() - 配送リスト
           │      ├─ トラッキング番号表示
           │      └─ ListView.separated - 商品明細
           │
           └─ ShippingAndPaymentInfo - 配送・支払い情報
```

### データフロー図

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

OrderDetailScreen ──────▶ OrderShipmentsScreen
      │                        │
      │ orderDetailsModel      │
      └──────────▶ initState ──────────▶ OrderShipmentsBloc
                                              │
                                              └─ OrderShipmentsRepositoryImp
                                                       │
                                                       └─ ShipmentModel
                                                              │
                                                              └─ shipmentsDetails() → UI表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| shipments_details.dart | `lib/screens/order_shipping/shipments_details.dart` | ソース | メイン画面ウィジェット |
| order_shipments_bloc.dart | `lib/screens/order_shipping/bloc/order_shipments_bloc.dart` | ソース | 状態管理BLoC |
| order_shipments_event.dart | `lib/screens/order_shipping/bloc/order_shipments_event.dart` | ソース | イベント定義 |
| order_shipments_state.dart | `lib/screens/order_shipping/bloc/order_shipments_state.dart` | ソース | 状態定義 |
| order_shipments_repository.dart | `lib/screens/order_shipping/bloc/order_shipments_repository.dart` | ソース | API通信 |
| shipping_payment_info.dart | `lib/screens/order_detail/widgets/shipping_payment_info.dart` | ソース | 配送/支払いWidget |
| index.dart | `lib/screens/order_shipping/utils/index.dart` | ソース | エクスポート集約 |
| route_constants.dart | `lib/utils/route_constants.dart` | 設定 | ルート定数定義 |
