feat: implement asset snapshot and manual asset read model

2026-06-30 22:04:52 +09:00
parent 7fd1b45bd5
commit beddff7661
20 changed files with 1232 additions and 61 deletions
@@ -0,0 +1,40 @@
+# 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.