# 0. 문서 상태
이 문서의 현재 상태와 식별 정보를 기록한다. 문서 추적과 승인 흐름에 필요한 최소 메타데이터를 적는다.

- 상태: confirmed
- 문서 ID: dcy-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow
- 이슈명: Jarca Ledger 대시보드 운영 허브 사양 정립 (이번 달 현금흐름 + 자산 유동성 + 운영 미처리)
- 작성 시각(KST): 2026-06-29 14:02 KST
- 마지막 갱신 시각(KST): 2026-06-29 20:03 KST
- 대체됨: 없음
- 후속 Discovery 참조: 없음
- 생성된 REQ 참조: REQ-005 (`docs/srs/Interface/req-005_dashboard-operations-hub-liquidity-monthly-cashflow.md`)

# 1. 계획 상태 요약
현재 Discovery가 어떤 배경에서 작성되고 있는지, 연계 문서가 있는지, 지금 시점의 해석이 무엇인지 짧게 요약한다.

- 연계 문서 현황:
	- 관련 점수 파일: 미생성
	- 관련 TODO/메모: 없음
- 해석:
	- 대시보드 첫 화면(`page_overview`)이 현재는 전체 기간 누적 손익·계좌 입출금 위주라, "이번 달 운영 상태"와 "현재 자산 유동성/부채 구조"를 한 화면에서 보려는 운영자 요구를 충족하지 못한다.
	- 이번 Discovery는 대시보드를 단일 운영 허브로 재정의하고, 이번 달 현금흐름·자산 유동성·운영 미처리 경고를 우선순위 구조로 묶는 변경 범위와 데이터 모델 보강(`liquidity_bucket`) 필요성을 판단한다.

# 2. 요구사항 판정 결과
이번 요청이 기존 요구사항과 비교해 신규인지, 유사한지, 중복인지 판단하고 그 근거를 남긴다.

- 판정: 신규
- 근거
	- dcy-001은 Streamlit UX/E2E·분류·환급 워크플로우 안정화, dcy-002~004는 백업·복구, statement-unavailable 수동 증빙/잔액대조, E2E evidence 환경 복구로 문제 정의가 다르며 "대시보드 화면 구성·자산 유동성 뷰"를 다루지 않는다.
	- 본 요청은 대시보드 정보구조 재정의와 신규 자산 분류 축(`liquidity_bucket`) 도입을 핵심으로 하므로 기존 후보의 미세 조정이 아니라 독립 주기로 추적하는 것이 명확하다.

# 3. 문제점의 요약
문제의 현재 상태, 기대 상태, 관련 이해관계자, 제약사항을 정리한다. Discovery의 핵심 맥락을 가장 먼저 이해할 수 있어야 한다.

- 현재 상태
	- `dashboard/app.py`의 `page_overview`는 `status='active'` 전체 거래를 누적 집계해 "실제 수입/지출/순현금흐름/저축률/확인필요"와 "계좌 입출금 흐름", 월별/인원별/카테고리 Top20 차트를 보여준다. 상단 지표가 당월이 아니라 전체 기간 합계 기준이라 "이번 달 현황"을 즉시 읽기 어렵다.
	- 자산 측면에서 `ledger_accounts.type`은 bank/card/cash/investment/loan 구분만 있고(`docs/data-model.md` Entity: LedgerAccount), 현금·투자·예적금·부동산·대출을 유동성 관점으로 묶는 `liquidity_bucket` 축은 없다. 자산 유동성/구성/순자산 뷰가 대시보드에 존재하지 않는다.
	- 운영 미처리 신호(미분류 거래, 확인필요 큐, 잔액대조 필요, 백업/import 상태)는 `page_uncategorized`, `page_cross_transfer_review`, `docs/runbooks/manual-balance-reconciliation.md`, 백업 워크플로우 등 별도 화면/문서에 흩어져 있어 한 화면에서 운영 상태를 점검하지 못한다.
	- `docs/project-structure.md`, `docs/runtime-flows.md` baseline 문서는 존재하나 대시보드 운영 허브 정보구조와 `liquidity_bucket` 데이터 흐름을 아직 반영하지 않는다.
