# 通知設計書 13-在庫アイテム更新

## 概要

本ドキュメントは、InvenTreeモバイルアプリにおける「在庫アイテム更新」通知の設計仕様を定義する。この通知は、在庫アイテムの情報が正常に更新された際に表示される成功通知である。

### 本通知の処理概要

この通知は、在庫アイテムの数量変更、ロケーション移動、その他の属性更新が成功した際のフィードバックとして機能する。

**業務上の目的・背景**：在庫管理において、在庫アイテムの情報更新は日常的に発生する重要な操作である。数量の追加・削減、棚卸し（カウント）、ロケーション間の移動など、様々な更新操作が存在する。この通知により、ユーザーは更新操作が正常に完了したことを即座に確認でき、データの整合性が保たれていることを把握できる。

**通知の送信タイミング**：以下のいずれかの操作が成功した時点で通知が生成される：
- 在庫アイテムの編集（editForm成功時）
- 在庫の追加（addStock API成功時）
- 在庫の削減（removeStock API成功時）
- 棚卸し（countStock API成功時）
- ロケーション間移動（transferStock API成功時）
- バーコードスキャンによるロケーション移動成功時

**通知の受信者**：在庫更新操作を実行した現在のアプリユーザー。通知はアプリ内スナックバーとして即座に表示される。

**通知内容の概要**：「Stock item updated」というメッセージが表示され、在庫アイテムの更新が成功したことをユーザーに伝える。

**期待されるアクション**：ユーザーは更新が完了したことを確認し、次の在庫管理作業に進む。画面は自動的にリフレッシュされ、最新の情報が表示される。

## 通知種別

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

## 送信仕様

### 基本情報

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

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

現在の操作を実行しているアプリユーザーに対して即座に表示される。サーバーへの通知送信は行わず、クライアントサイドのみで処理される。

## 通知テンプレート

### スナックバー通知

| 項目 | 内容 |
|-----|------|
| 表示位置 | 画面下部 |
| 背景色 | lightGreen（成功時） |
| アイコン | circle_check |
| 表示時間 | 5秒 |

### 本文テンプレート

