# 通知設計書 38-ルール適用エラー

## 概要

本ドキュメントは、Actual Budget アプリケーションにおける「ルール適用エラー」通知の設計仕様を記述する。この通知は、取引ルールの適用処理中に何らかのエラーが発生した場合に表示される。

### 本通知の処理概要

**業務上の目的・背景**：Actual Budget では、取引にルールを適用して自動的にカテゴリ分類や支払先設定などを行う機能がある。ルールの適用処理中にエラーが発生した場合（例：無効なルール設定、データ整合性エラーなど）、ユーザーにエラーを通知し、ルールの確認・修正を促す必要がある。

**通知の送信タイミング**：ルール削除操作において、スケジュールにリンクされているルールを削除しようとした場合など、ルール操作に関連するエラーが発生した際に表示される。

**通知の受信者**：ルール操作を実行したユーザー。

**通知内容の概要**：エラーの内容を示すメッセージが表示される。エラーの種類に応じて、警告（warning）またはエラー（error）タイプで表示される。

**期待されるアクション**：ユーザーはエラー内容を確認し、ルールの設定を確認・修正するか、関連するスケジュールとのリンクを解除してから再度操作を行う。

## 通知種別

アプリ内通知（トースト通知 - 警告/エラータイプ）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（操作結果受信時） |
| 優先度 | 高 |
| リトライ | 無 |

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

- ルール削除でスケジュールリンクエラーの場合は warning タイプ
- その他のルール操作エラーの場合は error タイプ
- 操作を実行したユーザーのローカル画面に表示

## 通知テンプレート

### アプリ内通知の場合

| 項目 | 内容 |
|-----|------|
| 通知タイプ | `warning` または `error` |
| 表示位置 | 画面右下（固定位置） |
| タイムアウト | デフォルト（6500ms） |

### 本文テンプレート

スケジュールリンクエラー時（warning）:
```
Message: This rule could not be deleted because it is linked to a schedule.
```

その他のエラー時（error）:
```
Message: Failed to delete rule. Please try again.
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| type | 通知タイプ | エラー種別に応じて `warning` または `error` | Yes |
| message | エラーメッセージ | エラー種別に応じた固定メッセージ（i18n対応） | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 画面操作 | ルール削除 | スケジュールにリンクされている場合 | MobileRulesPage.tsx で検知 |
| 画面操作 | ルール削除 | その他の削除エラー | MobileRulesPage.tsx の catch ブロック |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| なし | エラー発生時は常に通知を表示 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[ルール削除操作] --> B[rule-delete-all API 呼び出し]
    B --> C{結果確認}
    C -->|someDeletionsFailed: true| D[warning 通知を表示]
    C -->|例外発生| E[error 通知を表示]
    C -->|成功| F[Undo 通知を表示]
    D --> G[ルール一覧を再読み込み]
    E --> G
    F --> G
    G --> H[終了]
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| rules | ルール情報 | 削除対象の確認 |
| schedules | スケジュール情報 | ルールとのリンク確認 |

### 削除処理

サーバー側でルール削除時、`schedules` テーブルでリンクを確認し、リンクがある場合は削除を拒否して `false` を返す。

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| スケジュールリンク | ルールがスケジュールにリンクされている | 警告通知を表示、スケジュールからのリンク解除を促す |
| 削除失敗 | その他の削除エラー（例外） | エラー通知を表示、再試行を促す |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

制限なし（エラー発生時に即時表示）

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

- エラーメッセージは固定テキストを使用し、内部情報は含まない
- ルール削除操作は認証済みユーザーのみが実行可能

## 備考

- No.46「ルール削除失敗（スケジュールリンク）」とは同じエラーケースを扱うが、こちらはモバイル版での実装
- No.47「ルール削除失敗」とは異なり、こちらはより具体的なエラーメッセージを提供
- スケジュールからルールのリンクを解除するには、スケジュール編集画面から操作が必要

---

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

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

### 推奨読解順序

#### Step 1: ルール削除処理を理解する

モバイル版でのルール削除処理を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | MobileRulesPage.tsx | `packages/desktop-client/src/components/mobile/rules/MobileRulesPage.tsx` | handleRuleDelete 関数（128-167行目） |

**主要処理フロー**:
1. **130-133行目**: `rule-delete-all` API を呼び出し
2. **135-145行目**: `someDeletionsFailed` が true の場合、warning 通知を表示
3. **153-162行目**: 例外発生時、error 通知を表示
4. **152行目**: ルール一覧を再読み込み

#### Step 2: サーバー側の削除ロジックを理解する

サーバー側でのルール削除処理とスケジュールリンクチェックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | transaction-rules.ts | `packages/loot-core/src/server/transactions/transaction-rules.ts` | deleteRule 関数（229-241行目） |
| 2-2 | app.ts (rules) | `packages/loot-core/src/server/rules/app.ts` | deleteAllRules 関数（133-148行目） |

**主要処理フロー**:
- **230-235行目**: スケジュールにリンクされているかチェック
- **236-237行目**: リンクがある場合は `false` を返す
- **239行目**: リンクがない場合は削除を実行
- **138-144行目**: 複数ルール削除時、一部でも失敗した場合 `someDeletionsFailed: true`

#### Step 3: デスクトップ版での同様の処理を理解する

デスクトップ版でのルール削除処理との違いを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ManageRules.tsx | `packages/desktop-client/src/components/ManageRules.tsx` | onDeleteSelected 関数（223-239行目） |

**読解のコツ**: デスクトップ版では `alert` を使用しているが、モバイル版では通知を使用している点に注目。

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

```
MobileRulesPage.tsx
    │
    ├─ handleRuleDelete (useCallback)
    │      │
    │      └─ send('rule-delete-all', [rule.id])
    │             │
    │             └─ server/rules/app.ts: deleteAllRules
    │                    │
    │                    └─ transaction-rules.ts: deleteRule
    │                           │
    │                           ├─ db.first('schedules WHERE rule = ?')
    │                           │      │
    │                           │      ├─ (リンクあり) → return false
    │                           │      │
    │                           │      └─ (リンクなし) → db.delete_('rules', id)
    │                           │
    │                           └─ return true/false
    │
    ├─ (someDeletionsFailed: true)
    │      └─ addNotification({ type: 'warning', ... })
    │
    ├─ (例外発生)
    │      └─ addNotification({ type: 'error', ... })
    │
    └─ loadRules() → ルール一覧再読み込み
```

### データフロー図

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

ルール削除操作 ─────────────▶ rule-delete-all API ──────────────▶ 結果
                                   │
                                   ├─▶ (someDeletionsFailed: true)
                                   │      └─▶ warning 通知
                                   │
                                   ├─▶ (例外)
                                   │      └─▶ error 通知
                                   │
                                   └─▶ (成功)
                                          └─▶ Undo 通知
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| MobileRulesPage.tsx | `packages/desktop-client/src/components/mobile/rules/MobileRulesPage.tsx` | ソース | モバイル版ルール管理画面 |
| ManageRules.tsx | `packages/desktop-client/src/components/ManageRules.tsx` | ソース | デスクトップ版ルール管理画面 |
| app.ts | `packages/loot-core/src/server/rules/app.ts` | ソース | ルール操作API |
| transaction-rules.ts | `packages/loot-core/src/server/transactions/transaction-rules.ts` | ソース | ルール削除ロジック |
| notificationsSlice.ts | `packages/desktop-client/src/notifications/notificationsSlice.ts` | ソース | 通知の Redux slice 定義 |
| Notifications.tsx | `packages/desktop-client/src/components/Notifications.tsx` | ソース | 通知表示コンポーネント |
