gitea-impl-agent/jarca-ledger-mcp
1
0
Fork 0
forked from jsfamily/jarca-ledger-mcp
Code Pull Requests Activity
Files
8950eccc24ef344887ae407f44e349ccfd8130d3
jarca-ledger-mcp/docs/srs/Interface/req-022_monthly-settlement-read-only-dashboard.md
T

11 KiB
Raw Blame History

REQ-022 Monthly settlement read-only dashboard

  • Status: Approved
  • Type: Interface
  • Priority: High
  • Owner: 렛저장인
  • Source Discovery: docs/discovery/dcy-015_20260711_monthly-settlement-page-requirements-wireframe.md
  • Source Issues: #3 [Feature] 월정산 페이지 기능 요구사항 정의, #4 [Design] 월정산 페이지 와이어프레임 수준 섹션 설계안
  • Batch: TBD
  • Created At (KST): 2026-07-11 14:30 KST
  • Approved At (KST): 2026-07-11 14:30 KST

1. 배경

현재 Jarca Ledger에는 월정산에 필요한 개별 기능이 이미 존재한다. 요약 페이지는 월중 운영 허브를 제공하고, 자산/마감 페이지는 자산 snapshot preview/close를 제공하며, 확인필요 큐·미분류·잔액대조·import batch·예산 대비 정보도 각각 조회할 수 있다.

그러나 월말 정산을 위해서는 운영자가 여러 화면을 오가며 순서를 기억해야 한다. 이 REQ는 dcy-015 confirmed 범위에 따라 1차 구현을 Streamlit dashboard의 read-only checklist/report 월정산 페이지로 제한하고, 월정산 close 상태 영속화, MCP/finance-agent summary tool, PDF/Excel/Markdown export는 후속 범위로 분리한다.

2. Intent

월정산을 단순 보고서 모음이 아니라 한 페이지에서 수행하는 운영 검토 흐름으로 제공한다. 사용자는 대상 월을 선택하고, 월말 거래 반영 상태, 정산 전 blocker, 월간 핵심 수치, asset snapshot preview/close 상태, 다음 액션을 한 화면에서 판단할 수 있어야 한다.

3. 범위

In Scope

  • Streamlit dashboard에 월정산 페이지를 추가한다.
  • 대상 월 선택(YYYY-MM)과 basis date 자동 계산을 제공한다.
  • 월정산 상태는 1차 범위에서 별도 DB 영속화하지 않고, 기존 데이터에서 read-only로 산출한다.
  • 기존 service/application layer 계산 정의를 재사용해 내부 summary read model을 구성한다.
  • 내부 summary read model은 후속 MCP/finance-agent tool 확장이 가능하도록 dashboard 내부에 계산식을 고립시키지 않는다.
  • 다음 8개 섹션을 기본 정보구조로 구현한다.
    1. Header / 월 선택
    2. 월간 핵심 KPI
    3. 현금흐름 / 지출 구조
    4. 예산 대비 점검
    5. 정산 전 검토 Blocker
    6. 자산 / 순자산 마감 상태
    7. 월정산 결과 / Evidence
    8. 다음 액션
  • docs/project-structure.md, docs/runtime-flows.md, 필요 시 docs/interface-contract.md에 월정산 page/read-model 흐름과 후속 범위 경계를 반영한다.

Out of Scope

  • 월정산 close 상태를 저장하는 신규 monthly_settlements table 또는 lock/close 엔티티 도입.
  • 월별 거래 잠금, 장부 확정 후 수정 금지 정책, 자동 스케줄 기반 정산 실행.
  • MCP/finance-agent-facing monthly settlement summary tool 노출.
  • PDF/Excel/Markdown export.
  • 외부 금융기관 자동 잔액 동기화, 세무/법률 회계 리포트, 복식부기 수준 closing engine.
  • GitHub Project 4 field/status 변경.

4. 기능 요구사항

FR-1. 대상 월 선택과 상태 헤더

  • 사용자는 YYYY-MM 단위로 정산 월을 선택할 수 있어야 한다.
  • 기본값은 KST 현재 월이다.
  • 시스템은 선택 월의 말일을 basis date로 자동 계산해야 한다.
  • 상단에는 대상 월, basis date, read-only 산출 상태 배지를 표시해야 한다.
  • 상태 배지는 별도 월정산 close 영속화 없이 기존 snapshot/import/review 데이터를 근거로 산출해야 한다.