```
Stock item updated
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| なし | 固定メッセージ | L10().stockItemUpdated | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 画面操作 | 在庫アイテム編集完了 | editForm onSuccess | 在庫アイテム詳細画面での編集成功時 |
| 画面操作 | 在庫追加完了 | addStock API POST成功 | 在庫追加ダイアログでの操作成功時 |
| 画面操作 | 在庫削減完了 | removeStock API POST成功 | 在庫削減ダイアログでの操作成功時 |
| 画面操作 | 棚卸し完了 | countStock API POST成功 | 棚卸しダイアログでの操作成功時 |
| 画面操作 | 在庫移動完了 | transferStock API POST成功 | 在庫移動ダイアログでの操作成功時 |
| バーコード操作 | スキャン移動成功 | transferStock成功 | バーコードスキャンによるロケーション移動成功時 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| API失敗時 | 更新操作が失敗した場合は通知なし（エラー通知は別途処理） |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[在庫更新操作開始] --> B{操作種別}
    B -->|編集| C[editForm実行]
    B -->|追加| D[addStock API呼び出し]
    B -->|削減| E[removeStock API呼び出し]
    B -->|棚卸し| F[countStock API呼び出し]
    B -->|移動| G[transferStock API呼び出し]
    C --> H{API結果}
    D --> H
    E --> H
    F --> H
    G --> H
    H -->|成功| I[_stockUpdateMessage true 呼び出し]
    H -->|失敗| J[エラー処理]
    I --> K[showSnackIcon success=true]
    K --> L[スナックバー表示]
    L --> M[refresh context 画面更新]
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| なし（クライアント側のみ） | - | サーバー側で在庫データが更新される |

### テーブル別参照項目詳細

クライアントアプリ側では直接データベースを参照しない。サーバーAPI経由で在庫データの更新が行われる。

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| サーバー側StockItemテーブル | UPDATE | 在庫アイテムの数量・属性が更新される |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| なし | 成功通知のため該当なし | - |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0回（成功通知のため不要） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

## 配信設定

### レート制限

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

### 配信時間帯

24時間365日（アプリ使用時のみ）

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

- 通知内容には具体的な在庫情報は含まれず、単純な成功メッセージのみ
- 在庫更新操作自体はサーバー側で適切な権限チェックが行われる

## 備考

- 国際化対応済み（L10()による多言語サポート）
- 成功後、refresh(context)により画面が自動更新され、最新の在庫状態が反映される
- この通知は複数の更新操作（編集・追加・削減・棚卸し・移動）で共通して使用される

---

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

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

### 推奨読解順序

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

在庫アイテム更新通知に関連するデータ構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | app_en.arb | `lib/l10n/app_en.arb` | stockItemUpdated の定義（1533行目） |
| 1-2 | stock.dart | `lib/inventree/stock.dart` | InvenTreeStockItem クラスの構造 |

**読解のコツ**: stockItemUpdatedメッセージは複数の更新操作で共有されることを念頭に置く。

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

在庫更新操作の起点となる画面を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | stock_detail.dart | `lib/widget/stock/stock_detail.dart` | _StockItemDisplayState クラス（41行目以降） |

**主要処理フロー**:
1. **359行目**: _editStockItem - 在庫アイテム編集
2. **367-391行目**: _addStockDialog - 在庫追加ダイアログ
3. **402-426行目**: _removeStockDialog - 在庫削減ダイアログ
4. **428-456行目**: _countStockDialog - 棚卸しダイアログ
5. **461-476行目**: _transferStockDialog - 在庫移動ダイアログ

#### Step 3: 通知表示層を理解する

成功通知の表示メカニズムを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | stock_detail.dart | `lib/widget/stock/stock_detail.dart` | _stockUpdateMessage関数（393-397行目） |

**主要処理フロー**:
- **393-397行目**: _stockUpdateMessage - 更新成功時のスナックバー表示
- **395行目**: showSnackIcon(L10().stockItemUpdated, success: true)

#### Step 4: バーコードスキャンによる更新

バーコードスキャン経由での在庫更新を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | stock.dart | `lib/barcode/stock.dart` | StockItemScanIntoLocationHandler（111-157行目） |
| 4-2 | stock.dart | `lib/barcode/stock.dart` | StockLocationScanInItemsHandler（166-227行目） |

**主要処理フロー**:
- **139行目**: showSnackIcon(L10().stockItemUpdated, success: true)
- **206行目**: showSnackIcon(L10().stockItemUpdated, success: true)

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

```
_StockItemDisplayState (stock_detail.dart:41)
    │
    ├─ _editStockItem (stock_detail.dart:340)
    │      └─ editForm onSuccess
    │             └─ showSnackIcon(stockItemUpdated)
    │
    ├─ _addStockDialog (stock_detail.dart:367)
    │      └─ launchApiForm onSuccess
    │             └─ _stockUpdateMessage(true)
    │                    └─ showSnackIcon(stockItemUpdated)
    │
    ├─ _removeStockDialog (stock_detail.dart:402)
    │      └─ launchApiForm onSuccess
    │             └─ _stockUpdateMessage(true)
    │
    ├─ _countStockDialog (stock_detail.dart:428)
    │      └─ launchApiForm onSuccess
    │             └─ _stockUpdateMessage(true)
    │
    └─ _transferStockDialog (stock_detail.dart:461)
           └─ launchApiForm onSuccess
                  └─ _stockUpdateMessage(true)

StockItemScanIntoLocationHandler (stock.dart:111)
    └─ onLocationScanned
           └─ showSnackIcon(stockItemUpdated)

StockLocationScanInItemsHandler (stock.dart:166)
    └─ onItemScanned
           └─ showSnackIcon(stockItemUpdated)
```

### データフロー図

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

ユーザー操作        ───▶ 在庫更新API呼び出し    ───▶ サーバー
（編集/追加/削減/         │                          │
 棚卸し/移動）            │                          ▼
                          │                      成功応答
                          │                          │
                          ▼                          ▼
                     onSuccess               _stockUpdateMessage(true)
                     コールバック                    │
                          │                          ▼
                          └──────────────────▶ showSnackIcon
                                               "Stock item updated"
                                               (緑色背景)
                                                     │
                                                     ▼
                                               refresh(context)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| stock_detail.dart | `lib/widget/stock/stock_detail.dart` | ソース | 在庫アイテム詳細画面・更新操作 |
| stock.dart | `lib/barcode/stock.dart` | ソース | バーコードスキャンによる在庫操作 |
| stock.dart | `lib/inventree/stock.dart` | ソース | 在庫アイテムモデル定義 |
| snacks.dart | `lib/widget/snacks.dart` | ソース | スナックバー表示ユーティリティ |
| app_en.arb | `lib/l10n/app_en.arb` | リソース | 英語ローカライゼーション |
| api_form.dart | `lib/api_form.dart` | ソース | APIフォーム処理 |
