# 機能設計書 46-配送詳細表示

## 概要

本ドキュメントは、ECモバイルアプリケーションにおける配送詳細表示機能の設計仕様を定義する。注文の配送追跡情報（トラッキング番号、配送商品一覧）を表示する機能である。

### 本機能の処理概要

この機能は、注文詳細画面から遷移し、該当注文の配送情報を詳細に表示する。配送番号（トラッキング番号）、出荷された商品の一覧、配送先・支払い情報などを確認できる。

**業務上の目的・背景**：ECサイトにおいて、配送状況の確認はユーザーの最も頻繁なニーズの一つである。トラッキング番号を確認することで、配送業者のWebサイトで詳細な配送状況を追跡できる。また、出荷された商品の確認により、部分出荷の場合に何が送られたかを把握できる。

**機能の利用シーン**：ユーザーが注文詳細画面で「配送詳細」ボタンをタップした際に利用される。商品の到着予定確認、トラッキング番号の確認、出荷済み商品の確認などに使用される。

**主要な処理内容**：
1. 注文IDに基づく配送データの取得
2. トラッキング番号と配送ID（出荷番号）の表示
3. 出荷商品一覧（SKU、商品名、数量）の表示
4. 配送先・支払い情報の表示

**関連システム・外部連携**：バックエンドのBagisto GraphQL APIと連携し、配送データを取得する。

**権限による制御**：ログイン済みユーザーのみがアクセス可能。ユーザーは自身の注文の配送情報のみを閲覧できる。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 20 | 配送詳細画面 | 主画面 | 注文の配送追跡情報表示（トラッキング番号、配送商品一覧） |
| 18 | 注文詳細画面 | 参照元画面 | 配送詳細ボタンから遷移 |

## 機能種別

データ取得 / 詳細表示

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| orderId | int | Yes | 注文の内部ID | 正の整数 |

### 入力データソース

- 画面遷移引数：OrderDetailモデル（orderIdを含む）
- ユーザーセッション：認証トークン（SharedPreferencesから取得）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| viewShipments[].id | int | 出荷ID |
| viewShipments[].trackNumber | String | トラッキング番号 |
| viewShipments[].items[].sku | String | 商品SKU |
| viewShipments[].items[].name | String | 商品名 |
| viewShipments[].items[].qty | int | 出荷数量 |

### 出力先

- 画面表示：OrderShipmentsScreenウィジェットによる配送詳細表示

## 処理フロー

### 処理シーケンス

```
1. 画面初期化（initState）
   └─ OrderShipmentsBlocを取得し、OrderShipmentsFetchDataEventを発行
2. API呼び出し
   └─ OrderShipmentsRepositoryImpがApiClient経由でGraphQL APIを呼び出し
3. レスポンス処理
   └─ ShipmentModelにデシリアライズ
4. 状態更新
   └─ OrderShipmentsListDataStateをemitしてUI更新
5. 配送詳細表示
   └─ トラッキング番号、出荷番号、商品明細、配送・支払い情報を表示
```

### フローチャート

