jarca-ledger-mcp/docs/discovery/dcy-015_20260711_monthly-settlement-page-requirements-wireframe.md

# 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 참조:
  - REQ-022 (`docs/srs/Interface/req-022_monthly-settlement-read-model-foundation.md`)
  - REQ-023 (`docs/srs/Interface/req-023_monthly-settlement-dashboard-shell-kpi-cashflow-budget.md`)
  - REQ-024 (`docs/srs/Interface/req-024_monthly-settlement-operational-blockers-import-account-asset-status.md`)
  - REQ-025 (`docs/srs/Interface/req-025_monthly-settlement-evidence-next-actions-verification-hardening.md`)
- 요청 출처: 최총무가 등록한 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로 시작하고, 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로 넘기기 전 확인 체크

- [x] 최총무가 등록한 두 GitHub issue 본문 확인
  - 기준: repo issue #3/#4를 `gh issue view`로 확인 완료
- [x] 월정산 close 영속화 여부 결정
  - 기준: 1차 범위에서는 영속화하지 않고 read-only checklist/report 페이지로 시작
- [x] MCP/finance-agent-facing summary 포함 여부 결정
  - 기준: 1차 범위에서는 제외하되 내부 summary read model은 후속 MCP 확장 가능하게 설계
- [x] export 범위 포함 여부 결정
  - 기준: PDF/Excel/Markdown export는 후속 범위로 분리
- [x] 최총무/사용자 승인
  - 기준: 기능 요구사항과 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. 요구사항 목록](#5-요구사항-목록)
- 리스크/오픈 질문: [# 6. 리스크/가정 목록](#6-리스크가정-목록)
- 성공 기준: [# 7. 초기 성공 기준](#7-초기-성공-기준)
- 인계 전 확인: [# 8. REQ로 넘기기 전 확인 체크](#8-req로-넘기기-전-확인-체크)
- 사용자 결정 필요: [# 10. 사용자 결정 필요 항목 요약](#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: Justin Ko
- Confirmed At (KST): 2026-07-11 14:30 KST

## Approval Correction
- 2026-07-11 14:30 KST: 사용자 지시에 따라 Discovery 승인자를 `Justin Ko`로 정정했다.

## REQ Split Correction
- 2026-07-11 20:56 KST: 사용자 지시에 따라 기존 umbrella `REQ-022 Monthly settlement read-only dashboard`를 삭제하고, dcy-015 범위를 REQ-022~REQ-025 네 개의 작은 REQ로 재분해했다. 분해 이유는 월정산 페이지 1차 범위가 read model, dashboard shell, operational blocker/status, evidence/verification hardening으로 나뉘는 큰 작업이며, 기존 단일 REQ delivery가 implementation worker context-compaction stall로 blocked 되었기 때문이다.