- 기대 상태
	- 대시보드 첫 화면이 "이번 달 수입/지출 현황 → 자산 유동성 현황 → 자산 구성 → 지출 구조/예산 → 운영 경고" 순서의 운영 허브로 동작한다.
	- 자산을 유동성 버킷(현금/투자/예적금/부동산/대출)으로 묶어 금액·비율을 확인하고, 대출은 자산 구성 비율에서 제외하되 부채/순자산 계산에서 별도 차감한다.
- 이해관계자
	- 가계 재무를 운영하는 사용자(대시보드 1차 사용자)
	- 문서/요구사항 리뷰어 및 승인자(Hermes/사용자)
	- 대시보드·서비스·DB를 구현/운영하는 개발 담당자
- 제약사항
	- DB 스키마 변경은 additive/idempotent 원칙을 따르며 파괴적 마이그레이션은 명시 승인·백업 후에만 한다(`docs/data-model.md` Persistence Notes).
	- 부동산·무기한 자산처럼 거래 기반이 아닌 자산은 입력 소스가 불명확해 데이터 확보 방식 결정이 선행되어야 한다.
	- 본 Discovery 단계에서는 소스 코드/테스트/스키마를 변경하지 않고 사양만 정의한다.

## 주요 사용자 시나리오
사용자 또는 운영자가 실제로 어떤 상황에서 이 변경을 필요로 하는지 대표 시나리오를 적는다.

- 사용자가 월중에 대시보드를 열어 "이번 달 수입·지출·순현금흐름·저축률"을 최상단에서 즉시 확인하고 이번 달 지출 속도를 점검한다.
- 사용자가 "지금 당장 쓸 수 있는 현금이 얼마이고, 1~2주 내 가용 투자/예적금이 얼마이며, 부동산·대출까지 포함한 순자산이 얼마인지" 자산 유동성·구성 섹션에서 한눈에 파악한다.
- 사용자가 같은 화면 하단의 운영 경고에서 미분류 건수, 확인필요 큐, 잔액대조 필요 계좌, 최근 백업/import 상태를 보고 후속 정리 작업으로 이동한다.

# 4. 이번에 정의할 변경
이번 Discovery에서 다루는 핵심 변경 항목을 목록으로 적는다. 기능, 구조, 규칙 변경을 함께 포함해도 된다.

- 대시보드 운영 허브 정보구조 확정: ① 이번 달 수입/지출 현황 ② 자산 유동성 현황 ③ 자산 구성 ④ 지출 구조/예산 ⑤ 운영 경고의 5개 섹션 우선순위와 각 섹션 표시 지표를 사양으로 정의한다.
- 자산 유동성 분류 축 도입 검토: `liquidity_bucket`(cash, investment, deposit, real_estate, loan, other)을 권장 필드로 정의하고, 대출은 자산 구성 비율에서 제외·부채/순자산에서 별도 차감하는 집계 규칙을 정한다.
- baseline 문서 반영: `liquidity_bucket` 데이터 모델과 대시보드 운영 허브 화면 흐름을 `docs/data-model.md`, `docs/project-structure.md`, `docs/runtime-flows.md`에 갱신 요구로 등록한다.

## 영향 범위
변경이 미칠 코드/문서/운영 범위를 명시해 REQ 정제와 batch planning에서 추정 누락을 줄인다.

- 코드 영향:
	- `dashboard/app.py`의 `page_overview` 재구성(이번 달 스코프 집계, 자산 유동성/구성/순자산 섹션, 운영 경고 통합 패널) 및 관련 집계 헬퍼.
	- `liquidity_bucket` 도입 시 `jarca_ledger_mcp/db.py` 스키마(additive)와 `service.py` 자산/유동성 집계 함수, 분류 매핑 로직.
