# 画面設計書 19-請求書詳細画面

## 概要

本ドキュメントは、Bagisto eコマースモバイルアプリにおける請求書詳細画面の設計仕様を定義するものです。請求書詳細画面は、注文に関連する請求書情報の詳細を表示する画面です。

### 本画面の処理概要

請求書詳細画面は、注文に対して発行された請求書の詳細情報（商品、価格、税金の明細）を表示する画面です。

**業務上の目的・背景**：請求書詳細画面は、ユーザーが注文に対する請求内容を確認するための画面です。商品ごとの価格、数量、税額、小計、総計などの詳細な金額情報を提供することで、ユーザーが購入内容を正確に把握できるようにします。経費精算や確定申告などで請求書情報が必要な場合にも活用できます。

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

**主要な操作・処理内容**：
1. 請求書情報の取得・表示
2. 請求書ID、商品明細の表示
3. 各商品のSKU、名前、価格、数量、小計、税額、合計の表示
4. 価格詳細（小計、配送料、税金、合計）の表示
5. 配送先・支払い情報の表示

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 45 | 請求書表示 | 主機能 | 注文の請求書情報表示（商品、価格、税金の明細） |

## 画面種別

詳細

## URL/ルーティング

```dart
const String invoiceDetails = "InvoiceDetails";
```

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

## 入出力項目

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

## 表示項目

| No | 項目名 | 型 | 表示条件 | 説明 |
|----|--------|-----|----------|------|
| 1 | AppBar | AppBar | 常時 | タイトル「請求書」 |
| 2 | 請求書ID | Text | 常時 | 「請求書 #ID」形式で表示 |
| 3 | 商品一覧 | ListView | 常時 | 請求書に含まれる商品リスト |
| 4 | SKU | Text | 常時 | 商品SKUコード |
| 5 | 商品名 | Text | 常時 | 商品名 |
| 6 | 単価 | Text | 常時 | 商品単価（フォーマット済み） |
| 7 | 数量 | Text | 常時 | 購入数量 |
| 8 | 小計 | Text | 常時 | 商品小計 |
| 9 | 税額 | Text | 常時 | 商品税額 |
| 10 | 合計 | Text | 常時 | 商品合計（税込） |
| 11 | 価格詳細 | Card | 常時 | 小計、配送料、税金、総合計 |
| 12 | 配送・支払い情報 | ShippingAndPaymentInfo | 常時 | 配送先、支払い方法 |
| 13 | ローディング | Loader | 読み込み中 | データ取得中の表示 |
| 14 | 空状態表示 | EmptyDataView | 請求書なし | 請求書がない場合の表示 |

## イベント仕様

### 1-請求書データ取得

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

**処理フロー**：
1. `OrderInvoiceBloc`に`OrderInvoiceFetchDataEvent(orderId)`を発行
2. `OrderInvoiceRepository.getInvoicesList(orderId)`でAPIを呼び出し
3. 取得したデータを`InvoicesModel`モデルに変換
4. `OrderInvoiceListDataState.success`を発行しUIを更新

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 請求書取得 | order_invoices, order_invoice_items | SELECT | 注文の請求書情報を取得 |

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

#### order_invoices

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | id, sub_total, shipping_amount, tax_amount, grand_total | order_idで絞り込み | 請求書情報取得 |

#### order_invoice_items

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

## メッセージ仕様

| No | メッセージID | メッセージ内容 | 表示タイミング | 種別 |
|----|------------|---------------|--------------|------|
| 1 | invoice | 請求書 | AppBarタイトル | 情報 |
| 2 | priceDetails | 価格詳細 | 価格セクションタイトル | 情報 |
| 3 | subTotal | 小計 | 価格詳細行 | 情報 |
| 4 | shippingHandling | 配送料 | 価格詳細行 | 情報 |
| 5 | tax | 税金 | 価格詳細行 | 情報 |
| 6 | grandTotal | 合計 | 価格詳細行 | 情報 |
| 7 | sku | SKU | 商品詳細ラベル | 情報 |
| 8 | name | 名前 | 商品詳細ラベル | 情報 |
| 9 | price | 価格 | 商品詳細ラベル | 情報 |
| 10 | qty | 数量 | 商品詳細ラベル | 情報 |
| 11 | taxAmount | 税額 | 商品詳細ラベル | 情報 |

## 例外処理

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

## 備考

- 請求書は注文に対して複数発行される可能性あり（分割請求など）
- 各請求書の商品明細を`ListView.separated`で表示
- 価格はすべて`formattedPrice`でフォーマット済み
- `ShippingAndPaymentInfo`コンポーネントで配送・支払い情報を共通表示
- `NeverScrollableScrollPhysics()`で内部ListViewのスクロールを無効化

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | invoices_model.dart | `lib/screens/order_invoices/data_model/invoices_model.dart`（推定） | InvoicesModel、ViewInvoices、Items構造 |

**読解のコツ**: `InvoicesModel`には`viewInvoices`（請求書リスト）が含まれ、各請求書には`items`（商品明細）と`formattedPrice`（価格情報）が含まれます。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | invoice_details.dart | `lib/screens/order_invoices/view/invoice_details.dart` | InvoiceScreenクラス |

**主要処理フロー**:
1. **行27-32**: initStateでBloc取得、`OrderInvoiceFetchDataEvent`発行
2. **行35-46**: buildメソッドでScaffold構築
3. **行48-61**: BlocConsumerで状態に応じたUI構築
4. **行64-122**: `invoiceDetails`で請求書詳細表示
5. **行166-230**: `getInvoices`で請求書リスト表示

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | order_invoice_bloc.dart | `lib/screens/order_invoices/bloc/order_invoice_bloc.dart` | 請求書取得処理 |
| 3-2 | order_invoice_event.dart | `lib/screens/order_invoices/bloc/order_invoice_event.dart` | イベント定義 |
| 3-3 | order_invoice_state.dart | `lib/screens/order_invoices/bloc/order_invoice_state.dart` | 状態定義 |

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

```
InvoiceScreen (invoice_details.dart)
    │
    ├─ OrderInvoiceBloc (order_invoice_bloc.dart)
    │      │
    │      └─ OrderInvoiceFetchDataEvent
    │             └─ OrderInvoiceRepository.getInvoicesList()
    │
    └─ invoiceDetails()
           ├─ getInvoices() - 請求書リスト
           │      └─ ListView.separated - 商品明細
           │
           ├─ getOrdersRow() - 価格詳細行
           │
           └─ ShippingAndPaymentInfo - 配送・支払い情報
```

### データフロー図

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

OrderDetailScreen ──────▶ InvoiceScreen
      │                        │
      │ orderDetailsModel      │
      └──────────▶ initState ──────────▶ OrderInvoiceBloc
                                              │
                                              └─ OrderInvoiceRepository
                                                       │
                                                       └─ InvoicesModel
                                                              │
                                                              └─ invoiceDetails() → UI表示
```

### 関連ファイル一覧

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