gitea-impl-agent/jarca-ledger-mcp
1
0
Fork 0
forked from jsfamily/jarca-ledger-mcp
Code Pull Requests Activity
Files
beddff7661b543c5b6840cd2d5ca83fab2d3b0bb
jarca-ledger-mcp/docs/discovery/dcy-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow.md
T

20 KiB
Raw Blame History

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: "자산 유동성 현황" 섹션은 현금(당장 사용 가능), 투자(12주 내 사용 가능), 예적금(달년), 부동산(무기한), 대출(부채)을 버킷으로 묶어 각 금액과 비율을 표시한다. 비율 분모는 대출(부채)을 제외한 자산 합계로 하고, 대출은 부채/순자산 계산에서 별도 차감한다.
  • 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 초안 작성 단계로 넘기기 전에 무엇이 확정되어야 하는지 확인한다. 미완료 항목은 후속 결정이 필요함을 뜻한다.

  • 범위(In Scope/Out of Scope) 확정
    • 기준: 순자산 산식은 accounts.liquidity_bucket 기준 금융자산·수동 입력 비거래 자산에서 loan을 차감하는 방식으로 확정하고, 부동산 평가 자동화·자동 시세 연동·별도 자산 테이블은 제외한다.
  • 성공 지표의 측정 방식/데이터 출처 확정
    • 기준: S-1~S-3의 검수 방식과 데이터 출처가 REQ에서 실행 가능하게 구체화됨
  • High 영향 리스크 우선순위 및 해소 책임자 지정
    • 기준: liquidity_bucket 권위 소스는 계좌 단위로 고정하고, 비거래 자산 입력 리스크는 수동 입력 계좌/자산 항목과 기준일/출처 메모로 해소한다.
  • 모든 오픈 질문(OQ) Open 상태 없음 확인
    • 기준: OQ 목록에 Open 상태 항목이 0개이거나, 잔여 항목 전부 Deferred 처리 완료
  • 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 초안 작성 인계 시점의 확정 플래그와 섹션 참조만 기록한다. 내용 재작성 없이 원본 섹션을 링크로 대신한다.

섹션 참조

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
View Git Blame Copy Permalink