# 機能設計書 33-比較リストに追加

## 概要

本ドキュメントは、商品を比較リストに追加する機能の設計を記述する。

### 本機能の処理概要

本機能は、ユーザーが商品一覧画面やホーム画面から、比較したい商品を比較リストに追加するための機能である。

**業務上の目的・背景**：ECサイトにおいて、ユーザーは複数の商品を比較検討してから購入決定を行うことが多い。本機能により、気になる商品を比較リストに保存し、後から一括で比較できるようになる。これにより、ユーザーの購入意思決定プロセスを支援し、購入満足度の向上に寄与する。

**機能の利用シーン**：ユーザーがホーム画面の商品カードや、カテゴリ商品一覧画面で「比較」アイコンをタップした際に本機能が実行される。また、商品詳細画面からも比較リストへの追加が可能。

**主要な処理内容**：
1. 商品カードの比較アイコンタップを検知
2. GraphQL APIで比較リストへの追加リクエストを送信
3. 追加成功時に成功通知を表示
4. 失敗時にエラー通知を表示

**関連システム・外部連携**：GraphQL APIを介したBagistoバックエンドとの通信

**権限による制御**：ログインユーザー、ゲストユーザー共に利用可能（ゲストはセッションベースで管理）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | ホーム画面 | 参照画面 | ホーム画面から商品を比較リストに追加 |
| 7 | 商品詳細画面 | 参照画面 | 商品を比較リストに追加 |
| 8 | カテゴリ商品一覧画面 | 参照画面 | 一覧から商品を比較リストに追加 |

## 機能種別

データ登録処理（CREATE操作）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| productId | String | Yes | 商品ID | 有効な商品IDであること |

### 入力データソース

- 商品カードUIからの商品ID取得
- 商品詳細画面からの商品ID取得

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| success | bool | 処理成功フラグ |
| message | String | 結果メッセージ |

### 出力先

- 画面表示: 成功/失敗通知トースト
- 比較リスト: 商品が追加される

## 処理フロー

### 処理シーケンス

```
1. ユーザーが比較アイコンをタップ
   └─ 商品カードのonTap実行
2. AddToCompareEventを発火
   └─ HomePageBloc.add実行
3. BlocがAPIを呼び出し
   └─ HomePageRepository.callAddToCompareListApi実行
4. ApiClient.addToCompareでGraphQL通信
   └─ addToCompare mutationを実行
5. レスポンス処理
   └─ 成功: 成功通知表示
   └─ 失敗: エラー通知表示
```

### フローチャート

```mermaid
flowchart TD
    A[比較アイコンタップ] --> B[AddToCompareEvent発火]
    B --> C[GraphQL API呼び出し]
    C --> D{API結果}
    D -->|成功| E[成功通知表示]
    D -->|失敗| F[エラー通知表示]
    E --> G[比較リストに商品追加完了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-33-01 | 重複チェック | 既に比較リストにある商品は再追加不可 | 追加処理時 |
| BR-33-02 | 最大件数 | 比較リストの最大件数はバックエンドで制御 | 追加処理時 |

### 計算ロジック

特になし。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 比較追加 | compare_items | INSERT | 比較リストに商品追加 |

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

#### compare_items

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | customer_id, product_id | ユーザーID、商品ID | バックエンドで処理 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | graphqlErrors | API通信失敗 | エラー通知表示 |
| - | 重複エラー | 既に追加済み | 通知メッセージ表示 |

### リトライ仕様

自動リトライなし。

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

バックエンドAPIでトランザクション管理。

## パフォーマンス要件

- API応答時間: 2秒以内
- ボタン連打防止: ローディング中は再タップ無効

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

- セッションまたは認証トークンによるユーザー識別
- 有効な商品IDのみ追加可能

## 備考

- 比較画面への遷移は別途ナビゲーションで行う

---

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

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

### 推奨読解順序

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

APIレスポンスのモデル構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | base_model.dart | `lib/data_model/base_model.dart` | BaseModelクラスの構造（success, message） |

**読解のコツ**: 比較追加APIはシンプルなBaseModel応答を返す。

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

比較追加を呼び出すUI部分を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | home_page_repository.dart | `lib/screens/home_page/bloc/home_page_repository.dart` | callAddToCompareListApiメソッド |

**主要処理フロー**:
- **85-95行目**: addToCompare API呼び出し

#### Step 3: APIクライアントを理解する

GraphQL通信の実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | api_client.dart | `lib/services/api_client.dart` | addToCompareメソッド |

**主要処理フロー**:
- **367-382行目**: addToCompare mutation実行

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

```
ProductCard / HomePageWidget (UI)
    │
    ├─ HomePageBloc.add(AddToCompareEvent)
    │      │
    │      └─ HomePageRepository.callAddToCompareListApi(productId)
    │             │
    │             └─ ApiClient.addToCompare(productId)
    │                    │
    │                    └─ GraphQL mutation: addToCompare
    │
    └─ 通知表示
           ├─ 成功: 成功メッセージ
           └─ 失敗: エラーメッセージ
```

### データフロー図

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

商品ID ─────────────▶ HomePageBloc ───────────▶ 成功通知
                          │
                    HomePageRepository
                          │
                    ApiClient
                          │
                    GraphQL Server ───────────▶ 比較リスト更新
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| home_page_repository.dart | `lib/screens/home_page/bloc/home_page_repository.dart` | ソース | リポジトリ層 |
| api_client.dart | `lib/services/api_client.dart` | ソース | API通信クライアント |
| mutation_query.dart | `lib/services/mutation_query.dart` | ソース | GraphQLクエリ定義 |
| base_model.dart | `lib/data_model/base_model.dart` | ソース | 基本レスポンスモデル |
