gitea-impl-agent/jarca-ledger-mcp
1
0
Fork 0
forked from jsfamily/jarca-ledger-mcp
Code Pull Requests Activity
Files
5ecd12f05aa7949b639a44d3a9f259102014fa4d
jarca-ledger-mcp/docs/discovery/dcy-015_20260711_monthly-settlement-page-requirements-wireframe.md
T

18 KiB
Raw Blame History

0. 문서 상태

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

  • 상태: draft
  • 문서 ID: dcy-015_20260711_monthly-settlement-page-requirements-wireframe
  • 이슈명: 월정산 페이지 기능 요구사항 및 와이어프레임 수준 섹션 설계
  • 작성 시각(KST): 2026-07-11 10:48 KST
  • 마지막 갱신 시각(KST): 2026-07-11 11:03 KST
  • 대체됨: 없음
  • 후속 Discovery 참조: 없음
  • 생성된 REQ 참조: 없음
  • 요청 출처: 최총무가 등록한 GitHub Issues #3 [Feature] 월정산 페이지 기능 요구사항 정의, #4 [Design] 월정산 페이지 와이어프레임 수준 섹션 설계안
  • GitHub 확인 상태: repository issue 본문은 확인 완료. GitHub Project 4 API 직접 조회는 현재 CLI token의 read:project scope 부족으로 별도 blocked이나, 원문 요구사항은 issue #3/#4에서 확인했다.

1. 계획 상태 요약

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

  • 연계 문서 현황:
    • 관련 Discovery: dcy-005(대시보드 운영 허브/monthly cashflow), dcy-008(자산 스냅샷/평가), dcy-009(월말 스냅샷 생성/마감), dcy-012(확인필요/잔액대조 워크벤치), dcy-014(import provenance)
    • 관련 REQ: REQ-005, REQ-010, REQ-012, REQ-020, REQ-021
    • 관련 GitHub Issues: #3 [Feature] 월정산 페이지 기능 요구사항 정의, #4 [Design] 월정산 페이지 와이어프레임 수준 섹션 설계안 — 본문 확인 완료
  • 해석:
    • 기존 요약과 자산/마감 화면은 월중 운영 현황과 자산 스냅샷 close 기능을 제공하지만, 월말 또는 특정 월의 재무 운영을 한 번에 결산·검토·확정하는 전용 월정산 페이지는 없다.
    • 이번 Discovery는 구현에 바로 들어가기 전, 월정산 페이지의 기능 요구사항과 와이어프레임 수준 섹션 구성을 먼저 정의해 최총무/finance workflow가 사용할 운영 화면의 책임 경계를 확정하는 작업이다.

2. 요구사항 판정 결과

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

  • 판정: 새 Discovery 생성
  • 근거:
    • REQ-005는 대시보드 첫 화면의 당월 현금흐름·자산 유동성·운영 경고를 다루며, 월말 결산 절차/검토 체크리스트/마감 결과 요약을 전용 페이지로 묶는 범위가 아니다.
    • REQ-012는 자산 snapshot preview/close에 집중하며, 거래/예산/미분류/확인필요/import evidence까지 포함한 월정산 운영 페이지의 전체 정보구조를 다루지 않는다.
    • 따라서 기존 Discovery의 미세 조정이 아니라, 기존 구현을 조합해 별도 화면·workflow로 정리하는 신규 인터페이스 반복으로 추적하는 편이 명확하다.

3. 문제점의 요약

