# データベース設計書

## 概要

本ドキュメントは、Actual Budget（個人向け予算管理アプリケーション）のデータベース設計を記述したものです。本システムはSQLiteデータベースを使用し、予算管理、取引記録、スケジュール管理、レポート生成などの機能を提供します。データの同期にはCRDT（Conflict-free Replicated Data Type）が採用されており、複数デバイス間でのデータ整合性が保たれています。

## テーブル一覧

| テーブル名 | 対応エンティティ | 説明 |
| --- | --- | --- |
| accounts | AccountEntity | 銀行口座・資産口座の管理 |
| banks | BankEntity | 銀行機関情報の管理 |
| transactions | TransactionEntity | 取引記録の管理 |
| pending_transactions | - | 保留中の取引管理 |
| categories | CategoryEntity | カテゴリの管理 |
| category_groups | CategoryGroupEntity | カテゴリグループの管理 |
| category_mapping | - | カテゴリのマッピング情報 |
| payees | PayeeEntity | 支払先・入金元の管理 |
| payee_mapping | - | 支払先のマッピング情報 |
| rules | RuleEntity | 自動化ルールの管理 |
| schedules | ScheduleEntity | スケジュール（定期取引）の管理 |
| schedules_next_date | - | スケジュールの次回実行日管理 |
| schedules_json_paths | - | スケジュールのJSONパス情報 |
| custom_reports | CustomReportEntity | カスタムレポートの管理 |
| transaction_filters | TransactionFilterEntity | 取引フィルターの管理 |
| dashboard | Widget | ダッシュボードウィジェットの管理 |
| dashboard_pages | DashboardEntity | ダッシュボードページの管理 |
| zero_budget_months | - | ゼロベース予算月次管理 |
| zero_budgets | - | ゼロベース予算データ |
| reflect_budgets | - | 反映予算データ |
| notes | NoteEntity | ノート・メモの管理 |
| tags | TagEntity | タグの管理 |
| preferences | - | ユーザー設定の管理 |
| messages_crdt | - | CRDT同期メッセージの管理 |
| messages_clock | - | CRDT同期クロックの管理 |
| created_budgets | - | 作成済み予算月の管理 |
| kvcache | - | キーバリューキャッシュ |
| kvcache_key | - | キャッシュキー管理 |
| __meta__ | - | メタデータ管理 |
| __migrations__ | - | マイグレーション履歴管理 |
| db_version | - | データベースバージョン管理 |

## 各テーブル定義

### 1. accounts

銀行口座や資産口座を管理するテーブル。オンバジェット/オフバジェットの区別、口座の状態管理、銀行同期情報を保持します。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | TEXT | NO | 主キー（UUID） |
| account_id | TEXT | YES | 外部銀行システムのアカウントID |
| name | TEXT | YES | 口座名 |
| balance_current | INTEGER | YES | 現在残高（セント単位） |
| balance_available | INTEGER | YES | 利用可能残高 |
| balance_limit | INTEGER | YES | 与信限度額 |
| mask | TEXT | YES | 口座番号の下4桁 |
| official_name | TEXT | YES | 銀行の公式口座名 |
| type | TEXT | YES | 口座種別 |
| subtype | TEXT | YES | 口座サブタイプ |
| bank | TEXT | YES | 銀行ID（外部キー） |
| offbudget | INTEGER | NO | オフバジェットフラグ（0:予算内、1:予算外） |
| closed | INTEGER | NO | クローズフラグ（0:有効、1:閉鎖） |
| sort_order | REAL | YES | 表示順序 |
| account_sync_source | TEXT | YES | 同期ソース（simpleFin/goCardless/pluggyai） |
| last_sync | TEXT | YES | 最終同期日時 |
| last_reconciled | TEXT | YES | 最終照合日時 |
| tombstone | INTEGER | NO | 削除フラグ（0:有効、1:削除済） |

### 2. banks

銀行機関情報を管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | TEXT | NO | 主キー（UUID） |
| bank_id | TEXT | YES | 外部銀行システムの銀行ID |
| name | TEXT | YES | 銀行名 |
| tombstone | INTEGER | NO | 削除フラグ（0:有効、1:削除済） |

### 3. transactions

