# 通知設計書 24-ゴールテンプレート上書き結果

## 概要

本ドキュメントは、ゴールテンプレートを月次予算に上書き適用した結果をユーザーに表示する通知の仕様を定義します。

### 本通知の処理概要

ゴールテンプレート上書き結果通知は、カテゴリに設定されたゴールテンプレートを指定月の予算に強制的に上書き適用し、その処理結果をユーザーにフィードバックする機能です。既存の予算設定も上書きされます。

**業務上の目的・背景**：通常の「Apply budget template」では既に予算が設定されているカテゴリはスキップされますが、月の途中でテンプレートを変更した場合や、手動で設定した予算をテンプレートに基づいて再設定したい場合に、強制的に上書き適用する必要があります。この通知により、ユーザーは上書き処理の結果を確認できます。

**通知の送信タイミング**：ユーザーが予算画面のメニューから「Overwrite with budget template」アクションを実行した際に、テンプレートの上書き適用処理が行われ、結果が通知として表示されます。

**通知の受信者**：上書きアクションを実行したユーザー（現在の予算ファイルを操作中のユーザー）に対して通知が表示されます。

**通知内容の概要**：テンプレートの上書き適用結果として、適用されたカテゴリ数、既に最新の状態である場合のメッセージ、またはテンプレート解釈エラーの詳細が表示されます。

**期待されるアクション**：成功時は予算が正しく上書きされたことを確認し、必要に応じてUndo機能で元に戻すことができます。エラーがある場合は該当カテゴリのテンプレートを修正することが期待されます。

## 通知種別

アプリ内通知（メッセージタイプまたはエラータイプ）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（ユーザーアクション駆動） |
| 優先度 | 中 |
| リトライ | なし |

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

上書きアクションを実行したユーザーに対して結果を表示します。

## 通知テンプレート

### アプリ内通知

| 項目 | 内容 |
|-----|------|
| 通知タイプ | message（成功時）/ sticky（エラー時） |
| 件名/タイトル | なし |
| 表示形式 | トースト通知 |

### 本文テンプレート

**成功時（適用あり）：**
```
Successfully applied templates to {カテゴリ数} categories
```

**成功時（適用なし）：**
```
Everything is up to date
```