문제의 현재 상태, 기대 상태, 관련 이해관계자, 제약사항을 정리한다.

  • 현재 상태:
    • dashboard/app.py에는 요약 페이지가 있으며, KST 현재 월의 수입/지출, 자산 유동성, 자산 구성, 지출 구조/예산, 운영 경고를 보여준다.
    • 자산/마감 페이지는 수기 자산/부채 CRUD와 월말 스냅샷 Preview/Close를 제공한다.
    • 확인필요 큐, 미분류, 잔액대조, import batch, 예산 대비 실적은 각각 별도 섹션/페이지/서비스에 흩어져 있다.
    • 월정산 관점에서 필요한 “검토 대상 → 조정/확정 → 마감 증거 → 다음 액션” 흐름은 아직 하나의 페이지로 묶여 있지 않다.
  • 기대 상태:
    • 사용자는 월정산 페이지에서 특정 월을 선택하고, 월간 수입/지출/저축률, 예산 대비, 카테고리/가족 구성원별 지출, 확인필요/미분류/잔액대조/import 상태, 자산 snapshot 상태를 한 화면에서 검토한다.
    • 월정산 페이지는 마감 전 blocker와 마감 후 요약을 구분해 보여주며, 실제 destructive write는 기존 snapshot close 정책처럼 preview-first / explicit close / append-only evidence 원칙을 따른다.
  • 이해관계자:
    • 최총무: 월정산 운영 요구사항과 화면 정보구조 요청자
    • 사용자/가계 운영자: 월말 결산 검토 및 확정 사용자
    • finance agent 또는 향후 정산 agent: 월정산 상태와 미해결 항목을 소비할 도메인 agent
    • dev-butler/delivery-runner/dev-impl/dev-qc: 기능 설계·구현·검증 담당
  • 제약사항:
    • Jarca Ledger 서비스/DB가 source of truth이며, agent memory에 정산 데이터를 저장하지 않는다.
    • 운영 DB 변경은 additive/idempotent여야 하며, 월정산 close가 필요하다면 preview와 명시적 확정 단계를 분리해야 한다.
    • GitHub Project 4의 board metadata는 read:project scope 부족으로 직접 조회하지 못했지만, 최총무가 등록한 repo issue #3/#4 본문은 확인했으므로 요구사항 원문 근거는 확보했다.

주요 사용자 시나리오

  • 사용자가 월말에 월정산 페이지를 열어 대상 월을 선택하고, 수입/지출/저축률/예산 초과/순자산 변동을 먼저 확인한다.
  • 사용자가 마감 전 blocker 목록에서 미분류 거래, 확인필요 큐, 잔액대조 필요 계좌, import evidence 확인 필요 항목을 보고 상세 화면으로 이동한다.
  • 사용자가 모든 blocker가 해소된 뒤 월정산 summary를 확인하고, 필요 시 자산 snapshot close 또는 월정산 close를 실행한다.
  • 최총무 또는 finance agent가 월정산 완료 여부, 남은 action item, 해당 월 핵심 지표를 구조화된 summary로 확인한다.

4. 이번에 정의할 변경

  • 월정산 전용 페이지의 기능 요구사항 정의: 월 선택, 월간 요약, 예산/카테고리 분석, review blocker, 자산/마감 상태, close evidence의 책임 경계를 정한다.
  • 와이어프레임 수준 섹션 설계: 구현 전 페이지 섹션 순서, 각 섹션의 주요 지표/표/CTA, 상세 페이지 이동 단서를 정의한다.
  • 기존 페이지와의 경계 정리: 요약은 월중 운영 허브, 자산/마감은 자산 snapshot 작업장, 월정산은 월말 검토·결산·마감 orchestration 페이지로 구분한다.

영향 범위

  • 코드 영향:
    • dashboard/app.py: sidebar/page routing에 월정산 추가, 신규 page_monthly_settlement 또는 별도 모듈화 검토
    • jarca_ledger_mcp.adapters.streamlit.*_gateway: 기존 monthly cashflow, budget, asset, reconciliation, review/import gateway 재사용 또는 settlement gateway 신설
    • jarca_ledger_mcp.application.*: 월정산 summary read model이 필요하면 application service 추가
    • DB: 월정산 close 상태를 영속화할 경우 additive table 또는 existing snapshot/session reuse 필요
  • 문서 영향:
    • docs/data-model.md: 월정산 close 상태/summary 영속화가 생길 경우 반영
    • docs/project-structure.md: 월정산 page/gateway/service 책임 추가
    • docs/runtime-flows.md: 월정산 preview/review/close 흐름 추가
    • docs/interface-contract.md: MCP/agent-facing monthly settlement summary tool이 생길 경우 반영
  • 운영 영향:
    • 월말 운영 절차가 “미해결 항목 정리 → 월정산 preview → close/evidence 기록 → 다음 달 action”으로 표준화될 수 있다.

