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

5.7 KiB Raw Blame History