jarca-ledger-mcp/docs/srs/Interface/req-005_dashboard-operations-hub-liquidity-monthly-cashflow.md

REQ-005 Dashboard operations hub/liquidity/monthly cashflow

• Status: Approved
• Type: Interface
• Priority: High
• Owner: 렛저장인
• Source Discovery: docs/discovery/dcy-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow.md
• Batch: BAT-005
• Created At (KST): 2026-06-29
• Approved At (KST): 2026-06-29 21:08 KST

1. 배경

현재 Streamlit 대시보드 첫 화면은 전체 기간 누적 현금흐름과 계좌 입출금 중심으로 구성되어 있어, 운영자가 월중에 필요한 "이번 달 수입/지출 현황", "현재 자산 유동성", "미처리 운영 경고"를 한 화면에서 즉시 판단하기 어렵다. dcy-005 confirmed Discovery에 따라 대시보드 첫 화면을 운영 허브로 재정의하고, 계좌 단위 liquidity_bucket 축을 도입해 자산 유동성/구성/순자산 계산을 일관되게 제공한다.

2. 범위

In Scope

• page_overview를 다음 우선순위 섹션으로 재구성한다: ① 이번 달 수입/지출 현황 ② 자산 유동성 현황 ③ 자산 구성 ④ 지출 구조/예산 ⑤ 운영 경고.
• 이번 달 수입/지출 현황은 KST 현재 월의 transaction_date 기준으로 실제 수입, 실제 지출, 순현금흐름, 저축률을 표시한다.
• 자산 유동성 현황은 계좌 단위 accounts.liquidity_bucket 값을 기준으로 cash, investment, deposit, real_estate, loan, other 버킷별 금액과 비율을 표시한다.
• accounts.liquidity_bucket은 additive/idempotent schema migration으로 도입하고, 미지정 계좌는 other로 폴백한다.
• 비거래 자산/부채는 초기 구현에서 ledger_accounts 항목의 last_balance, last_synced_at, memo를 수동 입력 소스로 사용한다.
• 운영 경고 섹션은 미분류 거래, 확인필요 큐, 잔액대조 필요 계좌, 최근 백업/import 상태를 한 화면에 노출하고 상세 화면/절차로 이동할 단서를 제공한다.
• docs/data-model.md, docs/project-structure.md, docs/runtime-flows.md, 필요 시 docs/interface-contract.md에 대시보드 운영 허브와 liquidity_bucket 흐름을 반영한다.

Out of Scope

• 다계좌 실시간 잔액 연동, 외부 시세/투자 평가액 자동 연동.
• 카드 미결제금, 보험 해지환급금, 자동 시세 연동 자산 반영.
• asset_snapshots, manual_assets 같은 별도 자산 평가 테이블 신설.
• 거래/카테고리 단위 liquidity_bucket override.
• 사용자 정의 회계 월 마감 또는 posted_date 기준 월간 현금흐름 전환.

3. 기능 요구사항

FR-1. 이번 달 수입/지출 현황

• 대시보드 최상단 1순위 섹션은 "이번 달 수입/지출 현황"이어야 한다.
• 기본 기간은 KST 현재 월의 시작일부터 종료일까지이며, 집계 기준일은 transactions.transaction_date다.
• 실제 수입/지출 판정은 기존 ledger_categories.cashflow_kind 기준을 재사용한다.
• 표시 지표는 실제 수입, 실제 지출, 순현금흐름, 저축률을 포함해야 한다.
• 저축률은 기존 정의와 동일하게 순현금흐름 ÷ 실제 수입을 당월 범위에 적용한다. 실제 수입이 0인 경우에는 나누기 오류 없이 안전한 대체 표시를 제공한다.

FR-2. 자산 유동성 분류 축

• accounts.liquidity_bucket은 TEXT NOT NULL DEFAULT 'other' 성격의 additive 필드로 도입해야 한다.
• 허용값은 cash, investment, deposit, real_estate, loan, other다.
• 서비스 계층은 허용값 외 입력을 검증 오류로 거부해야 한다.
• 계좌 생성, 계좌 목록, 계좌 수정 흐름에서 liquidity_bucket을 사용할 수 있어야 한다.
• 기존 계좌 또는 미지정 계좌는 other로 안전하게 폴백해야 한다.

FR-3. 자산 유동성/구성/순자산 계산