5. 요구사항 목록

기능 요구사항 초안

  • FR-1: 월정산 페이지는 대상 월을 선택할 수 있어야 하며 기본값은 KST 현재 월이다. 과거 월 조회도 가능해야 한다.
  • FR-2: 상단 Summary 섹션은 대상 월의 실제 수입, 실제 지출, 순현금흐름, 저축률, 예산 초과 항목 수, 미해결 blocker 수를 표시해야 한다.
  • FR-3: 현금흐름/지출 분석 섹션은 카테고리별·가족 구성원별·고정비/변동비 기준의 월간 지출 구조를 보여주고, 기존 get_monthly_cashflow_report 및 budget report와 일관된 정의를 사용해야 한다.
  • FR-4: 예산 대비 섹션은 월 예산, 실제 지출, 잔여/초과, 사용률, 초과 항목을 표시하고 상세 조정 페이지로 이동할 단서를 제공해야 한다.
  • FR-5: 정산 전 검토 섹션은 미분류 거래, 확인필요 큐, 보류/재검토, 잔액대조 필요 계좌, import batch 확인 필요, last_balance 누락 항목을 blocker로 표시해야 한다.
  • FR-6: 자산/마감 섹션은 대상 월 기준 자산 snapshot preview/closed 여부, 자산 합계, 총부채, 순자산, 직전 월 대비 변화량을 표시해야 한다.
  • FR-7: 월정산 close가 이번 범위에 포함될 경우, close는 preview-first, explicit confirmation, append-only/correction evidence 원칙을 따라야 한다.
  • FR-8: 월정산 완료 후 최총무/finance agent가 사용할 수 있는 구조화 summary를 제공해야 한다. MCP tool 추가 여부는 REQ 단계에서 결정한다.
  • FR-9: dashboard AppTest/HTTP smoke 및 browser evidence는 월정산 페이지 핵심 섹션 렌더링을 포함해야 한다.

와이어프레임 수준 섹션 설계안

  1. Header / 월 선택

    • 제목: 월정산
    • 컨트롤: 대상 월 선택, 새로고침, 정산 상태 badge(초안, 검토 필요, 마감 가능, 마감 완료)
    • 보조 정보: DB path/schema version, 기준 시간(KST)

  2. 월간 핵심 KPI

    • 실제 수입, 실제 지출, 순현금흐름, 저축률
    • 예산 초과 항목 수, 미해결 blocker 수
    • 전월 대비 변화량은 가능하면 표시하되, 데이터 정의가 불명확하면 후속 범위로 둔다.

  3. 현금흐름 / 지출 구조

    • 카테고리 Top N
    • 가족 구성원/person별 지출
    • 고정비/변동비 또는 cashflow_kind별 구성
    • 상세 거래 필터로 이동하는 단서

  4. 예산 대비 점검

    • 예산 항목 table: category/subcategory/person, budget, actual, remaining, usage rate, status
    • 초과/임박 항목 강조

  5. 정산 전 검토 Blocker

    • 미분류 거래 수
    • 확인필요 큐 pending/held/recheck
    • 잔액대조 필요 계좌
    • import batch 최신성/확인 필요
    • last_balance 누락 자산/부채
    • 각 항목은 상세 페이지 링크/메뉴 안내/CTA를 갖는다.

  6. 자산 / 순자산 마감 상태

    • asset snapshot preview/closed 상태
    • 자산 합계, 총부채, 순자산
    • manual_assets 또는 accounts.last_balance source coverage
    • snapshot close CTA는 기존 자산/마감 정책과 충돌하지 않도록 자산/마감 페이지로 이동하거나, 동일 service를 재사용한다.

  7. 월정산 결과 / Evidence

    • close 가능 조건 pass/fail
    • close 실행 시점, operator, source summary
    • correction 필요 시 append-only correction 흐름
    • 월정산 report export는 후속 옵션으로 둔다.

  8. 다음 액션

    • 다음 달 예산 조정 후보
    • 반복되는 미분류/확인필요 rule 후보
    • 잔액대조/backup/import follow-up

