# 通知設計書 33-リクエスト成功

## 概要

本ドキュメントは、InvenTreeモバイルアプリケーションにおける「リクエスト成功」通知の設計仕様を定義するものです。この通知は、APIリクエストが正常に完了した際にユーザーに表示されるスナックバー通知です。

### 本通知の処理概要

この通知は、サーバーへの各種APIリクエスト（ロケート操作など）が正常に完了した場合にユーザーにフィードバックを提供する機能です。

**業務上の目的・背景**：ユーザーがサーバーに対して操作を実行する際、その操作が成功したことを明確に伝える必要があります。この通知により、ユーザーは要求した操作が正常に処理されたことを即座に確認でき、操作の確実性を担保します。特にロケート機能など、物理的なアクションを伴う操作の成功確認に重要です。

**通知の送信タイミング**：`locateItemOrLocation()` メソッドなどで、APIへのPOSTリクエストが成功（HTTP 200）した直後に通知が発生します。これは、アイテムやロケーションの特定操作後に発生します。

**通知の受信者**：通知は、アプリで操作を実行している現在のユーザーに対してのみ表示されます。

**通知内容の概要**：国際化対応されたメッセージ「Request successful」（または相当するローカライズ文字列）がスナックバーとして画面下部に表示されます。成功を示すライトグリーンの背景とチェックアイコンが付加されます。

**期待されるアクション**：ユーザーは操作が成功したことを確認し、次の作業に移ることが期待されます。

## 通知種別

アプリ内通知（スナックバー）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 中 |
| リトライ | なし |

### 送信先決定ロジック

アプリの現在アクティブなユーザーに対してのみ表示されます。ユーザーロールや権限による制限はありません。

## 通知テンプレート

### スナックバー通知の場合

| 項目 | 内容 |
|-----|------|
| 背景色 | ライトグリーン（Colors.lightGreen） |
| アイコン | TablerIcons.circle_check |
| 表示時間 | 5秒 |
| 閉じるボタン | あり |

### 本文テンプレート

```
{L10().requestSuccessful}
```

実際の表示例（英語）：
```
Request successful
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| requestSuccessful | リクエスト成功メッセージ | L10()国際化リソース | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| API応答 | locateItemOrLocation() | response.successful() | ロケート操作の成功時 |
| API応答 | 各種POSTリクエスト | HTTP 200 | 各種操作の成功時 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| APIエラー | サーバーエラー時は別のエラー通知が表示される |
| 非成功レスポンス | 200以外のステータスコードの場合は通知しない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[ロケート操作開始] --> B[プラグイン選択]
    B --> C[APIリクエスト送信]
    C --> D{レスポンス確認}
    D -->|successful| E[showSnackIcon呼び出し]
    D -->|失敗| F[エラー処理]
    E --> G[スナックバー表示]
    G --> H[5秒後自動非表示]
```

## データベース参照・更新仕様

### 参照テーブル一覧

該当なし（クライアントサイドのみの処理）

### 更新テーブル一覧

該当なし（サーバー側でプラグイン処理が実行される）

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| コンテキスト不在 | Flutterコンテキストが無効な場合 | 通知をスキップ |
| プラグイン未設定 | ロケートプラグインが無い場合 | 処理を中断 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし |
| 1日あたり上限 | 制限なし |

### 配信時間帯

制限なし（24時間対応）

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

- 操作対象の詳細情報は通知メッセージに含まれない
- 認証済みユーザーのみがアプリを使用可能
- プラグイン選択はサーバー側で制御される

## 備考

- この通知は主にlocateItemOrLocation()で使用されるが、他の成功通知にも適用可能
- 国際化対応により、アプリの言語設定に応じたメッセージが表示される

---

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

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

### 推奨読解順序

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

まず、APIレスポンスの successful() メソッドを理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | api.dart | `lib/api.dart` | APIResponseクラスのsuccessful()メソッド（行59） |

**読解のコツ**: successful()はステータスコード200-299を成功と判定する

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

locateItemOrLocation()メソッドでの成功時処理を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | api.dart | `lib/api.dart` | locateItemOrLocation()メソッド（行1660-1726） |

**主要処理フロー**:
1. **行1660-1665**: メソッド定義とパラメータ
2. **行1666-1707**: プラグイン選択処理
3. **行1709-1718**: ボディ構築
4. **行1719-1725**: POSTリクエストと成功時のshowSnackIcon呼び出し
5. **行1722-1724**: `if (response.successful()) { showSnackIcon(L10().requestSuccessful, success: true); }`

#### Step 3: スナックバー表示ロジックを理解する

showSnackIcon関数の実装を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | snacks.dart | `lib/widget/snacks.dart` | showSnackIcon関数（行11-81） |

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

```
locateItemOrLocation()  [lib/api.dart:1660]
    │
    ├─ getPlugins(mixin: "locate")  [行1666]
    │      └─ プラグイン一覧取得
    │
    ├─ launchApiForm()  [行1697] (複数プラグインの場合)
    │      └─ プラグイン選択ダイアログ
    │
    ├─ post("/api/locate/", ...)  [行1719]
    │      └─ HTTP POSTリクエスト
    │
    └─ showSnackIcon()  [行1723]
           └─ L10().requestSuccessful
```

### データフロー図

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

アイテム/ロケーション ───▶  locateItemOrLocation()     ───▶  スナックバー表示
ID                          ├─ プラグイン選択                  │
                            ├─ API POSTリクエスト              └─ 「Request successful」
                            └─ レスポンス判定                     メッセージ
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| api.dart | `lib/api.dart` | ソース | InvenTreeAPIクラス、locateItemOrLocation()メソッド |
| snacks.dart | `lib/widget/snacks.dart` | ソース | showSnackIcon関数の実装 |
| l10.dart | `lib/l10.dart` | ソース | 国際化ヘルパー関数L10() |
| api_form.dart | `lib/api_form.dart` | ソース | launchApiForm()関数（プラグイン選択ダイアログ） |