• 자산 유동성 현황은 accounts.liquidity_bucket을 단일 권위 소스로 사용한다.
• 버킷별 금액은 각 계좌의 최신 last_balance를 우선 사용한다. last_balance가 없는 계좌는 계산에서 제외하거나 별도 미입력 경고로 표시하되, 임의의 거래 합계로 자산 평가액을 추정하지 않는다.
• 자산 구성 비율의 분모는 cash, investment, deposit, real_estate, other 버킷 합계이며, loan은 제외한다.
• 총부채는 loan 버킷 합계로 표시하고, 순자산은 대출을 제외한 자산 합계에서 총부채를 차감해 계산한다.
• 부동산, 예적금, 대출 등 비거래 자산/부채는 last_balance를 현재 평가액/잔액, last_synced_at을 기준일, memo를 출처 메모로 사용한다.

FR-4. 운영 허브 화면 구성

• page_overview는 다음 순서로 섹션을 배치해야 한다.
  1. 이번 달 수입/지출 현황
  2. 자산 유동성 현황
  3. 자산 구성
  4. 지출 구조/예산
  5. 운영 경고
• 각 섹션은 기준 기간 또는 기준일을 명확히 표시해야 한다.
• 운영 경고 섹션은 최소한 미분류 거래 건수, 확인필요 큐 상태, 잔액대조 필요 계좌, 최근 백업/import 상태를 표시해야 한다.
• 운영 경고 항목은 해당 상세 화면 또는 관련 실행 절차로 이동할 수 있는 라벨, 메뉴 안내, 버튼 등 명확한 단서를 제공해야 한다.

FR-5. 문서 및 기준선 정렬

• docs/data-model.md는 LedgerAccount의 liquidity_bucket, 비거래 자산 수동 입력 방식, 자산/부채/순자산 계산 규칙을 설명해야 한다.
• docs/project-structure.md는 대시보드 운영 허브와 관련 집계 책임이 dashboard/app.py 및 jarca_ledger_mcp.service에 걸치는 구조를 반영해야 한다.
• docs/runtime-flows.md는 대시보드 운영 허브 조회 흐름과 KST 현재 월/transaction_date 기준, last_balance 기반 자산 유동성 집계 흐름을 반영해야 한다.
• MCP/service/dashboard interface가 변경되면 docs/interface-contract.md도 함께 갱신해야 한다.

4. Acceptance Criteria

• AC-1: 새 DB 및 기존 DB migration 후 accounts.liquidity_bucket이 존재하고 기본값/폴백은 other다.
• AC-2: 잘못된 liquidity_bucket 값으로 계좌 생성/수정 시 검증 오류가 반환된다.
• AC-3: 계좌 생성, 계좌 목록, 계좌 수정 결과에서 liquidity_bucket을 확인·설정할 수 있다.
• AC-4: 대시보드 첫 화면 최상단에 KST 현재 월 transaction_date 기준 실제 수입, 실제 지출, 순현금흐름, 저축률이 표시된다.
• AC-5: 자산 유동성/구성 섹션이 accounts.liquidity_bucket과 last_balance 기준으로 버킷별 금액, 구성 비율, 총부채, 순자산을 표시한다.
• AC-6: loan 버킷은 자산 구성 비율 분모에서 제외되고 총부채/순자산 계산에만 반영된다.
• AC-7: last_balance가 없는 비거래 자산/부채는 임의 추정하지 않고 미입력 또는 제외 상태가 화면에 명확히 표시된다.
• AC-8: 운영 경고 섹션이 미분류, 확인필요 큐, 잔액대조 필요, 백업/import 상태를 표시하고 상세 화면/절차 이동 단서를 제공한다.
• AC-9: pytest -q가 통과하고, dashboard/app.py 영향 변경이므로 scripts/streamlit_browser_evidence.py 기반 screenshot/DOM evidence가 생성된다.
• AC-10: docs/data-model.md, docs/project-structure.md, docs/runtime-flows.md, 필요 시 docs/interface-contract.md가 REQ-005 범위를 반영한다.

5. 구현 메모

• Schema version은 후속 batch에서 현재 값보다 1 증가시키고, migration은 additive/idempotent로 작성한다.
• liquidity_bucket의 권위 소스는 계좌 단위로 고정하며 거래/카테고리 override는 이번 범위에서 제외한다.
• 운영 DB, 원본 금융 파일, 민감정보를 사용하지 않고 synthetic/validation DB에서 대시보드 evidence를 생성한다.
• dcy-004 QC 결과에 따라 UI 영향 batch는 browser screenshot/snapshot evidence를 필수로 한다.
• 이 REQ는 구현 기준으로 승인되었으며, 후속 batch에서 구현·검증을 진행한다.