- 문서 영향:
	- `docs/data-model.md`(LedgerAccount/LedgerCategory에 `liquidity_bucket` 축, 순자산/부채 집계 규칙), `docs/project-structure.md`, `docs/runtime-flows.md`(대시보드 운영 허브 화면 흐름) 갱신.
- 운영 영향:
	- 부동산·대출 등 비거래 자산 입력/갱신 절차가 신설될 수 있어 운영 입력 루틴과 잔액대조 운영 흐름에 영향을 준다.

# 5. 요구사항 목록
실제로 구현과 검증으로 이어질 요구사항을 기능/비기능으로 나누어 정리하고, 범위 경계를 명확히 적는다.

## 기능 요구사항
- FR-1: 대시보드 최상단 1순위 섹션은 "이번 달 수입/지출 현황"으로, 당월 기준 실제 수입·실제 지출·순현금흐름·저축률을 표시한다. 당월 범위는 거래일(`transaction_date`) 기준 현재 월을 기본으로 한다.
- FR-2: "자산 유동성 현황" 섹션은 현금(당장 사용 가능), 투자(1~2주 내 사용 가능), 예적금(달~년), 부동산(무기한), 대출(부채)을 버킷으로 묶어 각 금액과 비율을 표시한다. 비율 분모는 대출(부채)을 제외한 자산 합계로 하고, 대출은 부채/순자산 계산에서 별도 차감한다.
- FR-3: 대시보드는 ① 이번 달 수입/지출 현황 ② 자산 유동성 현황 ③ 자산 구성 ④ 지출 구조/예산 ⑤ 운영 경고(미분류, 확인필요, 잔액대조 필요, 백업/import 상태)의 순서로 섹션을 배치한다.
- FR-4: 자산을 유동성 관점으로 묶기 위해 `accounts.liquidity_bucket`(cash, investment, deposit, real_estate, loan, other) 분류 축을 데이터 모델에 도입한다. `liquidity_bucket`의 권위 소스는 계좌 단위이며, 미지정 계좌는 `other`로 폴백한다. 거래/카테고리 단위 override는 이번 범위에서 제외한다.
- FR-5: `docs/data-model.md`, `docs/project-structure.md`, `docs/runtime-flows.md` baseline 문서에 `liquidity_bucket` 모델과 대시보드 운영 허브 화면 흐름 갱신을 포함한다.

## 비기능 요구사항
성능, 운영성, 일관성, 자동화 안정성 등 기능 외 요구사항을 적는다.

- NFR-1 (일관성): 자산 구성 비율과 순자산/부채 계산은 단일 정의(대출은 구성 비율 제외, 순자산에서 차감)를 모든 섹션·집계에서 동일하게 적용한다.
- NFR-2 (운영성): 운영 경고 섹션의 각 항목(미분류·확인필요·잔액대조·백업/import)은 건수/상태와 함께 해당 상세 화면으로 이동할 수 있는 단서를 제공한다.
- NFR-3 (안정성): `accounts.liquidity_bucket` 스키마 변경은 additive/idempotent로 적용하고, 미지정 계좌는 `other`로 안전하게 폴백해 기존 대시보드 동작을 깨지 않는다.

## 범위 경계
이번 반복에서 반드시 포함할 범위와 명시적으로 제외할 범위를 구분한다.

- In Scope
	- 대시보드 운영 허브 5개 섹션 정보구조와 각 섹션 핵심 지표 사양 정의.
	- `accounts.liquidity_bucket` 축과 자산 유동성/구성/순자산·부채 집계 규칙 정의 및 baseline 문서 갱신 요구.
- Out of Scope
	- 다계좌 실시간 잔액 연동, 외부 시세/투자 평가액 자동 연동.
	- 카드 미결제금, 보험 해지환급금, 자동 시세 연동 자산 반영.
	- 별도 자산 평가 테이블(`asset_snapshots`, `manual_assets` 등) 신설. 초기 구현은 `accounts` 항목의 수동 입력으로 처리한다.

