テーブル定義書¶

関連: 月次予算 / 支出の保存 / 収入 / PostgreSQL

正は sql/ のマイグレーションである。 Bot 起動時に src/finance_manager/db.py の SCHEMA_FILES 順で適用する。 金額の初期値はスキーマとは別で、sql/budget_seed.example.sql を手動実行する。

全体像¶

incomes (給与) ──► budget_months.ceiling_yen
budget_settings / category_budgets ──► 初回 draft のフォールバック
fixed_cost_items ──► budget_months.fixed_costs_yen / variable_pool_yen
budget_month_categories ──► 変動カテゴリ枠
expenses ──► 変動消化（固定費カテゴリは除外）
surplus_ledger ◄── 未割当 / 月末実残

expenses ◄── notification_raw.expense_id（任意）
wishlist_items / planned_expenses … 固定貯金、別枠とは別

外部キーとして存在する線は、月ヘッダと変動枠、通知と支出の2本だけである。 給与、固定費マスタ、seed、別枠はアプリが読んで計算する。

物理 ER¶

erDiagram
  budget_months ||--|{ budget_month_categories : "year_month"
  expenses ||--o{ notification_raw : "expense_id"

  expenses {
    bigint id PK
    int amount_yen
    text category
    timestamptz paid_at
  }
  incomes {
    bigint id PK
    int amount_yen
    text category
    timestamptz received_at
  }
  budget_months {
    date year_month PK
    int ceiling_yen
    int savings_yen
    int fixed_costs_yen
    int variable_pool_yen
    text status
  }
  budget_month_categories {
    date year_month PK
    text category PK
    int monthly_limit_yen
  }
  fixed_cost_items {
    bigint id PK
    text name UK
    int monthly_yen
    text expense_category
    boolean active
  }
  surplus_ledger {
    bigint id PK
    date year_month
    int amount_yen
    text reason
  }
  budget_settings {
    int id PK
    int monthly_income_yen
    int monthly_savings_yen
  }
  category_budgets {
    text category PK
    int monthly_limit_yen
  }
  notification_raw {
    bigint id PK
    bigint expense_id FK
  }
  wishlist_items {
    bigint id PK
    text name
    int target_yen
  }
  planned_expenses {
    bigint id PK
    text name
    int target_yen
    date deadline
  }

wishlist_items と planned_expenses は他テーブルとつながっていない。 固定貯金、別枠貯金とも別の袋である。

予算の流れ¶

草案を作るとき、本来の値（前月給与、前月の変動枠）が無ければ seed を使う。 点線がフォールバックである。

flowchart LR
  subgraph 本来の正
    I["incomes 前月の給与"] --> BM["budget_months 今月"]
    FC["fixed_cost_items"] --> BM
    BMC["budget_month_categories"] --> BM
  end

  subgraph フォールバック
    BS["budget_settings"] -.->|給与が無いとき天井| BM
    CB["category_budgets"] -.->|初月だけ枠のひな型| BMC
  end

  E["expenses 変動カテゴリ"] --> SP["変動の消化"]
  BM --> U["未割当 / 月末実残"]
  U --> SL["surplus_ledger 別枠"]

適用順（SCHEMA_FILES）¶

sql/grafana_readonly_grants.sql は Grafana 用 GRANT の手作業ファイルで、起動時には走らない。

expenses（支出）¶

1件の支出を置く。 Discord 手動が本線である。

インデックス: paid_at, created_at, subcategories（GIN）

大分類の現行値は 支出の保存 / 月次予算 を参照する。

incomes（収入）¶

支出とは別テーブルである。 ID も別採番し、返事では income_id= と出す。

予算上限に使うのは category = '給与' の前月合計だけである。 ボーナスは記録するが、上限には入れない。

budget_settings / category_budgets（フォールバック）¶

行はほぼ seed 用である。 月次の正は budget_months 側にある。

budget_settings¶

1行だけ置く（id = 1）。

category_budgets¶

当月行が無いとき、ここから budget_month_categories へコピーする。 その他 と固定費カテゴリは置かない。

budget_months（月ヘッダ）¶

year_month はその月の1日である。

draft 中は、前月給与と固定費マスタから天井と変動枠を取り直す。

budget_month_categories（変動カテゴリ枠）¶

親行削除で CASCADE する。 固定費名（家賃、通信など）はここに入れない。

fixed_cost_items（固定費マスタ）¶

毎月引く定額リストである。 実績支出とは別に「引く額」を持つ。

expense_category が付いている支出は、変動枠の消化に入れない。 未設定（例: 散髪）は引くだけである。

surplus_ledger（別枠貯金）¶

固定貯金とは別の袋である。 正は入金、負は出金とする。

同じ月、同じ reason は二重に積まない。

wishlist_items / planned_expenses¶

固定貯金、別枠貯金とはさらに別である。

wishlist_items¶

planned_expenses¶

wishlist に近い。 違うのは deadline（DATE）と status open / done / cancelled である。

notification_raw（通知の生データ）¶

PayPay 等の Android 通知を置く。 自動取込は後段である。

権限¶

Grafana は SELECT のみである。 finance_readonly への GRANT は各 sql/*.sql の末尾、または sql/grafana_readonly_grants.sql にある。