# 機能設計書 45-バックアップ管理

## 概要

本ドキュメントは、Actualの「バックアップ管理」機能の設計内容を記載する。予算ファイルの自動バックアップ作成と保持管理について、処理内容を定義する。

### 本機能の処理概要

バックアップ管理機能は、予算データの自動バックアップを定期的に作成し、一定数を保持する機能である。ユーザーの操作なしにバックグラウンドで動作し、データ損失に対する安全策を提供する。

**業務上の目的・背景**：予算データは重要な個人資産情報であり、誤操作やシステム障害によるデータ損失を防ぐため、自動バックアップ機能を提供する。ローカルファーストアーキテクチャにおいて、ユーザー自身がデータ管理の責任を持つため、堅牢なバックアップ機構が必要となる。

**機能の利用シーン**：通常運用時のバックグラウンド処理として自動実行される。ユーザーが設定画面でバックアップ情報を確認する場合、データ復旧が必要な場合に利用される。

**主要な処理内容**：
1. 15分間隔での自動バックアップ作成
2. 最大10世代のバックアップ保持
3. Actualデータディレクトリへのバックアップ保存
4. 古いバックアップの自動削除

**関連システム・外部連携**：なし（ローカルファイルシステムのみ）

**権限による制御**：特になし（全ユーザーが利用可能）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 40 | 設定画面 | 主機能 | 予算ファイルのバックアップ作成・復元 |
| 8 | 予算ファイル選択画面 | 補助機能 | 予算ファイルのバックアップ状態確認 |

## 機能種別

データ保護・自動バックアップ処理

## 入力仕様

### 入力パラメータ

本機能はユーザー入力を必要としない自動処理である。

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| - | - | - | - | - |

### 入力データソース

- 予算ファイル（現在開いている予算データ）
- システム時刻（バックアップタイミング判定）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| バックアップファイル | ファイル | 予算データのスナップショット |

### 出力先

- Actualデータディレクトリ内のバックアップフォルダ

## 処理フロー

### 処理シーケンス

```
1. バックアップタイマー起動
   └─ 15分間隔でバックアップ処理を実行

2. バックアップ作成
   ├─ 現在の予算データをスナップショット化
   └─ バックアップディレクトリに保存

3. バックアップローテーション
   ├─ 保存されているバックアップ数を確認
   ├─ 10世代を超える場合
   │    └─ 最も古いバックアップを削除
   └─ 10世代以下の場合
        └─ そのまま保持
```

### フローチャート

```mermaid
flowchart TD
    A[アプリケーション起動] --> B[バックアップタイマー開始]
    B --> C{15分経過?}

    C -->|No| D[待機]
    D --> C

    C -->|Yes| E[予算データスナップショット作成]
    E --> F[バックアップディレクトリに保存]
    F --> G{バックアップ数 > 10?}

    G -->|Yes| H[最古のバックアップを削除]
    G -->|No| I[処理完了]

    H --> I
    I --> D
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-45-01 | バックアップ間隔 | 15分ごとにバックアップを作成 | アプリケーション稼働中 |
| BR-45-02 | 最大保持数 | 最大10世代のバックアップを保持 | 常時 |
| BR-45-03 | 保存場所 | Actualデータディレクトリにバックアップを保存 | 常時 |
| BR-45-04 | 自動削除 | 10世代を超えた場合、最古のバックアップを自動削除 | バックアップ作成時 |

### 計算ロジック

バックアップ容量の目安:
- 最大保持数: 10世代
- バックアップ間隔: 15分
- 最大保持期間: 約2.5時間分（10 x 15分）

## データベース操作仕様

### 操作別データベース影響一覧

本機能はデータベースを直接操作しない。ファイルシステムへのバックアップ保存のみ。

| 操作 | 対象 | 操作種別 | 概要 |
|-----|------|---------|------|
| バックアップ作成 | ファイルシステム | CREATE | 予算データのスナップショットを作成 |
| バックアップ削除 | ファイルシステム | DELETE | 古いバックアップを削除 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| BACKUP_WRITE_FAILED | 書込エラー | ディスク容量不足、権限不足 | エラーログ出力、次回バックアップで再試行 |
| BACKUP_DELETE_FAILED | 削除エラー | ファイルロック、権限不足 | エラーログ出力、次回処理で再試行 |

### リトライ仕様

バックアップ失敗時は次回のバックアップタイミング（15分後）で自動的に再試行される。

## トランザクション仕様

ファイルシステム操作のため、データベーストランザクションは使用しない。バックアップファイルは一時ファイルへの書き込み後、リネームによるアトミック操作で完了する。

## パフォーマンス要件

- バックアップ作成: 予算ファイルサイズに依存（通常数秒以内）
- バックグラウンド実行のため、ユーザー操作への影響は最小限

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

- バックアップファイルはローカルに保存され、クラウドには自動送信されない
- バックアップファイルには予算データが含まれるため、ファイルシステムのアクセス制御に依存

## 備考

- 設定画面ではバックアップの頻度と最大保持数が情報として表示される
- バックアップからの復元機能は予算ファイル選択画面から利用可能
- バックアップ設定はユーザーによる変更ができず、固定値（15分、10世代）となっている

---

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

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

### 推奨読解順序

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

バックアップ管理で使用される定数を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Backups.tsx | `packages/desktop-client/src/components/settings/Backups.tsx` | バックアップ設定の定数値（9-10行目） |

**読解のコツ**: BACKUP_FREQUENCY_MINS = 15（バックアップ間隔）、MAX_BACKUPS = 10（最大保持数）がコンポーネント内で定数として定義されている。

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

バックアップ設定表示UIを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Backups.tsx | `packages/desktop-client/src/components/settings/Backups.tsx` | Backupsコンポーネント全体の構造（8-31行目） |

**主要処理フロー**:
1. **9-10行目**: バックアップ設定の定数定義
2. **12-30行目**: 設定情報の表示（UIのみ、設定変更機能なし）
3. **19-25行目**: Trans コンポーネントで翻訳対応した説明テキスト

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

```
Backups (Backups.tsx)
    │
    └─ Setting (UI.tsx)
           └─ 定数値を表示するのみ
              ├─ BACKUP_FREQUENCY_MINS: 15
              └─ MAX_BACKUPS: 10
```

### データフロー図

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

なし（情報表示のみ）────▶ 定数読み込み ──────────────▶ UI表示
                          ├─ BACKUP_FREQUENCY_MINS      ├─ バックアップ頻度
                          └─ MAX_BACKUPS                └─ 最大保持数
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Backups.tsx | `packages/desktop-client/src/components/settings/Backups.tsx` | ソース | バックアップ設定表示UIコンポーネント |
| UI.tsx | `packages/desktop-client/src/components/settings/UI.tsx` | ソース | 設定画面共通UIコンポーネント |