```mermaid
flowchart TD
    A[注文詳細画面] --> B{qtyShipped > 0?}
    B -->|Yes| C[配送詳細ボタン表示]
    B -->|No| D[配送詳細ボタン非表示]
    C --> E[配送詳細ボタン押下]
    E --> F[OrderShipmentsScreen遷移]
    F --> G[OrderShipmentsFetchDataEvent発行]
    G --> H[getShipmentsList API呼び出し]
    H --> I{レスポンス成功?}
    I -->|Yes| J[ShipmentModel生成]
    I -->|No| K[エラー表示]
    J --> L{データあり?}
    L -->|Yes| M[配送詳細表示]
    L -->|No| N[EmptyDataView表示]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-46-01 | 表示条件 | 出荷数量(qtyShipped)が0より大きい場合のみ表示 | 常時 |
| BR-46-02 | 自己注文のみ | ユーザーは自身の注文の配送情報のみ閲覧可能 | 常時 |
| BR-46-03 | 複数配送対応 | 1注文に複数の配送がある場合はすべて表示 | 常時 |

### 計算ロジック

配送詳細表示判定（注文詳細画面）：
```dart
if (orderDetailModel?.items?[0].qtyShipped != 0) {
  // 配送詳細ボタンを表示
}
```

## データベース操作仕様

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 配送取得 | shipments | SELECT | 注文IDに紐づく配送情報を取得 |
| 配送取得 | shipment_items | SELECT | 配送に含まれる商品明細を取得 |

### テーブル別操作詳細

#### shipments（GraphQL API経由）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, track_number, items等 | order_id = 指定されたorderId | 複数レコード可能 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | API通信エラー | ネットワーク接続不可 | エラー表示 |
| - | データなし | 配送情報がない | EmptyDataView表示 |

### リトライ仕様

- 自動リトライなし
- 画面再表示で再取得可能

## トランザクション仕様

本機能はデータ取得のみのため、トランザクション管理は不要。

## パフォーマンス要件

- データロード：2秒以内

## セキュリティ考慮事項

- 認証トークンを使用したAPI呼び出し
- 注文IDによるアクセス制御（サーバーサイドで所有者確認）

## 備考

- ShippingAndPaymentInfoウィジェットを再利用して配送・支払い情報を表示
- OrderDetailモデルを引数として渡し、関連情報を共有
- トラッキング番号は配送業者のWebサイトで追跡に使用可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | shipment_model.dart | `lib/data_model/order_model/shipment_model.dart` | ShipmentModel、ViewShipmentsの構造 |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | shipments_details.dart | `lib/screens/order_shipping/shipments_details.dart` | StatefulWidgetの構造、initStateでのBloc初期化 |

**主要処理フロー**:
- **18-22行目**: initStateでOrderShipmentsBlocを取得し、OrderShipmentsFetchDataEventを発行
- **39-54行目**: BlocConsumerでstateの変化を監視しUI更新
- **57-82行目**: shipmentsDetails()で配送情報を表示
- **106-149行目**: getShipments()でトラッキング番号と商品一覧を表示

#### Step 3: BLoCパターンを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | order_shipments_bloc.dart | `lib/screens/order_shipping/bloc/order_shipments_bloc.dart` | OrderShipmentsFetchDataEventのハンドリング |

**主要処理フロー**:
- **23-36行目**: OrderShipmentsFetchDataEvent処理、getShipmentsList呼び出し

#### Step 4: リポジトリ層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | order_shipments_repository.dart | `lib/screens/order_shipping/bloc/order_shipments_repository.dart` | getShipmentsListメソッド |

**主要処理フロー**:
- **21-30行目**: getShipmentsListでApiClient.getShipmentsList呼び出し

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

```
OrderShipmentsScreen (Widget)
    │
    ├─ OrderShipmentsBloc
    │      │
    │      └─ OrderShipmentsRepositoryImp
    │             │
    │             └─ ApiClient.getShipmentsList()
    │
    ├─ OrderShipmentsListDataState
    │      │
    │      └─ ShipmentModel
    │
    └─ ShippingAndPaymentInfo (Widget)
```

### データフロー図

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

orderId ───▶ OrderShipmentsFetchDataEvent ───▶ OrderShipmentsBloc
   │                                                │
   │                                                ▼
   │                                    OrderShipmentsRepository
   │                                                │
   │                                                ▼
   │                                      ApiClient (GraphQL)
   │                                                │
   │                                                ▼
   │                                        ShipmentModel
   │                                                │
   │                                                ▼
   └─────────────────────────────── OrderShipmentsListDataState ───▶ 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` | ソース | リポジトリ層 |
| shipment_model.dart | `lib/data_model/order_model/shipment_model.dart` | ソース | データモデル |
| shipping_payment_info.dart | `lib/screens/order_detail/widgets/shipping_payment_info.dart` | ソース | 配送・支払い情報UI |