FR-2. 월간 핵심 KPI

  • 대상 월 기준 실제 수입, 실제 지출, 순현금흐름, 저축률을 표시해야 한다.
  • 계산 기준은 기존 monthly cashflow 정의와 동일하게 transactions.transaction_date 및 ledger_categories.cashflow_kind를 사용해야 한다.
  • 예산 초과 항목 수와 미해결 blocker 수를 함께 표시해야 한다.

FR-3. 현금흐름 / 지출 구조

  • 대상 월의 카테고리별 지출 Top N을 표시해야 한다.
  • 가족 구성원/person별 지출 또는 사용처/카테고리 grouping을 제공해야 한다.
  • 고정비/변동비 또는 cashflow_kind 기반 구성을 기존 데이터가 허용하는 범위에서 표시해야 한다.
  • 상세 거래 화면으로 이동할 수 있는 메뉴 안내 또는 CTA를 제공해야 한다.

FR-4. 예산 대비 점검

  • 대상 월의 budget vs actual report를 표시해야 한다.
  • table은 category, subcategory, person, budget, actual, remaining, usage rate, status를 포함해야 한다.
  • 초과 또는 임박 항목은 시각적으로 구분해야 한다.

FR-5. 정산 전 검토 Blocker

  • 상단 요약과 상세 섹션에서 최소 다음 blocker를 표시해야 한다.
    • 미분류 거래 수
    • 큰 금액 미분류 거래 수 또는 미분류 금액 합계
    • 확인필요/이체 검토 pending 수
    • held/recheck 수
    • 잔액대조 필요 계좌 수
    • 최근 import 상태와 row_count = 0 또는 rolled_back batch
    • stale_valuation, missing_last_balance에 해당하는 자산/계좌 경고
  • 내부 코드성 경고명은 UI에서 자연어 설명으로 표시해야 한다.
  • 각 blocker는 관련 상세 페이지로 이동할 수 있는 메뉴 안내 또는 CTA를 제공해야 한다.

FR-6. 거래 반영 / import 상태

  • 계좌별 계좌명, 유형, 기관명, 마지막 반영 시각(last_synced_at), 마지막 잔액(last_balance), 상태 배지를 표시해야 한다.
  • 상태 배지는 정상, 주의, 갱신 필요, 잔액 없음 또는 이에 준하는 사용자 친화 표현을 사용해야 한다.
  • 최근 import batch 목록은 source, masked filename/provenance summary, imported_at, row_count, status를 표시해야 한다.
  • import provenance 표시는 REQ-021의 minimal/operator-summary 노출 정책을 따라야 하며 raw local path나 raw payload를 노출하지 않아야 한다.

FR-7. 자산 / 순자산 마감 상태

  • 대상 월 basis date 기준 asset snapshot preview 또는 closed snapshot 상태를 표시해야 한다.
  • 자산 합계, 총부채, 순자산, included/excluded/warnings 요약을 표시해야 한다.
  • snapshot close 실행 자체는 기존 자산/마감 workflow와 service를 재사용하며, 월정산 페이지에서 직접 close write를 추가하는 것은 1차 범위에서 제외한다.
  • close가 필요한 경우 사용자가 자산/마감 페이지로 이동할 수 있는 CTA를 제공해야 한다.

FR-8. 월정산 결과 / Evidence와 다음 액션

  • read-only 결과 섹션은 close 가능 조건 pass/fail, 주요 blocker, snapshot 상태, source summary를 표시해야 한다.
  • 다음 액션 섹션은 다음 달 예산 조정 후보, 반복 미분류/확인필요 rule 후보, 잔액대조/backup/import follow-up을 제안해야 한다.
  • PDF/Excel/Markdown export는 UI나 backend 구현에 포함하지 않고 후속 범위임을 문서화해야 한다.

FR-9. 검증 범위

  • dashboard AppTest 또는 equivalent Streamlit smoke는 월정산 페이지가 synthetic fixture DB에서 렌더링되는지 확인해야 한다.
  • HTTP smoke 또는 browser evidence는 핵심 섹션 heading과 주요 KPI/blocker 표시를 확인해야 한다.
  • full pytest와 ruff가 통과해야 한다.

