# 通知設計書 29-取引インポートエラー（プレビュー）

## 概要

本ドキュメントは、取引インポートのプレビュー処理中にエラーが発生した場合にユーザーに表示される通知の仕様を定義します。

### 本通知の処理概要

取引インポートエラー（プレビュー）通知は、ファイルから取引データをインポートする前のプレビュー段階で発生したエラーをユーザーにフィードバックする機能です。プレビュー処理では、インポート対象の取引が既存の取引とどのようにマッチングされるかを事前に確認できます。

**業務上の目的・背景**：取引インポートは外部ファイル（CSV、OFX、QFX、QIF等）から取引データを取り込む重要な機能です。プレビュー段階でエラーを検出することで、実際のインポート前に問題を把握し、データの整合性を保つことができます。エラーが発生した場合、ユーザーはファイル形式の修正やマッピング設定の調整を行うことができます。

**通知の送信タイミング**：取引インポートモーダルでプレビュー処理を実行した際、サーバー側でエラーが発生した時点で通知が表示されます。プレビュー処理はファイル選択後やマッピング変更時に自動的に実行されます。

**通知の受信者**：インポート処理を実行しているユーザーに対して通知が表示されます。

**通知内容の概要**：サーバーから返されたエラーメッセージがそのまま表示されます。エラーの種類に応じて、日付フォーマットの問題、金額の解析エラー、必須フィールドの欠落などが報告されます。

**期待されるアクション**：エラー内容を確認し、インポートファイルの修正、フィールドマッピングの調整、または日付フォーマットの変更を行うことが期待されます。

## 通知種別

アプリ内通知（エラータイプ）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（プレビュー処理完了時） |
| 優先度 | 高 |
| リトライ | なし |

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

プレビュー処理を実行したユーザーに対して通知を表示します。

## 通知テンプレート

### アプリ内通知

| 項目 | 内容 |
|-----|------|
| 通知タイプ | error |
| 件名/タイトル | なし |
| 表示形式 | トースト通知 |

### 本文テンプレート

```
{エラーメッセージ}
```

エラーメッセージの例：
- `Unable to parse date {日付} with given date format`
- `Transaction on {日付} has no amount`

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| message | エラーメッセージ | error.message | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| 画面操作 | プレビュー処理実行 | エラー発生時 | インポートモーダルでのプレビュー時 |

### 送信抑止条件

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

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[ユーザーがファイルを選択/マッピング変更] --> B[getImportPreview実行]
    B --> C[importPreviewTransactions dispatch]
    C --> D[transactions-import API isPreview=true]
    D --> E{エラーあり?}
    E -->|Yes| F[errors配列に追加]
    F --> G[errors.forEachでループ]
    G --> H[addNotification dispatch type=error]
    H --> I[UIに通知表示]
    E -->|No| J[プレビュー結果表示]
    I --> K[終了]
    J --> K
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| transactions | 既存取引とのマッチング | プレビュー処理でのみ参照 |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| なし | - | プレビュー処理ではデータ更新なし |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 日付解析エラー | 日付フォーマットが不正またはマッチしない | 日付フォーマット設定を変更 |
| 金額解析エラー | 金額フィールドが空または不正 | フィールドマッピングを確認 |
| ファイル解析エラー | ファイル形式が不正 | 正しい形式のファイルを選択 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

時間帯制限なし

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

- インポートファイルの内容はサーバー側で安全に処理
- エラーメッセージにはファイルパスの詳細を含めない

## 備考

- プレビュー処理はisPreview=trueでAPIを呼び出すため、実際のデータ変更は行われない
- 複数のエラーがある場合、各エラーが個別の通知として表示される
- プレビュー結果はUIのテーブルにも表示され、マッチング状態を確認できる

---

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

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

### 推奨読解順序

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

エラーレスポンスの構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | accountsSlice.ts | `packages/desktop-client/src/accounts/accountsSlice.ts` | importPreviewTransactions thunk（528-552行目） |

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | ImportTransactionsModal.tsx | `packages/desktop-client/src/components/modals/ImportTransactionsModal/ImportTransactionsModal.tsx` | getImportPreview関数（228-369行目） |

**主要処理フロー**:
1. **228行目**: `getImportPreview` コールバック関数定義
2. **316-322行目**: `importPreviewTransactions` をディスパッチしてプレビュー取得

#### Step 3: エラーハンドリングを理解する

エラー発生時の通知処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | accountsSlice.ts | `packages/desktop-client/src/accounts/accountsSlice.ts` | importPreviewTransactions内のエラー処理（540-549行目） |

**主要処理フロー**:
- **534行目**: `transactions-import` APIを `isPreview: true` で呼び出し
- **540-548行目**: `errors.forEach` で各エラーに対して `addNotification` をディスパッチ

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

```
ImportTransactionsModal (ImportTransactionsModal.tsx)
    │
    └─ getImportPreview (228)
           │
           └─ importPreviewTransactions dispatch (316)
                  │
                  └─ importPreviewTransactions thunk (accountsSlice.ts:528)
                         │
                         └─ transactions-import API (isPreview: true)
                                │
                                ├─ 成功 → updatedPreview 返却
                                │
                                └─ エラー → errors.forEach (540)
                                       │
                                       └─ addNotification (542)
                                              │
                                              └─ UI表示
```

### データフロー図

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

ファイル選択 ───▶ getImportPreview ───▶ importPreviewTransactions
マッピング変更                                    │
                                                 ▼
                                    transactions-import API
                                    (isPreview: true)
                                                 │
                                      ┌──────────┴──────────┐
                                      ▼                     ▼
                                  成功                   エラー
                                      │                     │
                                      ▼                     ▼
                              updatedPreview          errors配列
                                      │                     │
                                      ▼                     ▼
                              プレビュー表示          addNotification
                                                      (type: error)
                                                            │
                                                            ▼
                                                       UI表示
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ImportTransactionsModal.tsx | `packages/desktop-client/src/components/modals/ImportTransactionsModal/ImportTransactionsModal.tsx` | ソース | インポートモーダルUI |
| accountsSlice.ts | `packages/desktop-client/src/accounts/accountsSlice.ts` | ソース | プレビュー処理とエラーハンドリング |
| utils.ts | `packages/desktop-client/src/components/modals/ImportTransactionsModal/utils.ts` | ソース | インポートユーティリティ関数 |
| notificationsSlice.ts | `packages/desktop-client/src/notifications/notificationsSlice.ts` | ソース | 通知の状態管理 |
