# 機能設計書 28-ウィッシュリストに追加

## 概要

本ドキュメントは、ECモバイルアプリにおける商品をウィッシュリストに追加する機能について設計仕様を定義する。

### 本機能の処理概要

本機能は、ユーザーが気になる商品をウィッシュリスト（お気に入り）に追加し、後で購入検討できるように保存する機能である。

**業務上の目的・背景**：ECサイトにおいて、ユーザーが購入を即座に決定できない場合でも、気になる商品を保存しておく機能は重要である。ウィッシュリスト機能により、ユーザーは複数の商品を比較検討し、後日購入を決定する際の参考にできる。また、価格変動の監視やセール通知の対象としても活用可能。

**機能の利用シーン**：ユーザーが商品一覧や商品詳細画面で気になる商品を見つけた際に利用される。すぐに購入しないが後で検討したい商品、比較検討中の商品、ギフトとして検討中の商品などを保存する場合に活用される。

**主要な処理内容**：
1. 商品一覧画面やホーム画面でお気に入りアイコンをタップ
2. ログイン状態を確認（ログイン必須）
3. AddItemToWishlistEventを発行し、GraphQL API経由でサーバーに送信
4. サーバーでウィッシュリストに商品を追加
5. 成功時は成功メッセージを表示
6. UIのお気に入りアイコン状態を更新

**関連システム・外部連携**：Bagisto GraphQL APIとの連携により、`addToWishlist` mutationを使用して商品をウィッシュリストに追加する。

**権限による制御**：ログインユーザーのみ利用可能。ウィッシュリストはユーザーアカウントに紐づくため、認証が必須となる。

## 関連画面

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

## 機能種別

CRUD操作（Create）/ 認証必須

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| productId | String | Yes | 追加する商品ID | 数値文字列であること |

### 入力データソース

画面操作（お気に入りアイコン/ハートアイコン押下）

## 出力仕様

### 出力データ

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

### 出力先

- 画面表示（成功/エラーメッセージ）
- UIアイコン状態更新（お気に入り済みを示すアイコン変更）

## 処理フロー

### 処理シーケンス

```
1. ユーザーがお気に入りアイコンをタップ
   └─ 各画面のお気に入りボタン処理
2. ログイン状態をチェック
   └─ appStoragePref.getCustomerLoggedIn()
3. ログイン済みの場合、AddItemToWishlistEventを発行
   └─ 商品IDをパラメータとして渡す
4. HomePageBlocがイベントを受信
   └─ repository.addItemToWishlistを呼び出し
5. HomePageRepositoryがApiClientを経由でAPI呼び出し
   └─ GraphQL mutation addToWishlistを実行
6. サーバーでウィッシュリストに商品を追加
7. 成功時: AddToWishlistState.successを発行
8. 成功メッセージを表示
```

### フローチャート

```mermaid
flowchart TD
    A[お気に入りアイコンタップ] --> B{ログイン済み?}
    B -->|No| C[ログイン画面へ誘導]
    B -->|Yes| D[AddItemToWishlistEvent発行]
    D --> E[HomePageBloc処理]
    E --> F[API呼び出し]
    F --> G{成功?}
    G -->|Yes| H[AddToWishlistState.success]
    H --> I[成功メッセージ表示]
    I --> J[アイコン状態更新]
    G -->|No| K[AddToWishlistState.fail]
    K --> L[エラーメッセージ表示]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-028-01 | ログイン必須 | ウィッシュリストへの追加はログインユーザーのみ可能 | アイコンタップ時 |
| BR-028-02 | 重複防止 | 既にウィッシュリストにある商品を再度追加した場合の処理はサーバー側で制御 | API呼び出し時 |
| BR-028-03 | 複数画面対応 | ホーム画面、商品詳細、一覧画面など複数画面から追加可能 | 各画面 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ウィッシュリスト追加 | wishlists | INSERT | 商品をウィッシュリストに追加 |

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

#### wishlists

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | customer_id, product_id | ログインユーザーID、指定商品ID | 新規レコード作成 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 未ログイン | ログインしていない状態で操作 | ログイン画面へ誘導 |
| - | ネットワークエラー | API通信失敗 | エラーメッセージを表示 |
| - | 商品未存在 | 存在しない商品IDを指定 | エラーメッセージを表示 |

### リトライ仕様

自動リトライは行わない。ユーザーに再操作を促す。

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

サーバー側でトランザクション管理。

## パフォーマンス要件

- API応答時間: 2秒以内を目標
- UI応答: アイコン押下は即座に反応

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

- 認証: ログインユーザーのみ利用可能
- データアクセス: 自身のウィッシュリストにのみ追加可能

## 備考

本機能はホームページリポジトリ（HomePageRepository）に実装されており、複数の画面から呼び出される共通機能として設計されている。

---

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

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

### 推奨読解順序

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

API応答のデータモデルを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | add_wishlist_model.dart | `lib/data_model/add_to_wishlist_model/add_wishlist_model.dart` | AddWishListModelクラス |

**読解のコツ**: AddWishListModelはBaseModelを継承し、success/messageを含む。

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

お気に入り追加操作の呼び出し箇所を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | home_page_repository.dart | `lib/screens/home_page/bloc/home_page_repository.dart` | addItemToWishlistメソッド（59-69行目） |

**主要処理フロー**:
1. **59-69行目**: addItemToWishlistメソッドでApiClient.addToWishlistを呼び出し

#### Step 3: API層を理解する

実際のAPI呼び出し処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | api_client.dart | `lib/services/api_client.dart` | addToWishlist API呼び出し（336-350行目） |
| 3-2 | mutation_query.dart | `lib/services/mutation_query.dart` | GraphQL mutation定義（188-199行目） |

**主要処理フロー**:
- **336-350行目**: addToWishlistメソッドでGraphQL mutationを実行

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

```
各画面 (home_page, product_screen, categories_screen等)
    │
    └─ お気に入りアイコンタップ
           │
           └─ ログインチェック
                  │
                  └─ (ログイン済み) → AddItemToWishlistEvent発行
                         │
                         └─ HomePageBloc/ProductPageBloc等
                                │
                                └─ Repository.addItemToWishlist
                                       │
                                       └─ ApiClient.addToWishlist
                                              │
                                              └─ MutationQuery.addToWishlist
```

### データフロー図

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

お気に入りタップ ───▶ ログインチェック ───▶ AddItemToWishlistEvent
     (UI)              (認証確認)           (イベント発行)
                                                  │
                        ┌─────────────────────────┘
                        ▼
                 Bloc (各画面)
                        │
                        ▼
                  Repository
                        │
                        ▼
                   ApiClient
                        │
                        ▼
            GraphQL API (addToWishlist)
                        │
                        ▼
            AddWishListModel ───▶ State ───▶ UI更新
               (応答)           (通知)    (メッセージ/アイコン)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| home_page_repository.dart | `lib/screens/home_page/bloc/home_page_repository.dart` | ソース | ホームページリポジトリ（共通機能） |
| add_wishlist_model.dart | `lib/data_model/add_to_wishlist_model/add_wishlist_model.dart` | ソース | ウィッシュリスト追加応答モデル |
| api_client.dart | `lib/services/api_client.dart` | ソース | API通信クライアント |
| mutation_query.dart | `lib/services/mutation_query.dart` | ソース | GraphQLクエリ定義 |
