jarca-ledger-mcp/docs/srs/Data/req-009_asset-snapshot-manual-assets-valuation-model.md

REQ-009 Asset snapshot/manual assets valuation model

• Status: Implemented
• Type: Data
• Priority: High
• Owner: 렛저장인
• Source Discovery: docs/discovery/dcy-008_20260630_asset-snapshot-manual-valuation-system.md
• Batch: BAT-008
• Created At (KST): 2026-06-30 21:17 KST
• Approved At (KST): 2026-06-30 21:24 KST
• Implemented At (KST): 2026-06-30 22:05 KST

1. 배경

REQ-005는 accounts.liquidity_bucket + last_balance 기반 자산 유동성/순자산 표시를 구현했지만, 시점별 자산 평가 이력과 비거래 자산/부채의 독립 모델은 의도적으로 제외했다. dcy-008 confirmed Discovery에 따라 자산 스냅샷 이력과 수기 자산 모델을 별도 테이블로 도입하고, 계좌 last_balance + 수기 자산 보강을 단일 평가 권위 소스로 정립해 기준일별 순자산 재현과 후속 MCP 조회 기능의 데이터 기반을 마련해야 한다.

2. Intent

자산 평가 모델을 계좌 한 줄의 최신 값에서 벗어나, 기준일별 스냅샷과 비거래 자산/부채의 명시적 엔티티로 분리한다. 이 REQ의 목적은 asset_snapshots/manual_assets 데이터 모델, 순자산 산식, 권위 소스 우선순위, 월말 수동 스냅샷 정책을 구현 가능한 저장 계층 요구사항으로 고정하는 것이다.

3. 범위

In Scope

• asset_snapshots와 manual_assets를 별도 additive/idempotent 테이블로 도입한다.
• 비거래 자산/부채의 필수 속성(이름, 평가값, 기준일, liquidity_bucket, 출처 메모)을 정의한다.
• 자산 스냅샷의 필수 속성(기준일, 평가 대상, 평가 금액, liquidity_bucket, 출처/메모)을 정의한다.
• 자산성 합계 − loan 차감, 미평가 제외 규칙을 저장/집계 계층 기준으로 고정한다.
• 월말 수동 스냅샷 생성 정책과 항목 단위 수용 구조를 반영한다.
• docs/data-model.md에 위 모델과 권위 소스 규칙을 반영한다.

Out of Scope

• 외부 시세/부동산 자동 평가 연동.
• 실시간 자동 스냅샷 생성 스케줄러.
• 수익률/세금/리밸런싱 계산.
• 조회성 MCP 응답 shape 정의 자체(별도 Interface REQ에서 다룸).

4. Requirement

FR-1. Manual assets data model

• manual_assets는 거래로 산출되지 않는 비거래 자산/부채를 저장해야 한다.
• 각 항목은 최소한 이름, 자산/부채 구분 또는 liquidity_bucket, 평가값, 기준일, 출처 메모를 가져야 한다.
• 허용 liquidity_bucket 값은 cash, investment, deposit, real_estate, loan, other다.
• 사용자 입력 기반 평가값이 권위 소스가 되는 항목은 계좌 모델과 혼합 저장하지 않고 별도 엔티티로 유지해야 한다.

FR-2. Asset snapshots history model

• asset_snapshots는 기준일 시점의 자산 평가 결과를 누적 저장해야 한다.
• 스냅샷은 계좌와 수기 자산 항목을 모두 담을 수 있는 항목 단위 구조를 수용해야 한다.
• 기존 스냅샷은 파괴적으로 덮어쓰지 않고 신규 행으로 누적해야 한다.
• 각 행은 최소한 기준일, 평가 대상 식별자, 평가 금액, liquidity_bucket, 평가 출처/메모를 보존해야 한다.

FR-3. Valuation authority source rule

• 계좌 기반 자산은 기존 accounts.last_balance를 기본 평가 권위 소스로 사용해야 한다.
• 거래로 산출되지 않는 비거래 자산/부채는 manual_assets를 권위 소스로 사용해야 한다.
• 스냅샷은 위 권위 소스를 기준일 시점에 고정한 기록층이어야 하며, 실시간 권위 소스를 대체하는 별도 1차 입력원이 되어서는 안 된다.
• 동일 자산이 중복 집계되지 않도록 계좌 항목과 수기 자산 항목의 책임 경계를 정의해야 한다.

FR-4. Net worth formula and exclusion policy

• 순자산은 자산성 버킷(cash, investment, deposit, real_estate, other) 합계에서 loan 부채를 차감해 계산해야 한다.
• 평가값이 없는 항목은 임의 거래 합계로 추정하지 않고 제외해야 한다.
• 제외된 항목은 후속 화면/응답 계층에서 설명 가능하도록 상태 또는 근거를 남길 수 있어야 한다.

FR-5. Manual month-end snapshot policy

• 초기 운영 정책은 월말 수동 스냅샷 생성이어야 한다.
• 스냅샷 생성 흐름은 월말 마감 시점에 계좌 last_balance와 수기 자산 평가값을 함께 고정할 수 있어야 한다.
• 자동 생성/스케줄링은 후속 범위로 남긴다.

FR-6. Baseline documentation alignment

• docs/data-model.md는 asset_snapshots, manual_assets, 권위 소스 우선순위, 순자산 산식을 반영해야 한다.
• 필요 시 docs/project-structure.md와 docs/runtime-flows.md에 데이터 모델 책임과 월말 스냅샷 흐름을 참조 수준으로 반영해야 한다.

5. Acceptance Criteria

• AC-1: 신규 DB/기존 DB 모두에서 asset_snapshots, manual_assets가 additive/idempotent migration으로 생성된다.
• AC-2: manual_assets는 이름, 평가값, 기준일, liquidity_bucket, 출처 메모를 저장할 수 있다.
• AC-3: asset_snapshots는 기준일, 평가 대상, 평가 금액, liquidity_bucket, 출처/메모를 누적 저장할 수 있다.
• AC-4: 계좌 기반 자산은 last_balance, 비거래 자산/부채는 manual_assets를 권위 소스로 사용하는 규칙이 구현/문서에 반영된다.
• AC-5: 순자산 계산이 자산성 합계 − loan 차감, 미평가 제외 규칙을 따른다.
• AC-6: 빈 신규 테이블 상태에서도 기존 REQ-005 대시보드 흐름이 깨지지 않는다.
• AC-7: docs/data-model.md와 필요 baseline 문서가 본 REQ 범위를 반영한다.

6. Impacted Area

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

7. Notes

• 이 REQ는 저장 구조/권위 소스/순자산 산식 같은 데이터 모델 책임을 다루므로 Data 타입으로 관리한다.
• 조회성 MCP 응답 계약과 대시보드 노출 shape는 REQ-010에서 다룬다.
• 실제 초기 수기 자산 목록은 구현 전 사용자가 입력해야 하며, 본 REQ는 그 입력 포맷과 저장 규칙을 다루는 수준으로 제한한다.

8. Change Log

• 2026-06-30 21:17 KST: dcy-008 confirmed 범위를 바탕으로 Proposed 초안을 생성.
• 2026-06-30 21:24 KST: dcy-008 confirmed 결정사항과 Acceptance Criteria를 재검토해 Approved로 전환.
• 2026-06-30 22:05 KST: BAT-008 구현·검증 evidence와 jarcaledgerqc PASS gate를 근거로 Implemented로 전환.