226 lines
15 KiB
Markdown
226 lines
15 KiB
Markdown
# Jarca Ledger MCP Data Model
|
|
|
|
- Baseline Mode: observed
|
|
- Baseline Seed: `.stage-pilot/bootstrap/baseline.yaml`
|
|
- Status: draft
|
|
- Owner: Jarca / project maintainer
|
|
- Last Updated (KST): 2026-07-01
|
|
- Source Discovery / Batch: bootstrap-baseline, BAT-008, BAT-009
|
|
|
|
## Project Summary
|
|
- Jarca 가계부 전용 MCP 서버와 Streamlit 대시보드로 계좌/카드 거래, 예산, 분류 규칙, import, 현금흐름 분석을 SQLite에 저장하고 운영한다.
|
|
|
|
## Purpose
|
|
- This document captures the current data-model baseline for future Discovery, REQ, Batch, and Release work.
|
|
- It focuses on durable entities, state rules, consistency rules, and persistence boundaries rather than implementation-only details.
|
|
|
|
## Persistence Backend
|
|
- SQLite database at `~/.local/share/jarca/ledger.sqlite3` by default.
|
|
- Override path through `JARCA_LEDGER_DB_PATH`.
|
|
- Schema initialization and migrations are managed by `jarca_ledger_mcp/db.py`.
|
|
|
|
## Entity: LedgerAccount
|
|
- Source of Truth: `ledger_accounts`
|
|
- Purpose: Represents bank, card, cash, investment, or loan accounts used to attach transaction evidence and balances.
|
|
- Lifecycle: created -> updated -> inactive/archived
|
|
- Key Fields:
|
|
- `id` :: text :: stable account identifier
|
|
- `name` :: text :: operator-facing account name
|
|
- `type` :: text :: bank/card/cash/investment/loan classification
|
|
- `institution` :: text :: financial institution or source
|
|
- `account_number_masked` :: text :: masked account identifier
|
|
- `holder_name` :: text :: owner context for transfer matching
|
|
- `last_balance` :: integer :: latest known balance when available
|
|
- `last_synced_at` :: text :: 기준 잔액 스냅샷 시각. 정기 대조는 월말 23:59 KST, 수시 대조는 사용자 입력 시각
|
|
- `statement_status` :: text :: `unknown`, `import_supported`, `manual_only`, `partial_import`
|
|
- `liquidity_bucket` :: text :: `cash`, `investment`, `deposit`, `real_estate`, `loan`, `other`; 자산 유동성/구성/순자산 집계의 계좌 단위 권위 소스
|
|
- Relationships:
|
|
- `transactions.account_id` links rows to accounts.
|
|
- State Rules:
|
|
- `active=false` hides accounts from default lists without deleting history.
|
|
- `manual_only` is the statement-unavailable class; `partial_import` remains eligible for manual supplementation and balance reconciliation.
|
|
- Balance reconciliation is report/preview first: compare `baseline_balance`/`baseline_at` against the latest `balance_after` or net account transaction delta, with 1,000 KRW absolute tolerance.
|
|
- 계좌 기반 자산/부채는 `last_balance`를 현재 평가 권위 소스로 사용하고, `last_synced_at`을 기준일, `memo`를 출처 메모로 보존한다.
|
|
- 거래로 산출되지 않는 비거래 자산/부채는 `ManualAsset`에 별도 저장한다. 계좌와 수기 자산을 같은 항목으로 중복 등록하지 않는다.
|
|
- `liquidity_bucket='loan'`은 자산 구성 비율 분모에서 제외하고 총부채/순자산 산식에만 반영한다. `last_balance`가 없는 계좌/자산은 임의 거래 합계로 추정하지 않는다.
|
|
|
|
## Entity: ManualAsset
|
|
- Source of Truth: `manual_assets`
|
|
- Purpose: Stores non-transaction-derived assets/liabilities such as real estate, deposits, loans, and other manually valued holdings that should not be mixed into account rows.
|
|
- Lifecycle: created -> revalued/updated -> inactive/archived
|
|
- Key Fields:
|
|
- `id` :: text :: stable manual asset identifier
|
|
- `name` :: text :: operator-facing asset/liability name
|
|
- `liquidity_bucket` :: text :: `cash`, `investment`, `deposit`, `real_estate`, `loan`, `other`
|
|
- `valuation_amount` :: integer nullable :: latest manually entered valuation/balance; null means excluded from valuation totals
|
|
- `valuation_date` :: date text :: valuation basis date
|
|
- `currency` :: text :: default `KRW`
|
|
- `source_note` :: text :: valuation evidence/source memo
|
|
- `memo` :: text :: operator note
|
|
- `active` :: integer/bool :: inactive rows are excluded from default read reports
|
|
- Relationships:
|
|
- Referenced by `asset_snapshots.source_type='manual_asset'` and `source_id` when a month-end valuation is snapshotted.
|
|
- State Rules:
|
|
- `manual_assets` is the live authority source for non-transaction assets/liabilities.
|
|
- Create/update mutation validates name, date, liquidity bucket, source evidence fields, and stores changes additively in the existing row; inactive rows are hidden from default valuation reports.
|
|
- Soft delete/deactivate (`active=false`) is the default deletion semantic so historical `asset_snapshots.source_id` remains reproducible. Hard delete is exceptional cleanup only.
|
|
- Missing `valuation_amount` rows are excluded; transaction sums are not used as a substitute.
|
|
- `loan` bucket values are treated as liabilities and subtracted from asset-bucket totals.
|
|
|
|
## Entity: AssetSnapshot
|
|
- Source of Truth: `asset_snapshots`
|
|
- Purpose: Append-only item-level record of a basis-date asset/liability valuation produced from the live authority sources.
|
|
- Lifecycle: appended at month-end/manual close -> read for point-in-time reports and timeseries
|
|
- Key Fields:
|
|
- `id` :: text :: snapshot row identifier
|
|
- `basis_date` :: date text :: valuation date represented by the row
|
|
- `source_type` :: text :: `account` or `manual_asset`
|
|
- `source_id` :: text :: source entity identifier when available
|
|
- `name` :: text :: snapshot display name copied from the source at capture time
|
|
- `amount` :: integer nullable :: snapshotted valuation amount
|
|
- `liquidity_bucket` :: text :: bucket copied from the source at capture time
|
|
- `valuation_source`, `source_note`, `memo` :: text :: evidence and operator context
|
|
- `snapshot_run_id` :: text :: month-end close run identifier for rows created together
|
|
- `correction_of_run_id` :: text :: previous close run corrected by this append-only run when applicable
|
|
- `correction_reason` :: text :: operator reason required for same-date re-close/correction
|
|
- `is_correction` :: integer/bool :: marks correction close rows
|
|
- `closed_at` :: text :: close execution timestamp copied across the run
|
|
- `created_at` :: text :: snapshot row creation timestamp
|
|
- Relationships:
|
|
- Represents a historical record of `LedgerAccount.last_balance` or `ManualAsset.valuation_amount` rather than a new primary input source.
|
|
- State Rules:
|
|
- Snapshot rows are append-only. Existing rows are not destructively overwritten.
|
|
- `preview_asset_snapshot_close` computes the source item list, bucket totals, total assets/liabilities, net worth, and warnings without writing rows.
|
|
- `close_asset_snapshot` writes one run of item-level rows for a basis date from live authority sources. Same-date re-close requires `correction_reason`, appends a new correction run, and links to the previous `snapshot_run_id` when available.
|
|
- Read reports choose the latest run for a basis date when run metadata exists, preserving original and correction rows for audit while avoiding double counting.
|
|
- Basis-date snapshot reports prefer stored `asset_snapshots` rows when rows exist for the date; otherwise read reports can fall back to live authority sources.
|
|
|
|
## Entity: Transaction
|
|
- Source of Truth: `transactions`
|
|
- Purpose: Represents imported or manually entered financial event evidence.
|
|
- Lifecycle: created/imported -> categorized/reconciled -> soft-deleted or retained
|
|
- Key Fields:
|
|
- `transaction_date` :: date text :: ledger date
|
|
- `posted_date` / `transaction_datetime` :: text :: source timing detail where available
|
|
- `type` :: text :: `income`, `expense`, `transfer`, `refund`, or `adjustment`
|
|
- `amount` :: integer :: positive KRW amount
|
|
- `category` / `subcategory` :: text :: household classification
|
|
- `merchant`, `counterparty`, `description`, `payment_method` :: text :: evidence and display fields
|
|
- `source`, `external_id`, `import_batch_id`, `raw_summary`, `raw_payload` :: text :: provenance and audit fields
|
|
- `memo` :: text :: operator notes and reconciliation tags
|
|
- `status` :: text :: active/deleted/review lifecycle state where used
|
|
- Relationships:
|
|
- belongs to LedgerAccount through `account_id`
|
|
- linked to ImportBatch through `import_batch_id`
|
|
- interpreted with LedgerCategory through `category`/`subcategory`
|
|
- State Rules:
|
|
- Amount is stored positive; `type` determines direction.
|
|
- Cancellation/refund rows should use `refund` type when confirmed.
|
|
- Manual link evidence should be memo-tagged rather than silently rewritten.
|
|
|
|
## Entity: LedgerCategory
|
|
- Source of Truth: `ledger_categories`
|
|
- Purpose: Defines category/subcategory labels and their cashflow semantics.
|
|
- Lifecycle: seeded/created -> updated -> inactive/deleted
|
|
- Key Fields:
|
|
- `category` :: text
|
|
- `subcategory` :: text
|
|
- `cashflow_kind` :: text :: `income`, `expense`, `transfer`, `investment`, `debt_payment`, `exclude`, `unknown`
|
|
- `sort_order`, `memo`, `active`
|
|
- Relationships:
|
|
- Referenced by Transaction classification.
|
|
- Targeted by CategoryRule results.
|
|
- State Rules:
|
|
- `cashflow_kind` controls inclusion in actual household cashflow reports.
|
|
- Transfer, investment, exclude, and unresolved kinds are not actual household spending unless a report explicitly asks for account movements.
|
|
|
|
## Entity: CategoryRule
|
|
- Source of Truth: `category_rules`
|
|
- Purpose: Automatic classification policy for transactions.
|
|
- Lifecycle: created -> previewed/applied -> updated/deactivated/deleted
|
|
- Key Fields:
|
|
- `match_field` :: text :: field to inspect
|
|
- `pattern` :: text :: match pattern
|
|
- `match_type` :: text :: contains/equals/regex
|
|
- `category` / `subcategory` :: text :: classification target
|
|
- `priority` :: integer :: deterministic ordering
|
|
- `amount_min`, `amount_max`, `day_of_month` :: integer nullable :: optional constraints
|
|
- `person`, `is_fixed`, `confidence`, `memo`, `active`
|
|
- Relationships:
|
|
- Applies to Transaction rows.
|
|
- Should target valid or intentional category/subcategory labels.
|
|
- State Rules:
|
|
- Preview should precede broad application when changing classification behavior.
|
|
- More specific/high-priority rules should avoid accidentally overriding unrelated evidence.
|
|
|
|
## Entity: ImportBatch
|
|
- Source of Truth: `import_batches`
|
|
- Purpose: Tracks grouped imports for audit and rollback.
|
|
- Lifecycle: previewed -> imported -> optionally rolled back
|
|
- Key Fields:
|
|
- `id` :: text :: import batch identifier
|
|
- `source` :: text :: source kind
|
|
- `file_path` / source metadata where stored
|
|
- `inserted_count`, `skipped_duplicate_count`, `created_at`, `rolled_back_at`
|
|
- Relationships:
|
|
- Transaction rows reference `import_batch_id`.
|
|
- State Rules:
|
|
- Rollback should soft-delete by default.
|
|
- Duplicate imports with `skip_duplicates=True` may insert zero rows; that is not automatically an error.
|
|
|
|
## Entity: Budget
|
|
- Source of Truth: budget table/service functions
|
|
- Purpose: Monthly category/subcategory/person budget target.
|
|
- Lifecycle: created/updated -> compared against actual spending
|
|
- Key Fields:
|
|
- `month`, `category`, `subcategory`, `person`, `amount`, `currency`, `memo`
|
|
- Relationships:
|
|
- Compared against Transaction aggregates by report functions.
|
|
|
|
## Entity: LedgerBackupArtifact
|
|
- Source of Truth: filesystem under `/root/.local/share/jarca/backups/ledger/` by default
|
|
- Purpose: Timestamped SQLite backup artifact used for operational recovery and validation smoke checks.
|
|
- Lifecycle: created -> listed/status-checked -> retained/pruned by policy -> optionally restored by script/runbook after approval
|
|
- Key Evidence Fields:
|
|
- `path` :: text :: backup file path outside repository
|
|
- `size_bytes` :: integer :: file size metadata
|
|
- `mtime` :: text :: filesystem modification time
|
|
- `sha256` :: text :: file checksum
|
|
- `integrity_check` :: text :: SQLite integrity result
|
|
- `table_counts` / `aggregate_totals` :: metadata-only validation evidence
|
|
- State Rules:
|
|
- Keep backups from the most recent 30 days or newest 20 files.
|
|
- Backup artifacts and validation DB copies must not be committed to git.
|
|
- Restore execution is not a persisted MCP operation and requires script/runbook approval controls.
|
|
|
|
## Consistency Rules
|
|
- Actual cashflow reports include only categories whose `cashflow_kind` represents actual income or expense according to report semantics.
|
|
- Account movement summaries should be separate from actual household income/expense summaries.
|
|
- Cross-account auto-matching requires same date, same amount, opposite direction, and compatible source/owner evidence.
|
|
- External counterparty securities transfers are review items unless matched or explicitly confirmed.
|
|
- Import evidence fields are retained for audit and future correction.
|
|
- DB corrections should be narrow and memo-tagged.
|
|
- Dashboard/MCP asset and net-worth reports use a shared valuation helper: account-backed items from `accounts.last_balance` plus non-transaction items from `manual_assets`.
|
|
- Net worth is asset buckets (`cash`, `investment`, `deposit`, `real_estate`, `other`) minus absolute `loan` liabilities; missing valuations are excluded and reported, never inferred from transactions.
|
|
|
|
## Persistence Notes
|
|
- Schema changes should be additive/idempotent unless a destructive migration is explicitly approved and backed up.
|
|
- Operational backup/status evidence may include only path, size, mtime, checksum, integrity, row counts, and aggregate totals.
|
|
- Validation DB copies should live outside the repository and should be selected explicitly via `JARCA_LEDGER_DB_PATH` when used.
|
|
- Passwords for encrypted imports are runtime-only inputs and are not part of the persisted model.
|
|
- Raw payloads may contain sensitive financial evidence and should not be committed to git.
|
|
|
|
## Current Gaps / Planned Changes
|
|
- Formal schema migration documentation should be added before larger DB changes.
|
|
- Some UI workflows need final E2E verification against real rows.
|
|
- Statement-unavailable account handling is tracked by REQ-003/BAT-003; future work may add a dedicated reconciliation workbench and persistent review-decision queue.
|
|
- BAT-009 implements manual asset CRUD mutation and month-end snapshot preview/close/correction service/MCP/dashboard workflow. Future work may add automatic market/real-estate valuation or scheduled month-end close.
|
|
|
|
## Change Log
|
|
- 2026-06-26 22:24 KST: Created by `bootstrap-baseline` from repository observation.
|
|
- 2026-06-27 10:17 KST: BAT-002/REQ-002 기준으로 LedgerBackupArtifact와 metadata-only evidence 정책 추가.
|
|
- 2026-06-29 KST: REQ-003/BAT-003 기준으로 `accounts.statement_status`와 수동 잔액대조 preview 모델 추가.
|
|
- 2026-06-29 KST: REQ-005/BAT-005 기준으로 `accounts.liquidity_bucket`, `last_balance` 기반 자산 유동성/부채/순자산 규칙 추가.
|
|
- 2026-06-30 KST: REQ-009/REQ-010/BAT-008 기준으로 `manual_assets`, `asset_snapshots`, 권위 소스(`accounts.last_balance` + `manual_assets`), 순자산 산식/미평가 제외 정책 추가.
|
|
- 2026-07-01 KST: REQ-011/REQ-012/BAT-009 기준으로 manual asset CRUD, snapshot preview/close, append-only correction metadata, latest-run read policy 추가.
|