41 lines
2.1 KiB
Markdown
41 lines
2.1 KiB
Markdown
# 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.
|