取引記録を管理するテーブル。親子関係によるスプリット取引、振替取引、スケジュール連携をサポートします。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | TEXT | NO | 主キー（UUID） |
| isParent | INTEGER | NO | 親取引フラグ（スプリット取引の親） |
| isChild | INTEGER | NO | 子取引フラグ（スプリット取引の子） |
| parent_id | TEXT | YES | 親取引ID（スプリット取引時） |
| acct | TEXT | YES | 口座ID（外部キー） |
| category | TEXT | YES | カテゴリID（外部キー） |
| amount | INTEGER | YES | 金額（セント単位、正:入金、負:出金） |
| description | TEXT | YES | 支払先名（payee_id） |
| notes | TEXT | YES | メモ・備考 |
| date | INTEGER | YES | 取引日（数値形式） |
| financial_id | TEXT | YES | 外部金融システムID |
| type | TEXT | YES | 取引タイプ |
| location | TEXT | YES | 位置情報 |
| error | TEXT | YES | エラー情報（JSON） |
| imported_description | TEXT | YES | インポート時の元の説明 |
| starting_balance_flag | INTEGER | NO | 期首残高フラグ |
| transferred_id | TEXT | YES | 振替先取引ID |
| sort_order | REAL | YES | 表示順序 |
| cleared | INTEGER | NO | 確定フラグ（デフォルト1） |
| pending | INTEGER | NO | 保留中フラグ（デフォルト0） |
| reconciled | INTEGER | NO | 照合済フラグ（デフォルト0） |
| schedule | TEXT | YES | スケジュールID（外部キー） |
| raw_synced_data | TEXT | YES | 同期元の生データ |
| tombstone | INTEGER | NO | 削除フラグ（0:有効、1:削除済） |

### 4. pending_transactions

保留中の取引を管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | TEXT | NO | 主キー |
| acct | INTEGER | YES | 口座ID（外部キー） |
| amount | INTEGER | YES | 金額 |
| description | TEXT | YES | 説明 |
| date | TEXT | YES | 日付 |

### 5. categories

予算カテゴリを管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | TEXT | NO | 主キー（UUID） |
| name | TEXT | YES | カテゴリ名 |
| is_income | INTEGER | NO | 収入カテゴリフラグ（0:支出、1:収入） |
| cat_group | TEXT | YES | カテゴリグループID（外部キー） |
| sort_order | REAL | YES | 表示順序 |
| goal_def | TEXT | YES | 目標定義（JSON） |
| template_settings | JSON | YES | テンプレート設定 |
| hidden | BOOLEAN | NO | 非表示フラグ（デフォルト0） |
| tombstone | INTEGER | NO | 削除フラグ（0:有効、1:削除済） |

### 6. category_groups

カテゴリグループを管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | TEXT | NO | 主キー（UUID） |
| name | TEXT | YES | グループ名（ユニーク制約なし） |
| is_income | INTEGER | NO | 収入グループフラグ（0:支出、1:収入） |
| sort_order | REAL | YES | 表示順序 |
| hidden | BOOLEAN | NO | 非表示フラグ（デフォルト0） |
| tombstone | INTEGER | NO | 削除フラグ（0:有効、1:削除済） |

### 7. category_mapping

カテゴリのマッピング情報を管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | TEXT | NO | 主キー（カテゴリID） |
| transferId | TEXT | YES | 振替先カテゴリID |

### 8. payees

支払先・入金元を管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | TEXT | NO | 主キー（UUID） |
| name | TEXT | YES | 支払先名 |
| category | TEXT | YES | デフォルトカテゴリID |
| transfer_acct | TEXT | YES | 振替先口座ID（振替支払先の場合） |
| favorite | INTEGER | NO | お気に入りフラグ（デフォルト0） |
| learn_categories | BOOLEAN | NO | カテゴリ学習フラグ（デフォルト1） |
| tombstone | INTEGER | NO | 削除フラグ（0:有効、1:削除済） |

### 9. payee_mapping

支払先のマッピング情報を管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | TEXT | NO | 主キー（支払先ID） |
| targetId | TEXT | YES | マッピング先支払先ID |

### 10. rules

取引の自動化ルールを管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | TEXT | NO | 主キー（UUID） |
| stage | TEXT | YES | 実行ステージ（pre/null/post） |
| conditions | TEXT | YES | 条件定義（JSON） |
| conditions_op | TEXT | NO | 条件演算子（and/or、デフォルトand） |
| actions | TEXT | YES | アクション定義（JSON） |
| tombstone | INTEGER | NO | 削除フラグ（0:有効、1:削除済） |