# 6. 리스크/가정 목록
불확실성과 전제 조건을 분리해서 적는다. 리스크는 영향과 완화 방안을, 가정은 현재 판단의 전제를 기록한다.

## 리스크
- R-1 (Medium): `liquidity_bucket` 권위 소스가 구현 중 계좌 외 카테고리/거래 override로 확장되면 자산 집계 소스가 이중화돼 비율이 어긋날 수 있다.
	- 완화 방안: 이번 반복의 단일 권위 소스는 `accounts.liquidity_bucket`으로 고정하고, 거래/카테고리 override는 후속 범위로 제외한다. 미매핑은 `other`로 폴백한 뒤 운영 경고로 노출한다.
- R-2 (Medium): 부동산·대출 등 비거래 자산은 거래 데이터로 산출되지 않아 입력 누락 시 자산 유동성/순자산 수치가 왜곡된다.
	- 완화 방안: 초기에는 `accounts` 항목에 수동 입력하고, `last_balance`를 현재 평가액/잔액, `last_synced_at`을 기준일, `memo`를 출처 메모로 사용한다. 미입력 자산은 수치에서 제외했음을 화면에 표기한다.
- R-3 (Low): 상단 "이번 달" 스코프와 기존 전체 기간 차트가 한 화면에 공존하면 사용자가 기준 기간을 혼동할 수 있다.
	- 완화 방안: 각 섹션에 기준 기간 라벨을 명시하고, 당월/전체 기준을 시각적으로 구분한다.

## 가정
아직 확정되지 않았지만 현재 문서 작성의 기반이 되는 전제를 적는다.

- A-1: 저축률은 기존 `page_overview` 정의(순현금흐름 ÷ 실제 수입)를 당월 범위로 적용한다.
- A-2: 실제 수입/지출 판정은 기존 `ledger_categories.cashflow_kind`(income/expense 등) 기준을 그대로 재사용한다.
- A-3: 대출은 자산이 아니라 부채로 취급하며 자산 구성 비율의 분모에서 제외하고, 총부채/순자산 계산에만 사용한다.

## 오픈 질문
답을 아직 모르는 항목을 적는다. 추정으로 덮지 말고 REQ 초안 작성 이전에 확인할 질문으로 남긴다.

- OQ-1: `liquidity_bucket`의 권위 소스를 계좌 단위로 둘지, 카테고리/거래 단위로 둘지 결정한다.
	- 상태: Answered
	- 처리 방안: `liquidity_bucket`의 권위 소스는 `accounts.liquidity_bucket`으로 둔다. 허용값은 `cash`, `investment`, `deposit`, `real_estate`, `loan`, `other`이며, 미지정 계좌는 `other`로 폴백한다. 거래/카테고리 override는 이번 범위에서 제외한다.
	- 종료 조건: 자산 집계 권위 소스와 폴백 규칙이 REQ 초안에 명시되면 Answered 처리.
- OQ-2: 부동산·무기한 자산과 대출 잔액의 입력/갱신 방식(수동 입력 vs 전용 계좌 vs 외부 연동)을 어떻게 둘지 결정한다.
	- 상태: Answered
	- 처리 방안: 부동산, 예적금, 대출 잔액 등 거래내역만으로 산출되지 않는 자산/부채는 초기에는 `accounts` 항목으로 수동 입력한다. `last_balance`는 현재 평가액/잔액, `last_synced_at`은 기준일, `memo`는 출처 메모로 사용한다. 별도 자산 평가 테이블과 자동 시세 연동은 후속 범위로 둔다.
	- 종료 조건: 비거래 자산 입력/갱신 방식이 REQ 초안과 운영 절차에 반영되면 Answered 처리.

