# 通知設計書 30-取引インポートエラー

## 概要

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

### 本通知の処理概要

取引インポートエラー通知は、ファイルから取引データを実際にインポートする処理において発生したエラーをユーザーにフィードバックする機能です。プレビュー後の本番インポート処理でのエラーを報告します。

**業務上の目的・背景**：取引インポートは外部ファイル（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[ユーザーがImportボタンを押下] --> B[onImport実行]
    B --> C[importTransactions dispatch]
    C --> D{reconcile?}
    D -->|Yes| E[transactions-import API isPreview=false]
    D -->|No| F[api/transactions-add API]
    E --> G{エラーあり?}
    G -->|Yes| H[errors配列に追加]
    H --> I[errors.forEachでループ]
    I --> J[addNotification dispatch type=error]
    J --> K[UIに通知表示]
    G -->|No| L[成功処理]
    F --> L
    L --> M[setNewTransactions dispatch]
    M --> N[モーダルクローズ]
    K --> N
```

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

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| transactions | 既存取引とのマッチング | reconcile=trueの場合 |
| payees | 支払先のマッチング/作成 | - |
| categories | カテゴリのマッチング | - |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| transactions | INSERT/UPDATE | 取引の追加または更新 |
| payees | INSERT | 新規支払先の作成 |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 日付解析エラー | 日付フォーマットが不正 | 日付フォーマット設定を変更してプレビューから再実行 |
| 金額解析エラー | 金額フィールドが空または不正 | フィールドマッピングを確認してプレビューから再実行 |
| データ整合性エラー | 口座IDが不正など | 正しい口座でインポートを再実行 |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

時間帯制限なし

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

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

## 備考

- 本番インポート処理はisPreview=falseでAPIを呼び出し、実際のデータ変更が行われる
- 複数のエラーがある場合、各エラーが個別の通知として表示される
- reconcile=falseの場合は `api/transactions-add` が直接呼び出され、マッチング処理はスキップされる
- インポート成功時は `setNewTransactions` で新規/更新された取引IDが設定される

---

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

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

### 推奨読解順序

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

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

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

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

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

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

**主要処理フロー**:
1. **583行目**: `onImport` 関数定義
2. **704-710行目**: `importTransactions` をディスパッチしてインポート実行

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

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

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

**主要処理フロー**:
- **576-584行目**: `transactions-import` APIを `isPreview: false` で呼び出し
- **586-594行目**: `errors.forEach` で各エラーに対して `addNotification` をディスパッチ
- **596-602行目**: 成功時は `setNewTransactions` で新規取引を設定

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

```
ImportTransactionsModal (ImportTransactionsModal.tsx)
    │
    └─ onImport (583)
           │
           └─ importTransactions dispatch (704)
                  │
                  └─ importTransactions thunk (accountsSlice.ts:561)
                         │
                         ├─ reconcile=false → api/transactions-add API
                         │
                         └─ reconcile=true → transactions-import API (isPreview: false)
                                │
                                ├─ 成功 → setNewTransactions (596)
                                │         markUpdatedAccounts (604)
                                │
                                └─ エラー → errors.forEach (586)
                                       │
                                       └─ addNotification (588)
                                              │
                                              └─ UI表示
```

### データフロー図

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

Importボタン押下 ───▶ onImport ───▶ importTransactions
                                           │
                                           ▼
                              ┌────────────┴────────────┐
                              ▼                         ▼
                        reconcile=false           reconcile=true
                              │                         │
                              ▼                         ▼
                    api/transactions-add    transactions-import API
                              │             (isPreview: false)
                              │                         │
                              └────────────┬────────────┘
                                           │
                                ┌──────────┴──────────┐
                                ▼                     ▼
                            成功                   エラー
                                │                     │
                                ▼                     ▼
                    setNewTransactions          errors配列
                    markUpdatedAccounts               │
                                │                     ▼
                                ▼               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` | ソース | インポートユーティリティ関数 |
| transactionsSlice.ts | `packages/desktop-client/src/transactions/transactionsSlice.ts` | ソース | 取引の状態管理（setNewTransactions） |
| notificationsSlice.ts | `packages/desktop-client/src/notifications/notificationsSlice.ts` | ソース | 通知の状態管理 |
