Files
jarca-ledger-mcp/docs/batches/bat-009_20260701_manual-asset-crud-snapshot-close/design.md
T

2.1 KiB

BAT-009 Design

Schema and persistence design

  • Reuse manual_assets / asset_snapshots tables from BAT-008 and extend them only additively for write workflow metadata as needed.
  • manual_assets write lifecycle must support create/update/deactivate without destroying prior snapshot traceability.
  • asset_snapshots remains append-only; correction runs add new rows/metadata rather than overwriting prior close rows.

Write workflow design

  • Service layer should expose:
    • manual asset create/update/deactivate helpers
    • snapshot preview helper that returns write-free totals/warnings
    • snapshot close helper that materializes authority-source rows for one basis_date
    • correction helper/metadata so same-date re-close is represented as a correction append, not overwrite
  • Close path must preserve source_type, source_id, display name, valuation amount, liquidity_bucket, memo/reason metadata.

MCP and contract design

  • server.py should expose mutation MCP tools for manual asset CRUD and snapshot preview/close.
  • Success/error envelopes must match dcy-007 contract conventions.
  • Preview responses expose source='live_authority', is_closed_snapshot=false; close responses expose source='snapshot', is_closed_snapshot=true.
  • Correction close responses must identify that a correction run occurred.

Dashboard/operator UX design

  • dashboard/app.py should provide manual asset create/edit/deactivate flows and a month-end close panel.
  • Preview and close actions must be visually distinct.
  • Screen text should clarify whether displayed values are live authority estimates or closed snapshot values.
  • Correction history should be explainable at least through summary metadata/messages.

Verification design

  • Add targeted regression tests for:
    • manual asset update/deactivate lifecycle
    • snapshot preview side-effect freedom
    • append-only correction behavior for same basis_date
    • mutation MCP contract envelope coverage
    • dashboard/shared-helper fallback and source labeling
  • Prefer temp DB + synthetic data + local Streamlit smoke only.