### 오픈 질문 처리 기준
- `Open`: 아직 답이 없고 다음 단계 진행에 영향이 있는 상태다. 문서에 유지한다.
- `Answered`: 답이 확정된 상태다. 관련 본문/요구사항에 반영한 뒤 오픈 질문 목록에서는 제거하거나 resolved 기록으로 이동한다.
- `Deferred`: 지금 단계에서 결정하지 않고 다음 단계 또는 후속 이슈로 넘기는 상태다. 넘길 대상과 이유를 반드시 적는다.
- `Dropped`: 더 이상 유효하지 않은 질문이다. 삭제 사유를 짧게 남기고 목록에서 제거한다.
- 처리 원칙 1: 질문만 남기지 말고 반드시 `상태`, `처리 방안`, `종료 조건`을 함께 적는다.
- 처리 원칙 2: 답이 나온 질문은 본문 반영 없이 단순 삭제하지 않는다. 반영 위치를 먼저 갱신한다.
- 처리 원칙 3: High 영향 질문은 `Deferred` 처리 후 처리 방안에 REQ 인계 추적 방식을 명시한다.

# 7. 초기 성공 기준
이 변경이 성공했다고 판단할 기준을 측정 가능하게 정의한다. 가능하면 데이터 출처까지 연결한다.

- S-1: 대시보드 첫 화면에서 이번 달 수입/지출 현황, 자산 유동성 현황, 운영 경고가 정의된 우선순위 순서로 모두 노출된다.
- S-2: 자산 유동성/구성 섹션에서 `accounts.liquidity_bucket` 기준 버킷별 금액·비율, 대출 제외 자산 합계, 총부채, 순자산이 단일 정의에 따라 일관되게 계산된다.
- S-3: `liquidity_bucket` 데이터 모델과 대시보드 운영 허브 화면 흐름이 `docs/data-model.md`, `docs/project-structure.md`, `docs/runtime-flows.md`에 반영된다.

## 측정 방식 및 데이터 출처
각 성공 기준을 어떻게 측정할지와 어떤 데이터나 문서를 근거로 쓸지 적는다.

- S-1 측정 방식: 대시보드 운영 허브 화면 검수(스크린샷/E2E)로 섹션 순서·표시 지표 확인 / 데이터 출처: `dashboard/app.py` 렌더 결과, REQ 화면 사양
- S-2 측정 방식: 표본 데이터로 버킷 합계·비율·순자산 계산을 손검증과 비교 / 데이터 출처: `transactions`, `ledger_accounts`, `accounts.liquidity_bucket` 매핑 규칙
- S-3 측정 방식: baseline 문서 diff에서 `liquidity_bucket`·운영 허브 화면 흐름 반영 여부 확인 / 데이터 출처: `docs/data-model.md`, `docs/project-structure.md`, `docs/runtime-flows.md`

# 8. REQ로 넘기기 전 확인 체크
REQ 초안 작성 단계로 넘기기 전에 무엇이 확정되어야 하는지 확인한다. 미완료 항목은 후속 결정이 필요함을 뜻한다.

- [x] 범위(In Scope/Out of Scope) 확정
	- 기준: 순자산 산식은 `accounts.liquidity_bucket` 기준 금융자산·수동 입력 비거래 자산에서 `loan`을 차감하는 방식으로 확정하고, 부동산 평가 자동화·자동 시세 연동·별도 자산 테이블은 제외한다.
- [x] 성공 지표의 측정 방식/데이터 출처 확정
	- 기준: S-1~S-3의 검수 방식과 데이터 출처가 REQ에서 실행 가능하게 구체화됨
- [x] High 영향 리스크 우선순위 및 해소 책임자 지정
	- 기준: `liquidity_bucket` 권위 소스는 계좌 단위로 고정하고, 비거래 자산 입력 리스크는 수동 입력 계좌/자산 항목과 기준일/출처 메모로 해소한다.