비기능 요구사항

  • NFR-1: 월정산 페이지의 계산 기준은 기존 service/application layer 정의를 재사용해야 하며, dashboard 내부에서 별도 산식을 중복 구현하지 않는다.
  • NFR-2: 운영 DB write는 preview/explicit close/correction flow 없이 발생하면 안 된다.
  • NFR-3: synthetic fixture DB 기반 AppTest/HTTP smoke에서 월정산 페이지가 안정적으로 렌더링되어야 한다.
  • NFR-4: agent-facing summary를 제공할 경우 raw financial evidence나 import 원본 payload를 노출하지 않고 REQ-021 provenance/sensitive-data policy를 따른다.

범위 경계

  • In Scope:
    • 월정산 페이지의 기능 요구사항 정의
    • 와이어프레임 수준 섹션 설계
    • 기존 요약, 자산/마감, 확인필요 큐, 미분류, Import와의 경계 정의
    • 구현 REQ로 넘길 acceptance criteria 초안
  • Out of Scope:
    • 즉시 코드 구현
    • 외부 금융기관 자동 잔액 동기화
    • 세무/법률 회계 리포트
    • PDF/Excel export의 최종 양식 확정
    • Project 4 item status 변경. board field 조작은 이번 Discovery 범위가 아니며 별도 evidence/권한이 필요

6. 리스크/가정 목록

리스크

  • R-1 (Medium): 월정산이 기존 요약/자산/마감 기능을 단순 중복하면 화면 복잡도만 늘어날 수 있다.
    • 완화: 요약은 월중 운영 허브, 월정산은 월말 검토·마감 orchestration으로 책임을 분리한다.
  • R-2 (High): 월정산 close를 새로 영속화할 경우 기존 asset snapshot close와 이중 마감 상태가 생길 수 있다.
    • 완화: REQ 단계에서 월정산 close를 read-only checklist로 둘지, 별도 monthly_settlements 상태로 둘지 명확히 결정한다.
  • R-3 (Low): GitHub Project 4의 board 상태/field metadata는 현재 Project API scope 부족으로 직접 확인하지 못했다.
    • 완화: 요구사항 본문은 repo issue #3/#4에서 확인했으며, Project field 상태가 필요할 때만 read:project scope를 복구한다.
  • R-4 (Medium): 월정산 summary가 finance agent 입력으로 사용될 경우 privacy/sensitive boundary를 잘못 잡으면 raw evidence 노출 위험이 있다.
    • 완화: REQ-021 minimal/operator-summary/debug-gated policy를 그대로 적용한다.

가정

  • A-1: “월정산”은 회계/세무 공식 결산이 아니라 가계 운영용 월간 마감·검토·요약 workflow를 뜻한다.
  • A-2: 기본 대상 월은 KST 기준 현재 월이며, 집계 기준은 기존 monthly cashflow와 동일하게 transactions.transaction_date다.
  • A-3: 월정산 페이지는 Streamlit dashboard의 신규 page로 시작하고, MCP/agent-facing tool은 필요성이 확인되면 REQ 또는 후속 범위로 분리한다.
  • A-4: 월정산 close가 포함될 경우 기존 snapshot close와 동일하게 append-only/correction 원칙을 따른다.

오픈 질문

  • OQ-1: 월정산 close 상태를 영속화할 것인가, 아니면 read-only checklist/report 페이지로 시작할 것인가?
    • 상태: Open
    • 처리 방안: REQ 초안 전 사용자/최총무 확인 필요
    • 종료 조건: monthly_settlements 같은 신규 table 필요 여부가 결정된다.
  • OQ-2: 월정산 결과를 finance agent/MCP tool로 제공해야 하는가?
    • 상태: Open
    • 처리 방안: 최총무 운영 방식 확인 후 Interface 범위에 포함 여부 결정
    • 종료 조건: dashboard-only 또는 dashboard+MCP 범위가 확정된다.
  • OQ-3: 월정산 export(PDF/Excel/Markdown)까지 이번 범위에 포함할 것인가?
    • 상태: Deferred
    • 처리 방안: 1차 페이지 구현 이후 후속 Discovery/REQ 후보로 둔다.
    • 종료 조건: export 형식과 소비자가 확정된다.