5. 비기능 요구사항

  • NFR-1 (계산 일관성): 월정산 페이지의 계산 기준은 기존 service/application layer 정의를 재사용해야 하며 dashboard 내부에서 별도 산식을 중복 구현하지 않는다.
  • NFR-2 (무부작용): 1차 월정산 페이지는 read-only여야 하며, 월정산 close 영속화나 거래 lock 같은 신규 write side effect를 만들지 않는다.
  • NFR-3 (확장성): 내부 summary read model은 후속 MCP/finance-agent-facing tool로 확장 가능하도록 application/service boundary에서 구성한다.
  • NFR-4 (민감정보 보호): import/provenance/evidence 표시는 REQ-021 정책을 따르고 raw path, raw payload, 원본 금융파일 내용을 노출하지 않는다.
  • NFR-5 (운영성): 내부 코드명(missing_last_balance, stale_valuation 등)은 사용자에게 자연어 설명과 권장 조치로 표시한다.

6. Acceptance Criteria

  • AC-1: Streamlit sidebar 또는 routing에서 월정산 페이지에 접근할 수 있다.
  • AC-2: 대상 월 선택 시 basis date가 해당 월 말일로 계산되어 표시된다.
  • AC-3: 대상 월의 실제 수입, 실제 지출, 순현금흐름, 저축률, 예산 초과 항목 수, 미해결 blocker 수가 표시된다.
  • AC-4: 현금흐름/지출 구조 섹션이 카테고리/person/고정비 또는 동등한 월간 지출 분석을 표시한다.
  • AC-5: 예산 대비 섹션이 budget, actual, remaining, usage rate, status를 표시하고 초과/임박 항목을 구분한다.
  • AC-6: 정산 전 검토 Blocker 섹션이 미분류, 확인필요/이체 검토, 보류/재검토, 잔액대조, import, last_balance/valuation 경고를 사용자 친화 문구로 표시한다.
  • AC-7: 거래 반영/import 상태 섹션이 계좌별 last_synced_at/last_balance 상태와 최근 import batch 상태를 표시하며 raw local path/raw payload를 노출하지 않는다.
  • AC-8: 자산/순자산 마감 상태 섹션이 asset snapshot preview 또는 closed 상태, 자산 합계, 총부채, 순자산, warnings/excluded 요약을 표시한다.
  • AC-9: 1차 범위 구현에는 신규 monthly_settlements table, 월정산 close persistence, MCP monthly settlement tool, export 기능이 포함되지 않는다.
  • AC-10: 내부 summary read model 또는 gateway는 후속 MCP 확장을 방해하지 않는 위치에 구성된다.
  • AC-11: dashboard synthetic fixture 기반 AppTest/HTTP smoke 또는 equivalent browser evidence가 월정산 페이지 핵심 섹션 렌더링을 검증한다.
  • AC-12: docs/project-structure.md, docs/runtime-flows.md, 필요 시 docs/interface-contract.md가 월정산 page/read-model 흐름과 후속 범위 경계를 반영한다.
  • AC-13: python -m ruff check .와 python -m pytest -q가 통과한다.

7. Impacted Area

  • dashboard/app.py 또는 월정산 page module
  • jarca_ledger_mcp.adapters.streamlit.*_gateway
  • 월정산 summary read model을 둘 application/service module
  • tests/test_dashboard_app.py 및 dashboard HTTP/browser smoke
  • docs/project-structure.md
  • docs/runtime-flows.md
  • docs/interface-contract.md if an internal/external interface contract changes

8. Notes

  • 이 REQ는 dcy-015의 1차 범위만 다룬다.
  • 월정산 close 영속화, MCP/finance-agent summary tool, PDF/Excel/Markdown export는 후속 Discovery/REQ 후보로 남긴다.
  • 기존 자산/마감 페이지의 asset snapshot close write semantics를 중복 구현하지 않는다.
  • GitHub Project 4 board field/status 변경은 이 REQ 범위가 아니며, issue #3/#4와 StagePilot 문서 추적을 구현 입력으로 삼는다.

9. Change Log

  • 2026-07-11 14:30 KST: dcy-015 confirmed 범위로 REQ-022 Proposed 초안을 생성했다.
  • 2026-07-11 14:30 KST: 사용자 승인 범위와 confirm-req 게이트 검토에 따라 Approved로 전환했다.
View Git Blame Copy Permalink