# 通知設計書 59-バーコードスキャン音

## 概要

本ドキュメントは、InvenTreeアプリにおける「バーコードスキャン音」の設計仕様を定義する。バーコードスキャン操作の結果（成功/失敗）に応じて、ユーザーに音声フィードバックを提供する。

### 本通知の処理概要

バーコードスキャン音は、バーコードスキャン操作の結果をユーザーに即座に伝えるための音声フィードバック機能である。視覚的なフィードバックを見逃しやすい倉庫作業などの環境で、聴覚によるフィードバックを提供することで作業効率を向上させる。

**業務上の目的・背景**：在庫管理の現場では、作業者は複数のアイテムを連続してスキャンすることが多い。その際、画面を毎回確認することは作業効率を低下させる。スキャン成功・失敗を音で知らせることで、作業者は画面を見なくても結果を把握でき、素早く次のアクションに移ることができる。特に騒音のある環境や、手元を見ながらの作業中に、音声フィードバックは重要な役割を果たす。

**通知の送信タイミング**：バーコードスキャンが完了し、結果が判明した時点で即座に再生される。成功時は `barcodeSuccessTone()` が呼び出され、失敗時は `barcodeFailureTone()` が呼び出される。

**通知の受信者**：現在バーコードスキャンを実行しているユーザー。音声はデバイスのスピーカーから再生される。

**通知内容の概要**：成功時は `barcode_scan.mp3`、失敗時は `barcode_error.mp3` という音声ファイルが再生される。音声ファイルはアプリのアセットとしてバンドルされている。

**期待されるアクション**：ユーザーは音声を聞いて、スキャン結果を認識する。成功音が聞こえれば次のアイテムのスキャンに進み、失敗音が聞こえればスキャンをやり直す。

## 通知種別

音声通知（Audio Notification）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（スキャン結果判明と同時に再生） |
| 優先度 | 中（音声フィードバック） |
| リトライ | 無（再生失敗時は静かに失敗） |

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

- 現在バーコードスキャンを実行しているユーザー
- 条件：`INV_SOUNDS_BARCODE` 設定が `true` の場合にのみ再生

## 通知テンプレート

### 音声ファイル構成

| 結果 | ファイルパス | 説明 |
|-----|------------|------|
| 成功 | `assets/sounds/barcode_scan.mp3` | スキャン成功時の音声 |
| 失敗 | `assets/sounds/barcode_error.mp3` | スキャン失敗時の音声 |

### 再生設定

| 項目 | 設定値 | 説明 |
|-----|-------|------|
| AudioContext | AndroidUsageType.notification | Android通知音として再生 |
| AudioFocus | AndroidAudioFocus.none | 他の音声を中断しない |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| INV_SOUNDS_BARCODE | バーコード音設定 | InvenTreeSettingsManager | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| バーコード処理完了 | スキャン成功 | INV_SOUNDS_BARCODE == true | barcodeSuccessTone()が呼び出される |
| バーコード処理完了 | スキャン失敗 | INV_SOUNDS_BARCODE == true | barcodeFailureTone()が呼び出される |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| INV_SOUNDS_BARCODE == false | バーコード音設定がオフの場合 |
| hasContext() == false | アプリコンテキストが利用できない場合（テスト環境等） |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[バーコードスキャン完了] --> B{スキャン結果}
    B -->|成功| C[barcodeSuccessTone呼び出し]
    B -->|失敗| D[barcodeFailureTone呼び出し]
    C --> E[INV_SOUNDS_BARCODE設定確認]
    D --> E
    E -->|有効| F[hasContext確認]
    E -->|無効| G[終了]
    F -->|true| H[AudioPlayer生成]
    F -->|false| G
    H --> I[AudioContext設定]
    I --> J[playAudioFile実行]
    J --> K[音声再生]
    K --> G
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| Settings（ローカルDB） | バーコード音設定の確認 | Sembast NoSQLデータベース |

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

#### Settings

| 参照項目（キー） | 用途 | デフォルト値 |
|----------------|------|------------|
| INV_SOUNDS_BARCODE | バーコード音の有効/無効 | true |

### 更新テーブル一覧

