jarca-ledger-mcp/docs/srs/Data/req-011_manual-asset-crud-month-end-snapshot-write-model.md

REQ-011 Manual asset CRUD / month-end snapshot write model

• Status: Implemented
• Type: Data
• Priority: High
• Owner: 렛저장인
• Source Discovery: docs/discovery/dcy-009_20260701_manual-asset-crud-month-end-snapshot-close-workflow.md
• Batch: BAT-009
• Created At (KST): 2026-07-01 09:00 KST
• Approved At (KST): 2026-07-01 09:02 KST
• Implemented At (KST): 2026-07-01 10:52 KST

1. 배경

REQ-009/REQ-010은 manual_assets, asset_snapshots, 조회성 MCP, 대시보드 정렬까지 구현했지만 쓰기 경로는 의도적으로 제외했다. 현재는 read model과 평가 helper는 존재하지만, 수기 자산을 생성·수정·비활성 처리하거나 특정 기준일 자산 상태를 마감해 asset_snapshots에 확정하는 1급 운영 경로가 없다. dcy-009 confirmed Discovery에 따라 write model, 재마감 정책, 이력 보존 규칙을 구현 가능한 데이터/서비스 요구사항으로 고정해야 한다.

2. Intent

수기 자산 CRUD와 월말 마감 스냅샷 생성을 임시 수기 절차가 아니라 명시적 저장 계층/서비스 계층 기능으로 정립한다. 이 REQ의 목적은 manual_assets write lifecycle, preview 입력 모델, asset_snapshots append-only correction 정책, soft delete 원칙, 백업/승인 연계 안전장치를 구현 가능한 데이터 책임으로 고정하는 것이다.

3. 범위

In Scope

• manual_assets의 생성/수정/비활성(soft delete) write model을 정의한다.
• 특정 basis_date 기준 live authority(accounts.last_balance + 활성 manual_assets)를 스냅샷 행으로 고정하는 month-end snapshot close write path를 정의한다.
• snapshot preview를 위한 집계/검증 데이터 모델과 warning shape를 정의한다.
• 동일 basis_date 재마감 시 append-only + 정정 행 추가 정책과 중복/정정 메타데이터 규칙을 정의한다.
• dcy-002 운영 안전장치와 정합한 백업/승인 연계 규칙을 정의한다.
• docs/data-model.md와 필요 baseline 문서에 write model 책임을 반영한다.

Out of Scope

• 외부 시세/부동산 자동 평가 연동.
• 월말 자동 스케줄링/cron 생성.
• read-only MCP 응답 shape 자체의 상세 설계(별도 Interface REQ에서 다룸).
• 투자 조언/리밸런싱/세금/수익률 계산.

4. Requirement

FR-1. Manual asset CRUD write lifecycle

• manual_assets는 create/update/deactivate 흐름을 지원해야 한다.
• 생성/수정 시 최소 필드 name, valuation_amount, valuation_date, liquidity_bucket, source_note를 검증해야 한다.
• 허용 liquidity_bucket 값은 cash, investment, deposit, real_estate, loan, other다.
• 삭제 기본 정책은 hard delete가 아니라 비활성/soft delete여야 한다.
• hard delete는 운영 복구가 불필요한 예외 정리 작업에 한해 별도 승인 하에서만 허용되어야 한다.

FR-2. Snapshot preview data model

• snapshot close 실행 전 preview는 해당 basis_date에 스냅샷될 계좌/수기 자산 항목 목록, 평가값, liquidity_bucket, source type, 합계, 경고를 계산할 수 있어야 한다.
• preview는 write side effect 없이 동작해야 한다.
• preview는 미평가/제외 항목, stale valuation, 중복 위험을 warning 형태로 드러낼 수 있어야 한다.

FR-3. Month-end snapshot close write path

• snapshot close는 특정 basis_date의 live authority를 항목 단위 asset_snapshots 행으로 고정해야 한다.
• close 시 각 행은 source_type, source_id, display_name, valuation_amount, liquidity_bucket, basis_date, close 근거 메모를 보존해야 한다.
• close 결과는 이후 read model이 동일 산식으로 재구성 가능한 형태여야 한다.

FR-4. Append-only correction policy

• 동일 basis_date 재마감 기본 정책은 overwrite가 아니라 append-only + 정정 행 추가여야 한다.
• 정정 실행은 기존 마감 행을 지우지 않고 correction 메타데이터(정정 사유, 정정 실행 시각, 정정 대상 basis_date)를 남겨야 한다.
• 정정 실행 전에는 dcy-002 기준 백업/승인 절차를 선행할 수 있어야 한다.
• read side는 최신 유효 마감 집합을 결정할 수 있도록 정정 계보를 추적할 수 있어야 한다.

FR-5. Valuation/rule consistency

• write path는 REQ-009/REQ-010이 확정한 권위 소스(accounts.last_balance + manual_assets)와 순자산 산식(자산성 버킷 합계 − loan, 미평가 제외)을 그대로 따라야 한다.
• write path가 생성한 snapshot과 read model의 보고 결과는 동일 basis_date에서 일치 검증 가능해야 한다.

FR-6. Baseline documentation alignment

• docs/data-model.md는 manual asset write lifecycle, soft delete semantics, correction metadata, snapshot close policy를 반영해야 한다.
• 필요 시 docs/runtime-flows.md, docs/project-structure.md는 preview → close → corrected-close 흐름과 write/read 책임 경계를 반영해야 한다.

5. Acceptance Criteria

• AC-1: 신규/기존 DB 모두에서 manual asset create/update/deactivate에 필요한 필드와 상태가 additive/idempotent하게 저장된다.
• AC-2: snapshot preview가 side effect 없이 항목 목록, bucket totals, total assets, total liabilities, net worth, warnings를 반환할 수 있다.
• AC-3: month-end snapshot close가 특정 basis_date의 authority source를 asset_snapshots에 항목 단위로 고정 저장한다.
• AC-4: 동일 basis_date 재마감은 overwrite 없이 correction append 정책으로 처리되고, 원본/정정 이력이 모두 보존된다.
• AC-5: manual asset soft delete와 snapshot correction이 있어도 REQ-009/REQ-010 read model은 동일 산식으로 일관된 결과를 낸다.
• AC-6: docs/data-model.md와 필요 baseline 문서가 본 REQ 범위를 반영한다.

6. Impacted Area

• jarca_ledger_mcp/db.py
• jarca_ledger_mcp/service.py
• tests/test_asset_snapshots.py
• 필요 시 tests/test_service.py
• docs/data-model.md
• 필요 시 docs/runtime-flows.md
• 필요 시 docs/project-structure.md

7. Notes

• 이 REQ는 write model, correction policy, persistence semantics를 다루므로 Data 타입으로 관리한다.
• MCP mutation contract와 operator UX는 REQ-012에서 다룬다.
• 월말 자동 스케줄링은 Discovery 결정에 따라 후속 범위로 유지한다.

8. Change Log

• 2026-07-01 09:00 KST: dcy-009 confirmed 범위를 바탕으로 Proposed 초안을 생성.
• 2026-07-01 09:02 KST: dcy-009 confirmed 결정사항(append-only correction, soft delete 기본, auto scheduling 후속)을 반영해 Approved로 전환.
• 2026-07-01 10:52 KST: BAT-009 구현, full pytest PASS, MCP tool discovery, browser smoke evidence를 근거로 Implemented로 전환.