jarca-ledger-mcp/docs/srs/Interface/req-010_asset-snapshot-net-worth-read-mcp-and-dashboard-alignment.md

# REQ-010 Asset snapshot/net worth read MCP and dashboard alignment

- Status: Implemented
- Type: Interface
- 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. 배경

자산 스냅샷/수기 자산/평가 체계가 데이터 모델로만 존재하면 대시보드와 MCP 소비자가 서로 다른 규칙으로 자산·순자산을 해석할 위험이 있다. dcy-008 confirmed Discovery는 기준일 자산 스냅샷 조회, 순자산 시계열 조회, 수기 자산 조회를 조회성 MCP 범위에 포함하고, dcy-005 대시보드 표시 경로와 동일한 산식·권위 소스를 사용하도록 요구한다.

## 2. Intent

자산 스냅샷과 순자산 평가 결과를 대시보드 내부 계산에만 가두지 않고, 조회성 MCP와 화면 표시가 같은 규칙·같은 설명 필드·같은 제외 정책을 따르도록 인터페이스 계약을 정렬한다. 이 REQ의 목적은 기준일 조회, 시계열 조회, 수기 자산 조회의 최소 응답 계약과 대시보드 정합성 의무를 구현 가능한 인터페이스 요구사항으로 고정하는 것이다.

## 3. 범위

### In Scope
- 기준일 자산 스냅샷 조회 MCP를 정의한다.
- 순자산 시계열 조회 MCP를 정의한다.
- 수기 자산 조회 MCP를 정의한다.
- 응답에 기준일/집계 구간, 권위 소스, `liquidity_bucket`, 산식 적용 기준, 포함/제외 항목 설명을 포함한다.
- 대시보드 자산/순자산 표시가 동일 권위 소스와 동일 산식을 사용하도록 정렬한다.
- `docs/interface-contract.md`, 필요 시 `docs/runtime-flows.md`, `docs/project-structure.md`를 갱신한다.

### Out of Scope
- 스냅샷 생성 mutation MCP.
- 수기 자산 생성/수정/삭제 mutation MCP.
- 외부 시세/부동산 자동 평가를 노출하는 인터페이스.
- 투자 조언/리밸런싱 추천 응답.

## 4. Requirement

### FR-1. Asset snapshot read MCP
- 기준일별 자산 스냅샷 조회 경로를 제공해야 한다.
- 응답은 최소한 기준일, 자산 버킷별 금액, 총부채, 순자산, 포함/제외 항목 요약을 설명할 수 있어야 한다.
- 응답은 어떤 권위 소스(`last_balance`, `manual_assets`, snapshot record)가 사용됐는지 추적 가능해야 한다.

### FR-2. Net worth timeseries read MCP
- 최근 N개월 또는 지정 구간 순자산 시계열 조회 경로를 제공해야 한다.
- 각 시점은 동일 산식(자산성 합계 − `loan`)과 동일 제외 정책을 적용해야 한다.
- 시계열 응답은 기준일 또는 구간 정의를 명확히 포함해야 한다.

### FR-3. Manual assets read MCP
- 수기 자산/부채 목록 또는 집계 조회 경로를 제공해야 한다.
- 응답은 항목명, 평가값, 기준일, `liquidity_bucket`, 출처 메모를 확인할 수 있어야 한다.
- 미평가 또는 오래된 평가 항목은 후속 UX/응답에서 경고 가능하도록 상태 정보를 제공할 수 있어야 한다.

### FR-4. Dashboard/MCP contract alignment
- `dashboard/app.py`의 자산 유동성/순자산 표시와 조회성 MCP 응답은 동일 권위 소스 우선순위와 동일 순자산 산식을 사용해야 한다.
- `REQ-005`의 기존 표시 경로와 충돌하지 않도록, 신규 모델이 비어 있는 경우 기존 안전 폴백을 유지해야 한다.
- 동일 데이터에 대해 대시보드와 MCP가 숫자/분류 규칙이 어긋나지 않도록 검증 가능해야 한다.

### FR-5. Baseline documentation alignment
- `docs/interface-contract.md`는 자산 스냅샷 조회, 순자산 시계열 조회, 수기 자산 조회의 최소 응답 계약을 반영해야 한다.
- `docs/runtime-flows.md`는 월말 스냅샷 생성 이후 조회성 MCP와 대시보드가 동일 데이터를 소비하는 흐름을 설명해야 한다.
- `docs/project-structure.md`는 `dashboard/app.py`, `jarca_ledger_mcp/service.py`, `jarca_ledger_mcp/server.py` 간 책임 경계를 반영해야 한다.

## 5. Acceptance Criteria

- AC-1: 기준일 자산 스냅샷 조회 MCP가 정의되고 기준일, 버킷별 금액, 총부채, 순자산, 포함/제외 항목을 반환할 수 있다.
- AC-2: 순자산 시계열 조회 MCP가 정의되고 지정 구간의 기준일별 순자산을 동일 산식으로 반환할 수 있다.
- AC-3: 수기 자산 조회 MCP가 정의되고 항목명, 평가값, 기준일, `liquidity_bucket`, 출처 메모를 반환할 수 있다.
- AC-4: 대시보드와 MCP가 동일 권위 소스/동일 산식/동일 제외 정책을 사용한다.
- AC-5: 신규 모델이 비어 있어도 기존 `REQ-005` 자산 표시 경로가 안전하게 폴백한다.
- AC-6: `docs/interface-contract.md`와 필요 baseline 문서가 본 REQ 범위를 반영한다.

## 6. Impacted Area

- `jarca_ledger_mcp/server.py`
- `jarca_ledger_mcp/service.py`
- `dashboard/app.py`
- `docs/interface-contract.md`
- 필요 시 `docs/runtime-flows.md`
- 필요 시 `docs/project-structure.md`

## 7. Notes

- 이 REQ는 조회성 MCP와 대시보드 표시 계약을 다루므로 `Interface` 타입으로 관리한다.
- mutation MCP는 본 REQ에서 제외하며 후속 Discovery/REQ로 분리한다.
- 데이터 저장 구조와 월말 수동 스냅샷 정책의 구현 책임은 `REQ-009`를 선행 입력으로 사용한다.

## 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로 전환.