- [x] 모든 오픈 질문(OQ) `Open` 상태 없음 확인
	- 기준: OQ 목록에 `Open` 상태 항목이 0개이거나, 잔여 항목 전부 `Deferred` 처리 완료
- [x] Freeze 확정 담당자(CONFIRMED_BY) 지정
	- 기준: 사용자 진환 고가 권장안을 승인하고 confirm-discovery 진행을 지시했다.

# 9. 파일 처리 결과
이 Discovery 문서 생성/갱신 결과와 참조 문서를 기록한다. 이후 추적과 리뷰 시 근거로 사용한다.

- 처리 결과: 생성
- 생성 경로: docs/discovery/dcy-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow.md
- 참조 문서:
	- docs/data-model.md (LedgerAccount/LedgerCategory, `liquidity_bucket` 도입 대상)
	- docs/runtime-flows.md, docs/project-structure.md (대시보드 운영 허브 화면 흐름 갱신 대상; stage-pilot/templates/runtime-flows.md, stage-pilot/templates/project-structure.md를 논리 템플릿 참조로 사용)
	- dashboard/app.py `page_overview` (현재 대시보드 첫 화면 구현 근거)

# 10. 사용자 결정 필요 항목 요약
사용자나 승인자가 결정해야 하는 항목만 모아 정리한다. 결정, 확인, 데이터 요청을 구분해서 적는다.

## DECIDE
- `liquidity_bucket`의 권위 소스는 `accounts.liquidity_bucket`으로 둔다. 허용값은 `cash`, `investment`, `deposit`, `real_estate`, `loan`, `other`이며, 미지정 계좌는 `other`로 폴백한다. 거래/카테고리 override는 이번 범위에서 제외한다.
- 순자산은 `cash`, `investment`, `deposit`, `real_estate`, `other` 중 자산성 항목의 합계에서 `loan` bucket 합계를 차감해 계산한다. 대출은 자산 구성 비율에는 포함하지 않고 총부채/순자산 계산에만 사용한다. 카드 미결제금, 보험 해지환급금, 자동 시세 연동은 이번 범위에서 제외한다.

## CONFIRM
- "이번 달"은 `transaction_date` 기준 현재 월(KST)로 정의한다. `posted_date` 기준 또는 사용자 정의 회계 월 마감은 후속 옵션으로 둔다.

## DATA
- 부동산, 예적금, 대출 잔액 등 거래내역만으로 산출되지 않는 자산/부채는 초기에는 `accounts` 항목으로 수동 입력한다. `last_balance`는 현재 평가액/잔액, `last_synced_at`은 기준일, `memo`는 출처 메모로 사용한다. 별도 자산 테이블과 자동 시세 연동은 후속 범위로 둔다.

# 11. Discovery Freeze
REQ 초안 작성 인계 시점의 확정 플래그와 섹션 참조만 기록한다. 내용 재작성 없이 원본 섹션을 링크로 대신한다.

## 섹션 참조
- 범위: [# 5. 요구사항 목록 > 범위 경계](#5-요구사항-목록)
- 리스크/오픈 질문: [# 6. 리스크/가정 목록](#6-리스크가정-목록)
- 성공 기준: [# 7. 초기 성공 기준](#7-초기-성공-기준)
- 인계 전 확인: [# 8. REQ로 넘기기 전 확인 체크](#8-req로-넘기기-전-확인-체크)
- 사용자 결정 필요: [# 10. 사용자 결정 필요 항목 요약](#10-사용자-결정-필요-항목-요약)

## Freeze 플래그
- Handoff Decision: 승인
- Handoff Rationale: 사용자 승인으로 대시보드 운영 허브 정보구조, `accounts.liquidity_bucket` 권위 소스, 순자산/부채 계산 경계, 이번 달 기준, 비거래 자산 수동 입력 방식이 확정되었으므로 REQ 초안 작성으로 넘긴다.
- Ready for REQ Drafting: true
- Confirmed By: 진환 고
- Confirmed At (KST): 2026-06-29 14:08 KST