From 9c52e0731c42671b9dfd39765dd82d3100157414 Mon Sep 17 00:00:00 2001 From: Jarca Date: Sat, 11 Jul 2026 10:51:03 +0900 Subject: [PATCH] docs: draft monthly settlement page discovery --- ...-settlement-page-requirements-wireframe.md | 270 ++++++++++++++++++ docs/discovery/index.md | 1 + 2 files changed, 271 insertions(+) create mode 100644 docs/discovery/dcy-015_20260711_monthly-settlement-page-requirements-wireframe.md diff --git a/docs/discovery/dcy-015_20260711_monthly-settlement-page-requirements-wireframe.md b/docs/discovery/dcy-015_20260711_monthly-settlement-page-requirements-wireframe.md new file mode 100644 index 0000000..eb79c0e --- /dev/null +++ b/docs/discovery/dcy-015_20260711_monthly-settlement-page-requirements-wireframe.md @@ -0,0 +1,270 @@ +# 0. 문서 상태 +이 문서의 현재 상태와 식별 정보를 기록한다. 문서 추적과 승인 흐름에 필요한 최소 메타데이터를 적는다. + +- 상태: draft +- 문서 ID: dcy-015_20260711_monthly-settlement-page-requirements-wireframe +- 이슈명: 월정산 페이지 기능 요구사항 및 와이어프레임 수준 섹션 설계 +- 작성 시각(KST): 2026-07-11 10:48 KST +- 마지막 갱신 시각(KST): 2026-07-11 10:48 KST +- 대체됨: 없음 +- 후속 Discovery 참조: 없음 +- 생성된 REQ 참조: 없음 +- 요청 출처: 최총무 요청으로 전달된 Project 4 항목 제목 `[Feature] 월정산 페이지 기능 요구사항 정의`, `[Design] 월정산 페이지 와이어프레임 수준 섹션 설계안` +- Project 4 확인 상태: GitHub CLI token에 `read:project` scope가 없어 Project item 본문/상태 확인은 blocked. 사용자가 전달한 두 제목을 기준 입력으로 사용한다. + +# 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 + - 관련 Project 4 항목: 제목은 전달받았으나 Project API scope 부족으로 본문/상태 미확인 +- 해석: + - 기존 `요약`과 `자산/마감` 화면은 월중 운영 현황과 자산 스냅샷 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와 명시적 확정 단계를 분리해야 한다. + - Project 4 상세 본문은 현재 `read:project` scope 부족으로 확인되지 않았으므로, 본 Discovery는 전달받은 제목과 repo 상태 기반 초안이다. + +## 주요 사용자 시나리오 + +- 사용자가 월말에 `월정산` 페이지를 열어 대상 월을 선택하고, 수입/지출/저축률/예산 초과/순자산 변동을 먼저 확인한다. +- 사용자가 마감 전 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 변경. 현재 token scope 부족으로 보드 상태 확인 불가 + +# 6. 리스크/가정 목록 + +## 리스크 + +- R-1 (Medium): `월정산`이 기존 `요약`/`자산/마감` 기능을 단순 중복하면 화면 복잡도만 늘어날 수 있다. + - 완화: `요약`은 월중 운영 허브, `월정산`은 월말 검토·마감 orchestration으로 책임을 분리한다. +- R-2 (High): 월정산 close를 새로 영속화할 경우 기존 asset snapshot close와 이중 마감 상태가 생길 수 있다. + - 완화: REQ 단계에서 월정산 close를 read-only checklist로 둘지, 별도 `monthly_settlements` 상태로 둘지 명확히 결정한다. +- R-3 (Medium): 최총무가 요청한 Project item 본문에 추가 조건이 있을 수 있으나 현재 Project API scope 부족으로 확인하지 못했다. + - 완화: GitHub token `read:project` scope 복구 후 Project item 본문을 재확인하고 Discovery를 보강한다. +- 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: Project 4 item 본문을 확인한 뒤 최총무 요청사항과 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 측정 방식: `read:project` scope 복구 후 Project 4 item title/body 비교 / 데이터 출처: GitHub Project 4 +- S-4 측정 방식: 사용자 결정 항목 OQ-1/OQ-2 해소 여부 / 데이터 출처: 사용자/최총무 확인 + +# 8. REQ로 넘기기 전 확인 체크 + +- [ ] Project 4 두 항목의 본문/상태 확인 + - 기준: GitHub CLI token에 `read:project` scope가 있어야 함 +- [ ] 월정산 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_PROJECT4_ITEM_BODY}}`: Project 4의 `[Feature]`, `[Design]` 항목 본문/상태를 확인해 본 Discovery 초안과 차이를 검토한다. +- `{{CONFIRM_WIREFRAME_SECTION_ORDER}}`: Header, KPI, 현금흐름/지출, 예산, blocker, 자산/마감, evidence, 다음 액션 섹션 순서를 승인한다. + +## DATA +- `{{DATA_MONTHLY_SETTLEMENT_EXPORT_NEED}}`: 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: 초기 Discovery 초안 생성 완료. Project 4 item 본문 확인과 월정산 close/MCP 범위 결정 후 REQ 초안 작성 가능. +- Ready for REQ Drafting: false +- Confirmed By: 없음 +- Confirmed At (KST): 없음 diff --git a/docs/discovery/index.md b/docs/discovery/index.md index 6710a47..8aed1be 100644 --- a/docs/discovery/index.md +++ b/docs/discovery/index.md @@ -20,3 +20,4 @@ | dcy-012_20260703_review-queue-reconciliation-workbench-persistence | 20260703 | 확인필요 큐 / 잔액대조 워크벤치 영속화 및 운영 모델 정립 | [Discovery](./dcy-012_20260703_review-queue-reconciliation-workbench-persistence.md) | confirmed | | dcy-013_20260707_docker-network-mcp-deployment | 20260707 | Jarca Ledger 독립 Docker 배포 및 network MCP endpoint 제공 | [Discovery](./dcy-013_20260707_docker-network-mcp-deployment.md) | confirmed | | dcy-014_20260708_import-provenance-sensitive-data-policy | 20260708 | Import provenance 및 민감자료 저장 정책 정리 | [Discovery](./dcy-014_20260708_import-provenance-sensitive-data-policy.md) | confirmed | +| dcy-015_20260711_monthly-settlement-page-requirements-wireframe | 20260711 | 월정산 페이지 기능 요구사항 및 와이어프레임 수준 섹션 설계 | [Discovery](./dcy-015_20260711_monthly-settlement-page-requirements-wireframe.md) | draft |