なし（読み取り専用）

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 音声ファイル欠損 | アセットファイルが存在しない場合 | エラーは暗黙的に処理される |
| 再生失敗 | オーディオプレーヤーエラー | エラーは暗黙的に処理される |
| コンテキスト不足 | hasContext() == false | 再生をスキップ |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0回（再生失敗時はスキップ） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

## 配信設定

### レート制限

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

### 配信時間帯

制限なし（スキャン操作時に即座に再生）

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

- 音声再生はローカルのみで完結
- 個人情報は含まれない
- 周囲への音漏れに配慮が必要（業務環境による）

## 備考

- 設定画面でバーコード音のオン/オフを切り替え可能
- AudioPlayerライブラリ（audioplayers）を使用
- Androidでは通知音として分類（他のメディア再生に影響しない）
- テスト環境ではdebug()によるログ出力のみ

---

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

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

### 推奨読解順序

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

音声設定の定義と、使用される音声ファイルを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | preferences.dart | `lib/preferences.dart` | INV_SOUNDS_BARCODE定数の定義 |
| 1-2 | assets/sounds/ | `assets/sounds/*.mp3` | 音声ファイルの存在確認 |

**読解のコツ**: INV_SOUNDS_BARCODEのデフォルト値がtrueであることを確認しておくと良い。

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

音声再生のトリガーとなる関数を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | tones.dart | `lib/barcode/tones.dart` | barcodeSuccessTone()、barcodeFailureTone()関数 |

**主要処理フロー**:
1. **7-15行目**: barcodeSuccessTone() - 成功音の再生
2. **17-25行目**: barcodeFailureTone() - 失敗音の再生

#### Step 3: 音声再生処理を理解する

実際の音声再生ロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | helpers.dart | `lib/helpers.dart` | playAudioFile()関数（92-115行目）の実装詳細 |

**主要処理フロー**:
- **92-98行目**: デバッグ出力とhasContext()チェック
- **100-114行目**: AudioPlayer生成とAudioContext設定、再生実行

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

```
バーコードスキャン処理
    |
    +-- スキャン結果判定
    |       |
    |       +-- [成功] barcodeSuccessTone() [tones.dart:7-15行目]
    |       |           |
    |       |           +-- INV_SOUNDS_BARCODE設定確認
    |       |           |
    |       |           +-- playAudioFile("sounds/barcode_scan.mp3")
    |       |                   |
    |       |                   +-- [helpers.dart:92-115行目]
    |       |                           |
    |       |                           +-- debug()
    |       |                           |
    |       |                           +-- hasContext()チェック
    |       |                           |
    |       |                           +-- AudioPlayer()生成
    |       |                           |
    |       |                           +-- setAudioContext()
    |       |                           |
    |       |                           +-- play(AssetSource)
    |       |
    |       +-- [失敗] barcodeFailureTone() [tones.dart:17-25行目]
    |                   |
    |                   +-- （同様の処理フロー）
```

### データフロー図

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

バーコードスキャン結果 ──> tone関数呼び出し ──────────> 設定チェック
(成功/失敗)                                                    |
                                                              v
                                                   INV_SOUNDS_BARCODE確認
                                                              |
                              +------------------+------------+
                              |                  |
                              v                  v
                          [有効]             [無効]
                              |                  |
                              v                  v
                      hasContext()確認      処理終了
                              |
                              v
                      AudioPlayer生成
                              |
                              v
                      音声ファイル再生
                              |
                              v
                      デバイススピーカー出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| tones.dart | `lib/barcode/tones.dart` | ソース | barcodeSuccessTone/barcodeFailureTone関数 |
| helpers.dart | `lib/helpers.dart` | ソース | playAudioFile関数の実装 |
| preferences.dart | `lib/preferences.dart` | ソース | INV_SOUNDS_BARCODE定数、InvenTreeSettingsManager |
| barcode_scan.mp3 | `assets/sounds/barcode_scan.mp3` | アセット | 成功音の音声ファイル |
| barcode_error.mp3 | `assets/sounds/barcode_error.mp3` | アセット | 失敗音の音声ファイル |
| handler.dart | `lib/barcode/handler.dart` | ソース | バーコードハンドラー（音声関数の呼び出し元） |