### 11. schedules

定期取引（スケジュール）を管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | TEXT | NO | 主キー（UUID） |
| name | TEXT | YES | スケジュール名 |
| rule | TEXT | YES | ルールID（外部キー） |
| active | INTEGER | NO | 有効フラグ（デフォルト0） |
| completed | INTEGER | NO | 完了フラグ（デフォルト0） |
| posts_transaction | INTEGER | NO | 自動取引作成フラグ（デフォルト0） |
| tombstone | INTEGER | NO | 削除フラグ（0:有効、1:削除済） |

### 12. schedules_next_date

スケジュールの次回実行日を管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | TEXT | NO | 主キー |
| schedule_id | TEXT | YES | スケジュールID（外部キー） |
| local_next_date | INTEGER | YES | ローカル次回日付 |
| local_next_date_ts | INTEGER | YES | ローカル次回タイムスタンプ |
| base_next_date | INTEGER | YES | 基準次回日付 |
| base_next_date_ts | INTEGER | YES | 基準次回タイムスタンプ |
| tombstone | INTEGER | NO | 削除フラグ（デフォルト0） |

### 13. schedules_json_paths

スケジュールのJSONパス情報を管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| schedule_id | TEXT | NO | 主キー（スケジュールID） |
| payee | TEXT | YES | 支払先パス |
| account | TEXT | YES | 口座パス |
| amount | TEXT | YES | 金額パス |
| date | TEXT | YES | 日付パス |

### 14. custom_reports

カスタムレポートを管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | TEXT | NO | 主キー（UUID） |
| name | TEXT | YES | レポート名 |
| start_date | TEXT | YES | 開始日 |
| end_date | TEXT | YES | 終了日 |
| date_static | INTEGER | NO | 静的日付フラグ（デフォルト0） |
| date_range | TEXT | YES | 日付範囲タイプ |
| mode | TEXT | NO | モード（デフォルトtotal） |
| group_by | TEXT | NO | グループ化基準（デフォルトCategory） |
| balance_type | TEXT | NO | 残高タイプ（デフォルトExpense） |
| sort_by | TEXT | NO | ソート順（デフォルトdesc） |
| show_empty | INTEGER | NO | 空表示フラグ（デフォルト0） |
| show_offbudget | INTEGER | NO | オフバジェット表示（デフォルト0） |
| show_hidden | INTEGER | NO | 非表示項目表示（デフォルト0） |
| include_current | INTEGER | NO | 現在月含むフラグ（デフォルト0） |
| show_uncategorized | INTEGER | NO | 未分類表示（デフォルト0） |
| trim_intervals | INTEGER | NO | 期間トリムフラグ（デフォルト0） |
| graph_type | TEXT | NO | グラフタイプ（デフォルトBarGraph） |
| conditions | TEXT | YES | 条件定義（JSON） |
| conditions_op | TEXT | NO | 条件演算子（デフォルトand） |
| metadata | TEXT | YES | メタデータ（JSON） |
| interval | TEXT | NO | 期間単位（デフォルトMonthly） |
| color_scheme | TEXT | YES | カラースキーム |
| tombstone | INTEGER | NO | 削除フラグ（デフォルト0） |

### 15. transaction_filters

取引フィルターを管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | TEXT | NO | 主キー（UUID） |
| name | TEXT | YES | フィルター名 |
| conditions | TEXT | YES | 条件定義（JSON） |
| conditions_op | TEXT | NO | 条件演算子（デフォルトand） |
| tombstone | INTEGER | NO | 削除フラグ（デフォルト0） |

### 16. dashboard

ダッシュボードウィジェットを管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | TEXT | NO | 主キー（UUID） |
| dashboard_page_id | TEXT | YES | ダッシュボードページID（外部キー） |
| type | TEXT | YES | ウィジェットタイプ |
| width | INTEGER | YES | 幅 |
| height | INTEGER | YES | 高さ |
| x | INTEGER | YES | X座標 |
| y | INTEGER | YES | Y座標 |
| meta | TEXT | YES | メタ情報（JSON） |
| tombstone | INTEGER | NO | 削除フラグ（デフォルト0） |

### 17. dashboard_pages