**エラー時：**
```
There were errors interpreting some templates:

{カテゴリ名}: {エラー内容}
...
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| カテゴリ数 | 適用されたカテゴリの数 | 処理結果 | No |
| pre | エラー詳細（改行区切り） | テンプレート解析結果 | No（エラー時のみ） |
| message | メインメッセージ | 固定値/動的生成 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 画面操作 | overwrite-goal-templateアクション | 常時 | 予算メニューから上書き実行時 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| なし | 上書き実行時は常に結果を通知 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[ユーザーがOverwrite with budget templateを実行] --> B[applyBudgetAction dispatch]
    B --> C[budget/overwrite-goal-template API呼び出し]
    C --> D[overwriteTemplate実行]
    D --> E[テンプレートノートを保存]
    E --> F[カテゴリテンプレート取得]
    F --> G[processTemplate実行 force=true]
    G --> H{エラーあり?}
    H -->|Yes| I[エラー詳細を含む通知生成]
    H -->|No| J{適用カテゴリあり?}
    J -->|Yes| K[成功メッセージ通知生成]
    J -->|No| L[最新状態メッセージ通知生成]
    I --> M[addNotification dispatch]
    K --> M
    L --> M
    M --> N[UIに通知表示]
    N --> O[終了]
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| categories | カテゴリ情報とテンプレート定義の取得 | goal_defカラムからテンプレート取得 |
| category_groups | カテゴリグループ情報 | 非表示カテゴリのフィルタリング |
| zero_budgets / reflect_budgets | 現在の予算値 | 上書き前の値参照 |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| zero_budgets | UPDATE | 予算金額の強制上書き |
| reflect_budgets | UPDATE | Reflect予算の場合の予算金額上書き |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| テンプレート解釈エラー | CategoryTemplateContext初期化失敗 | エラー詳細を通知に表示 |
| 構文エラー | テンプレート構文が不正 | エラー行を通知に表示 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

時間帯制限なし

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

- テンプレート処理はサーバー側で安全に実行
- 予算金額の変更はUndoable（取り消し可能）

## 備考

- 「Apply budget template」との違いは `force` パラメータが `true` であること
- 既存の予算設定も上書きされるため注意が必要
- 処理はUndoable（取り消し可能）
- 優先度（priority）に基づいて処理順序が決定される

---

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

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

### 推奨読解順序

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

Notification型とTemplate型を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | goal-template.ts | `packages/loot-core/src/server/budget/goal-template.ts` | Notification型（17-23行目） |
| 1-2 | templates.ts | `packages/loot-core/src/types/models/templates.ts` | Template型の各種タイプ定義 |

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

クライアント側からの呼び出しフローを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | budgetSlice.ts | `packages/desktop-client/src/budget/budgetSlice.ts` | overwrite-goal-templateケース（481-489行目） |

**主要処理フロー**:
1. **481行目**: `case 'overwrite-goal-template':` でアクション分岐
2. **482-488行目**: `send('budget/overwrite-goal-template', { month })` でAPIを呼び出し、結果を `addNotification` でディスパッチ

#### Step 3: サーバー側処理を理解する

テンプレート上書き適用の実装を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | goal-template.ts | `packages/loot-core/src/server/budget/goal-template.ts` | overwriteTemplate関数（59-68行目） |
| 3-2 | goal-template.ts | `packages/loot-core/src/server/budget/goal-template.ts` | processTemplate関数（187-312行目） |

**主要処理フロー**:
- **59行目**: `overwriteTemplate` 関数開始
- **64行目**: `storeNoteTemplates()` でノートからテンプレートを保存
- **65行目**: `getTemplates()` でテンプレート取得
- **66行目**: `processTemplate(month, true, ...)` で上書き適用（force=true）

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

```
applyBudgetAction (budgetSlice.ts:442)
    │
    ├─ case 'overwrite-goal-template' (budgetSlice.ts:481)
    │      │
    │      └─ send('budget/overwrite-goal-template', { month })
    │             │
    │             └─ app.method('budget/overwrite-goal-template') (app.ts:91)
    │                    │
    │                    └─ goalActions.overwriteTemplate (goal-template.ts:59)
    │                           │
    │                           ├─ storeNoteTemplates()
    │                           ├─ getTemplates()
    │                           └─ processTemplate(month, true, ...)
    │                                  │                    ▲
    │                                  │               force=true
    │                                  │
    │                                  └─ 全カテゴリを強制上書き
    │
    └─ addNotification (budgetSlice.ts:482)
```

### データフロー図

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

ユーザーアクション ───▶ budget/overwrite-goal-template API ───▶ overwriteTemplate
      │                                                              │
      │                                                              ▼
      │                                                    storeNoteTemplates
  month引数                                                          │
                                                                     ▼
                                                          getTemplates
                                                                     │
                                                                     ▼
                                                          processTemplate
                                                          (force=true)
                                                                     │
                                                     ┌───────────────┴───────────────┐
                                                     ▼                               ▼
                                            全カテゴリ処理                   ゴール/予算更新
                                           （既存予算も上書き）                        │
                                                     │                               ▼
                                                     └───────────────┬───────────────┘
                                                                     ▼
                                                          Notification生成
                                                                     │
                                                                     ▼
                                                               UI表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| budgetSlice.ts | `packages/desktop-client/src/budget/budgetSlice.ts` | ソース | クライアント側のアクション処理 |
| goal-template.ts | `packages/loot-core/src/server/budget/goal-template.ts` | ソース | テンプレート上書き適用のメイン処理 |
| category-template-context.ts | `packages/loot-core/src/server/budget/category-template-context.ts` | ソース | カテゴリ毎のテンプレート計算コンテキスト |
| app.ts | `packages/loot-core/src/server/budget/app.ts` | ソース | 予算関連APIのルーティング |
