41 lines
1.9 KiB
Markdown
41 lines
1.9 KiB
Markdown
# BAT-008 Design
|
|
|
|
## Schema and persistence design
|
|
|
|
- Add `manual_assets` as a first-class table for non-transaction-derived assets/liabilities.
|
|
- Add `asset_snapshots` as an append-only history table keyed by basis date plus evaluated item identity.
|
|
- Migrations remain additive/idempotent; existing ledger/account flows must continue to operate when both tables are empty.
|
|
|
|
## Authority-source and valuation design
|
|
|
|
- Account-backed assets use `accounts.last_balance` as the live authority source.
|
|
- Non-transaction assets/liabilities use `manual_assets` as the live authority source.
|
|
- `asset_snapshots` is a historical record layer, not a competing primary input source.
|
|
- Net worth formula remains: asset buckets (`cash`, `investment`, `deposit`, `real_estate`, `other`) minus `loan`; missing valuations are excluded, not inferred.
|
|
|
|
## Read model design
|
|
|
|
- Service layer should expose:
|
|
- manual assets list/report helpers
|
|
- basis-date asset snapshot read helpers
|
|
- net-worth timeseries helpers
|
|
- shared valuation/fallback helpers consumed by both MCP and dashboard
|
|
- Snapshot read responses must expose basis date, bucket totals, liabilities, net worth, and inclusion/exclusion explanation fields.
|
|
- Manual assets read responses must expose item name, value, basis date, `liquidity_bucket`, and memo/source metadata.
|
|
|
|
## Dashboard alignment design
|
|
|
|
- `dashboard/app.py` should consume the same valuation helpers as the MCP read tools.
|
|
- If no manual assets/snapshots exist, dashboard behavior must safely fall back to REQ-005 account-based display.
|
|
- Excluded/unvalued items should be explainable instead of silently counted.
|
|
|
|
## Verification design
|
|
|
|
- Add targeted regression tests for:
|
|
- additive migration creation
|
|
- manual asset persistence and retrieval
|
|
- snapshot accumulation/read behavior
|
|
- net-worth formula / exclusion policy
|
|
- dashboard/MCP shared fallback behavior
|
|
- Prefer synthetic SQLite fixtures and temp DBs only.
|