ダッシュボードページを管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | TEXT | NO | 主キー（UUID） |
| name | TEXT | YES | ページ名 |
| tombstone | INTEGER | NO | 削除フラグ（デフォルト0） |

### 18. zero_budget_months

ゼロベース予算の月次データを管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | TEXT | NO | 主キー（年-月形式） |
| buffered | INTEGER | NO | バッファ金額（デフォルト0） |

### 19. zero_budgets

ゼロベース予算のカテゴリ別データを管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | TEXT | NO | 主キー（月-カテゴリID） |
| month | INTEGER | YES | 月（数値形式） |
| category | TEXT | YES | カテゴリID |
| amount | INTEGER | NO | 予算金額（デフォルト0） |
| carryover | INTEGER | NO | 繰越フラグ（デフォルト0） |
| goal | INTEGER | YES | 目標金額 |
| long_goal | INTEGER | YES | 長期目標金額 |

### 20. reflect_budgets

反映予算のカテゴリ別データを管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | TEXT | NO | 主キー（月-カテゴリID） |
| month | INTEGER | YES | 月（数値形式） |
| category | TEXT | YES | カテゴリID |
| amount | INTEGER | NO | 予算金額（デフォルト0） |
| carryover | INTEGER | NO | 繰越フラグ（デフォルト0） |
| goal | INTEGER | YES | 目標金額 |
| long_goal | INTEGER | YES | 長期目標金額 |

### 21. notes

ノート・メモを管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | TEXT | NO | 主キー（関連エンティティID） |
| note | TEXT | YES | ノート内容 |

### 22. tags

タグを管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | TEXT | NO | 主キー（UUID） |
| tag | TEXT | YES | タグ名（ユニーク） |
| color | TEXT | YES | タグ色 |
| description | TEXT | YES | タグ説明 |
| tombstone | INTEGER | NO | 削除フラグ（デフォルト0） |

### 23. preferences

ユーザー設定を管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | TEXT | NO | 主キー（設定キー） |
| value | TEXT | YES | 設定値 |

### 24. messages_crdt

CRDT同期メッセージを管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | INTEGER | NO | 主キー（自動採番） |
| timestamp | TEXT | NO | タイムスタンプ（ユニーク） |
| dataset | TEXT | NO | データセット名 |
| row | TEXT | NO | 行ID |
| column | TEXT | NO | カラム名 |
| value | BLOB | NO | 値 |

### 25. messages_clock

CRDT同期クロックを管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | INTEGER | NO | 主キー |
| clock | TEXT | YES | クロック値 |

### 26. created_budgets

作成済み予算月を管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| month | TEXT | NO | 主キー（月） |

### 27. kvcache

キーバリューキャッシュを管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| key | TEXT | NO | 主キー（キー） |
| value | TEXT | YES | 値 |

### 28. kvcache_key

キャッシュキーを管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | INTEGER | NO | 主キー（自動採番） |
| key | REAL | YES | キー値 |

### 29. __meta__

メタデータを管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| key | TEXT | NO | 主キー（メタキー） |
| value | TEXT | YES | メタ値 |

### 30. __migrations__

マイグレーション履歴を管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| id | INT | NO | 主キー（マイグレーションID） |

### 31. db_version

データベースバージョンを管理するテーブル。

| カラム名 | データ型 | NULL | 説明 |
| --- | --- | --- | --- |
| version | TEXT | NO | 主キー（バージョン） |

## 備考

### 削除の論理削除

本システムでは、ほぼ全てのエンティティテーブルに `tombstone` カラムが存在し、物理削除ではなく論理削除（ソフトデリート）が採用されています。これはCRDTによるデータ同期を正しく機能させるための設計です。

### 金額の表現

全ての金額は整数（INTEGER）で保存され、セント単位（100分の1単位）で管理されています。これにより浮動小数点の丸め誤差を回避しています。

### ID体系

主キーにはUUID（TEXT型）が使用されており、分散環境でのID衝突を回避しています。

### 同期サーバーデータベース

同期サーバー側には別途以下のテーブルが存在します：
- `messages_binary`: 暗号化されたメッセージの保存
- `messages_merkles`: マークルツリーによるデータ整合性管理

### インデックス

主要なテーブルには適切なインデックスが設定されており、特に取引テーブルの検索性能が最適化されています。
