gitea-impl-agent/jarca-ledger-mcp

Fork 0

forked from jsfamily/jarca-ledger-mcp

Files

T

Jarca 6c67b0427c docs: confirm monthly settlement discovery scope

2026-07-11 14:31:28 +09:00

20 KiB

Raw Blame History

0. 문서 상태

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

상태: confirmed
문서 ID: dcy-015_20260711_monthly-settlement-page-requirements-wireframe
이슈명: 월정산 페이지 기능 요구사항 및 와이어프레임 수준 섹션 설계
작성 시각(KST): 2026-07-11 10:48 KST
마지막 갱신 시각(KST): 2026-07-11 14:30 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는 월정산 페이지 핵심 섹션 렌더링을 포함해야 한다.

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

Header / 월 선택
- 제목: 월정산
- 컨트롤: 대상 월 선택, 새로고침, 정산 상태 badge(초안, 검토 필요, 마감 가능, 마감 완료)
- 보조 정보: DB path/schema version, 기준 시간(KST)
월간 핵심 KPI
- 실제 수입, 실제 지출, 순현금흐름, 저축률
- 예산 초과 항목 수, 미해결 blocker 수
- 전월 대비 변화량은 가능하면 표시하되, 데이터 정의가 불명확하면 후속 범위로 둔다.
현금흐름 / 지출 구조
- 카테고리 Top N
- 가족 구성원/person별 지출
- 고정비/변동비 또는 cashflow_kind별 구성
- 상세 거래 필터로 이동하는 단서
예산 대비 점검
- 예산 항목 table: category/subcategory/person, budget, actual, remaining, usage rate, status
- 초과/임박 항목 강조
정산 전 검토 Blocker
- 미분류 거래 수
- 확인필요 큐 pending/held/recheck
- 잔액대조 필요 계좌
- import batch 최신성/확인 필요
- last_balance 누락 자산/부채
- 각 항목은 상세 페이지 링크/메뉴 안내/CTA를 갖는다.
자산 / 순자산 마감 상태
- asset snapshot preview/closed 상태
- 자산 합계, 총부채, 순자산
- manual_assets 또는 accounts.last_balance source coverage
- snapshot close CTA는 기존 자산/마감 정책과 충돌하지 않도록 자산/마감 페이지로 이동하거나, 동일 service를 재사용한다.
월정산 결과 / Evidence
- close 가능 조건 pass/fail
- close 실행 시점, operator, source summary
- correction 필요 시 append-only correction 흐름
- 월정산 report export는 후속 옵션으로 둔다.
다음 액션
- 다음 달 예산 조정 후보
- 반복되는 미분류/확인필요 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로 시작하고, 1차 범위에서는 MCP/finance-agent-facing tool을 제외한다. 다만 내부 summary read model은 후속 MCP 확장이 가능하도록 service boundary를 유지한다.
A-4: 1차 범위에서는 월정산 close 상태를 별도 영속화하지 않고 read-only checklist/report 페이지로 시작한다. asset snapshot close는 기존 자산/마감 정책과 service를 재사용하며, 월정산 close 영속화는 후속 REQ 후보로 둔다.
A-5: PDF/Excel/Markdown export는 1차 범위에서 제외하고 후속 범위로 둔다.

오픈 질문

OQ-1: 월정산 close 상태를 영속화할 것인가, 아니면 read-only checklist/report 페이지로 시작할 것인가?
- 상태: Answered
- 처리 방안: 1차 범위에서는 월정산 close 상태를 영속화하지 않고 read-only checklist/report 페이지로 시작한다. 별도 monthly_settlements table이나 월정산 lock/close 엔티티는 만들지 않는다.
- 종료 조건: REQ 초안에서 dashboard read-only checklist/report 범위와 close 영속화 제외가 명시되면 완료.
OQ-2: 월정산 결과를 finance agent/MCP tool로 제공해야 하는가?
- 상태: Answered
- 처리 방안: 1차 범위에서는 MCP/finance-agent summary tool을 제외한다. 내부 summary read model은 후속 MCP 확장이 가능하도록 application/service boundary를 유지한다.
- 종료 조건: REQ 초안에서 dashboard-only 1차 범위와 MCP 후속 확장 가능성이 명시되면 완료.
OQ-3: 월정산 export(PDF/Excel/Markdown)까지 이번 범위에 포함할 것인가?
- 상태: Deferred
- 처리 방안: PDF/Excel/Markdown export는 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 read-only checklist/report 1차 구현으로 작성 가능하며, MCP/export/close 영속화는 후속 범위로 분리된다.

측정 방식 및 데이터 출처

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 측정 방식: 사용자 승인 내용이 REQ 범위 경계에 반영됐는지 확인 / 데이터 출처: 사용자 승인, 본 Discovery

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

최총무가 등록한 두 GitHub issue 본문 확인
- 기준: repo issue #3/#4를 gh issue view로 확인 완료
월정산 close 영속화 여부 결정
- 기준: 1차 범위에서는 영속화하지 않고 read-only checklist/report 페이지로 시작
MCP/finance-agent-facing summary 포함 여부 결정
- 기준: 1차 범위에서는 제외하되 내부 summary read model은 후속 MCP 확장 가능하게 설계
export 범위 포함 여부 결정
- 기준: PDF/Excel/Markdown export는 후속 범위로 분리
최총무/사용자 승인
- 기준: 기능 요구사항과 8개 와이어프레임 섹션 설계안 승인

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

월정산 close 상태: 1차 범위에서는 영속화하지 않고 read-only checklist/report 페이지로 시작한다.
MCP/finance-agent summary tool: 1차 범위에서는 제외한다. 단, 내부 summary read model은 후속 MCP 확장 가능하게 설계한다.

CONFIRM

와이어프레임 섹션 순서: Header, KPI, 현금흐름/지출, 예산, blocker, 자산/마감, evidence, 다음 액션의 8개 순서를 승인한다.

DATA

PDF/Excel/Markdown export: 후속 범위로 둔다.

11. Discovery Freeze

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

섹션 참조

범위: # 5. 요구사항 목록
리스크/오픈 질문: # 6. 리스크/가정 목록
성공 기준: # 7. 초기 성공 기준
인계 전 확인: # 8. REQ로 넘기기 전 확인 체크
사용자 결정 필요: # 10. 사용자 결정 필요 항목 요약

Freeze 플래그

Handoff Decision: 승인
Handoff Rationale: GitHub issue #3/#4 본문 확인 및 사용자 승인으로 1차 범위가 dashboard read-only checklist/report로 확정되었다. 월정산 close 영속화, MCP/finance-agent summary tool, PDF/Excel/Markdown export는 후속 범위로 분리하고, 8개 와이어프레임 섹션 순서를 REQ 입력으로 사용한다.
Ready for REQ Drafting: true
Confirmed By: 진환 고
Confirmed At (KST): 2026-07-11 14:30 KST

20 KiB Raw Blame History