7. 초기 성공 기준

  • S-1: 월정산 페이지의 섹션 순서와 각 섹션의 표시 지표/CTA가 REQ 작성 가능한 수준으로 확정된다.
  • S-2: 기존 구현과 중복되는 부분과 새로 필요한 read model/close state가 분리되어 구현 범위가 명확해진다.
  • S-3: GitHub issue #3/#4 본문과 Discovery 초안의 gap이 정리된다.
  • S-4: 승인 후 REQ는 dashboard-only 1차 구현인지, dashboard+MCP+영속 close state 구현인지 결정 가능한 상태가 된다.

측정 방식 및 데이터 출처

  • S-1 측정 방식: Discovery/REQ 리뷰에서 섹션별 AC 도출 가능 여부 확인 / 데이터 출처: 본 Discovery, dashboard/app.py 현 구현
  • S-2 측정 방식: 영향을 받는 modules/docs 목록과 out-of-scope 항목 검토 / 데이터 출처: docs/project-structure.md, docs/runtime-flows.md, existing REQ-005/REQ-012/REQ-020
  • S-3 측정 방식: GitHub issue #3/#4 title/body 비교 / 데이터 출처: genichin/jarca-ledger-mcp issue #3/#4
  • S-4 측정 방식: 사용자 결정 항목 OQ-1/OQ-2 해소 여부 / 데이터 출처: 사용자/최총무 확인

8. REQ로 넘기기 전 확인 체크

  • 최총무가 등록한 두 GitHub issue 본문 확인
    • 기준: repo issue #3/#4를 gh issue view로 확인 완료
  • 월정산 close 영속화 여부 결정
    • 기준: read-only page vs persistent monthly settlement state
  • MCP/finance-agent-facing summary 포함 여부 결정
    • 기준: dashboard-only vs dashboard+MCP
  • export 범위 포함 여부 결정
    • 기준: 1차 범위 포함 또는 후속 Deferred
  • 최총무/사용자 승인
    • 기준: 기능 요구사항과 와이어프레임 섹션 설계안 승인

9. 파일 처리 결과

  • 처리 결과: 생성
  • 생성 경로: docs/discovery/dcy-015_20260711_monthly-settlement-page-requirements-wireframe.md
  • 참조 문서:
    • docs/discovery/dcy-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow.md
    • docs/discovery/dcy-009_20260701_manual-asset-crud-month-end-snapshot-close-workflow.md
    • docs/srs/Interface/req-005_dashboard-operations-hub-liquidity-monthly-cashflow.md
    • docs/srs/Interface/req-012_manual-asset-crud-snapshot-close-mcp-and-operator-dashboard-alignment.md
    • docs/srs/Interface/req-020_review-decision-persistence-reconciliation-workbench.md
    • dashboard/app.py
    • docs/project-structure.md
    • docs/runtime-flows.md

10. 사용자 결정 필요 항목 요약

DECIDE

  • {{DECIDE_MONTHLY_SETTLEMENT_CLOSE_STATE}}: 월정산 close 상태를 영속화할지, read-only checklist/report page로 시작할지 결정한다.
  • {{DECIDE_MONTHLY_SETTLEMENT_MCP_SCOPE}}: 최총무/finance agent가 소비할 MCP monthly settlement summary tool을 이번 범위에 포함할지 결정한다.

CONFIRM

  • {{CONFIRM_WIREFRAME_SECTION_ORDER}}: Header, KPI, 현금흐름/지출, 예산, blocker, 자산/마감, evidence, 다음 액션 섹션 순서를 승인한다.

DATA

  • {{DATA_MONTHLY_SETTLEMENT_EXPORT_NEED}}: PDF/Excel/Markdown export 필요 여부와 소비자를 확인한다.

11. Discovery Freeze

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

섹션 참조

Freeze 플래그

  • Handoff Decision: 보류
  • Handoff Rationale: 초기 Discovery 초안 생성 및 GitHub issue #3/#4 본문 확인 완료. 월정산 close/MCP 범위 결정 후 REQ 초안 작성 가능.
  • Ready for REQ Drafting: false
  • Confirmed By: 없음
  • Confirmed At (KST): 없음
View Git Blame Copy Permalink