Implement BAT-009 manual asset CRUD and snapshot close

2026-07-01 10:55:34 +09:00
parent beddff7661
commit 02380a88ab
24 changed files with 1129 additions and 24 deletions
@@ -0,0 +1,40 @@
+# 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.
@@ -0,0 +1,47 @@
+# BAT-009 Implementation
+
+## Plan summary
+
+BAT-009 extends the BAT-008 valuation/read foundation into a full write workflow: manual asset CRUD, month-end snapshot preview/close/correction, mutation MCP contracts, operator dashboard UX, and baseline doc alignment while preserving shared valuation rules and safe fallback behavior.
+
+## Changed files
+
+- `jarca_ledger_mcp/db.py`
+- `jarca_ledger_mcp/service.py`
+- `jarca_ledger_mcp/server.py`
+- `dashboard/app.py`
+- `tests/test_asset_snapshots.py`
+- `tests/test_contract_regression.py`
+- `tests/test_dashboard_app.py`
+- `tests/test_ledger_categories.py`
+- `tests/test_service.py`
+- `tests/contract_snapshots/response_contract_v1_0.json`
+- `docs/data-model.md`
+- `docs/interface-contract.md`
+- `docs/discovery/dcy-009_20260701_manual-asset-crud-month-end-snapshot-close-workflow.md`
+- `docs/srs/Data/req-011_manual-asset-crud-month-end-snapshot-write-model.md`
+- `docs/srs/Interface/req-012_manual-asset-crud-snapshot-close-mcp-and-operator-dashboard-alignment.md`
+- `docs/srs/index.md`
+- `docs/batches/index.md`
+- `docs/batches/bat-009_20260701_manual-asset-crud-snapshot-close/index.md`
+- `docs/batches/bat-009_20260701_manual-asset-crud-snapshot-close/verification.md`
+
+## Execution log
+
+- 2026-07-01 09:03 KST: BAT-009 standard batch scaffold created from approved REQ-011/REQ-012.
+- 2026-07-01 10:52 KST: `manual_assets` write lifecycle(create/update/deactivate), `asset_snapshots` close/correction metadata, latest-run snapshot read selection, mutation MCP 5종, 대시보드 `자산/마감` 페이지, contract snapshot/test, baseline docs 정렬을 반영했다.
+- 2026-07-01 10:52 KST: stale schema-version expectations(`8`/`9`)을 current schema version `10`에 맞게 `tests/test_ledger_categories.py`, `tests/test_service.py`에서 정렬했다.
+
+## Validation
+
+- `python3 -m py_compile jarca_ledger_mcp/*.py dashboard/app.py` → PASS
+- `python3 -m pytest tests/test_asset_snapshots.py tests/test_contract_regression.py tests/test_dashboard_app.py -q` → PASS (`12 passed`)
+- `python3 -m pytest -q` → PASS (`42 passed, 4 skipped`)
+- `hermes mcp test jarca-ledger` → PASS (`Connected`, `Tools discovered: 56`)
+- Browser smoke: Streamlit app on `http://127.0.0.1:18501/?page=자산/마감` rendered the new page with manual asset CRUD section and snapshot preview/close section; browser console JS errors 없음.
+
+## Remaining risks / follow-up notes
+
+- Correction metadata shape must remain compatible with existing read helpers and historical snapshots.
+- Dashboard UX should not imply production-safe automation; this batch is still synthetic-evidence only.
+- Automatic valuation feeds and scheduled month-end close remain explicitly out of scope for BAT-009.
@@ -0,0 +1,36 @@
+# BAT-009 Manual asset CRUD / snapshot close
+
+- Profile: standard
+- Status: release-candidate
+- Included REQ: REQ-011, REQ-012
+- Discovery: dcy-009
+- Owner: 렛저장인
+- Date (KST): 2026-07-01
+
+## 목표
+
+REQ-011/REQ-012에 따라 `manual_assets` write lifecycle, month-end snapshot preview/close, append-only correction policy, mutation MCP, operator dashboard UX, source/is_closed 표기 정렬을 구현한다. 동시에 기존 BAT-008 read model/REQ-005 dashboard safety fallback/dcy-007 contract regression을 깨지 않도록 write/read 일관성을 유지한다.
+
+## 산출물
+
+- `manual_assets` create/update/deactivate write support and validation
+- snapshot preview/close/correction service APIs and additive persistence metadata
+- mutation MCP tools/contracts: manual asset CRUD, snapshot preview, snapshot close
+- `dashboard/app.py` operator UX for manual asset management and month-end close preview/execute
+- regression tests for write/read consistency, correction policy, contract envelope, dashboard fallback
+- `docs/data-model.md`, `docs/interface-contract.md`, `docs/project-structure.md`, `docs/runtime-flows.md` baseline write-workflow updates
+- BAT-009 planning/design/implementation/verification documents and synthetic-only evidence
+
+## 범위 제한
+
+- 외부 시세/부동산 자동 평가 연동
+- 월말 자동 스케줄링/cron close
+- 투자 조언/리밸런싱/세금/수익률 계산
+- production ledger DB 실데이터 기반 evidence
+
+## 문서
+
+- `planning.md`: delivery plan, dependency, risks, validation entry criteria
+- `design.md`: write-model/correction/MCP/UI design
+- `implementation.md`: changed files, execution log, validation commands
+- `verification.md`: AC mapping, PASS/FAIL, REQ Implemented decision
@@ -0,0 +1,37 @@
+# BAT-009 Planning
+
+## Scope
+
+- Implement REQ-011: manual asset create/update/deactivate write model, snapshot preview/close persistence, append-only correction policy.
+- Implement REQ-012: mutation MCP tools/contracts, operator dashboard UX, source/is_closed_snapshot alignment.
+- Preserve REQ-005/REQ-010 safe fallback when manual asset write paths are unused or new write metadata is absent.
+- Use synthetic/temp data only for tests and verification evidence.
+
+## Dependencies
+
+- dcy-009 confirmed Discovery and approved REQ-011/REQ-012.
+- Existing BAT-008 read model in `jarca_ledger_mcp/db.py`, `service.py`, `server.py`, `dashboard/app.py`.
+- Existing dcy-007 response contract / `tests/test_contract_regression.py` expectations.
+- Additive/idempotent SQLite migration discipline and dcy-002 backup/approval safety policy.
+
+## Work plan
+
+1. Create BAT-009 standard batch docs and register entry.
+2. Extend schema/service write path for manual asset update/deactivate and snapshot preview/close/correction metadata.
+3. Add mutation MCP endpoints/contracts for manual asset CRUD and snapshot preview/close.
+4. Add dashboard operator flows for manual asset management and month-end close preview/execute.
+5. Update baseline docs (`docs/data-model.md`, `docs/interface-contract.md`, `docs/project-structure.md`, `docs/runtime-flows.md`).
+6. Run narrow validation first (targeted tests / contract regression / synthetic service probe / dashboard smoke).
+7. If evidence satisfies ACs, move BAT-009 to release-candidate and REQ-011/REQ-012 to Implemented.
+
+## Design Gate
+
+- Result: standard batch 유지.
+- Reason: schema, service, MCP contract, dashboard UX, correction policy, baseline docs를 함께 바꾸므로 design/verification depth가 필요하다.
+
+## Risks and mitigations
+
+- Correction semantics drifting from read model: mitigate by explicit correction metadata, latest-valid-close selection tests, and read-after-close probes.
+- Mutation contract drift vs dcy-007: mitigate by extending contract regression snapshots/tests for new tools.
+- Dashboard operator flow accidentally mutating without preview clarity: mitigate by separate preview/close actions and source/is_closed labeling.
+- Hard delete breaking historical traceability: mitigate by soft delete default plus tests asserting deactivated items do not erase prior snapshots.
@@ -0,0 +1,48 @@
+# BAT-009 Verification
+
+## Verification summary
+
+Status: PASS
+
+Evidence was collected against synthetic/temp data only. No production ledger DB mutation or real financial files were used.
+
+## Acceptance criteria mapping
+
+### REQ-011
+
+- AC-1: PASS — `manual_assets` create/update/deactivate write path and additive schema migration/correction columns implemented in `db.py`/`service.py`; full pytest PASS confirms existing/new DB initialization succeeds.
+- AC-2: PASS — `preview_asset_snapshot_close` exists and targeted tests verify side-effect-free totals/warnings behavior.
+- AC-3: PASS — `close_asset_snapshot` writes basis-date authority-source rows with close metadata and is covered by `tests/test_asset_snapshots.py`.
+- AC-4: PASS — same-date re-close requires correction reasoning and appends correction rows via `snapshot_run_id` / `correction_of_run_id` / `is_correction`; targeted tests verify append-only behavior.
+- AC-5: PASS — latest-run snapshot read selection plus shared valuation helpers keep read model/report consistency; targeted + full pytest PASS.
+- AC-6: PASS — `docs/data-model.md` updated for write lifecycle, close/correction metadata, and latest-run read policy.
+
+### REQ-012
+
+- AC-1: PASS — MCP tools `create_manual_asset`, `update_manual_asset`, `deactivate_manual_asset` are exposed in `server.py`; `hermes mcp test jarca-ledger` discovered all 56 tools including BAT-009 additions.
+- AC-2: PASS — `preview_asset_snapshot_close` MCP/service returns preview totals, warnings, `source='live_authority'`, `is_closed_snapshot=false`; targeted tests PASS.
+- AC-3: PASS — `close_asset_snapshot` MCP/service returns close metadata and correction markers with `source='snapshot'`, `is_closed_snapshot=true`; targeted tests PASS.
+- AC-4: PASS — `dashboard/app.py` adds `자산/마감` page with manual asset add/update/deactivate and snapshot preview/close UX; browser smoke rendered the page successfully.
+- AC-5: PASS — browser/render + targeted tests confirm `source`/`is_closed_snapshot` aligned across preview/close/report flows and dashboard messaging.
+- AC-6: PASS — `tests/test_contract_regression.py` and `tests/contract_snapshots/response_contract_v1_0.json` updated; `docs/interface-contract.md` updated; targeted/full pytest PASS.
+
+## Requirement state decision
+
+- REQ-011: Implemented.
+- REQ-012: Implemented.
+
+## Validation evidence
+
+- `python3 -m py_compile jarca_ledger_mcp/*.py dashboard/app.py` → PASS
+- `python3 -m pytest tests/test_asset_snapshots.py tests/test_contract_regression.py tests/test_dashboard_app.py -q` → PASS (`12 passed`)
+- `python3 -m pytest -q` → PASS (`42 passed, 4 skipped`)
+- `hermes mcp test jarca-ledger` → PASS (`Connected`, `Tools discovered: 56`)
+- Browser smoke on Streamlit `자산/마감` page → PASS, JS errors 없음
+
+## Remaining issues
+
+### Hard blockers
+- None.
+
+### Non-blocking follow-up
+- Automatic valuation feeds and scheduled month-end close remain explicitly out of scope for BAT-009.
@@ -16,3 +16,4 @@
 | BAT-006 | standard | release-candidate | REQ-006 | dcy-006 | [bat-006_20260630_pytest-apptest-smoke-ci-automation](bat-006_20260630_pytest-apptest-smoke-ci-automation/) |
 | BAT-007 | standard | release-candidate | REQ-007, REQ-008 | dcy-007 | [bat-007_20260630_mcp-response-contract-ci-versioning](bat-007_20260630_mcp-response-contract-ci-versioning/) |
 | BAT-008 | standard | release-candidate | REQ-009, REQ-010 | dcy-008 | [bat-008_20260630_asset-snapshots-manual-assets-read-mcp](bat-008_20260630_asset-snapshots-manual-assets-read-mcp/) |
+| BAT-009 | standard | release-candidate | REQ-011, REQ-012 | dcy-009 | [bat-009_20260701_manual-asset-crud-snapshot-close](bat-009_20260701_manual-asset-crud-snapshot-close/) |