jarca-ledger-mcp/docs/srs/Interface/req-022_monthly-settlement-read-model-foundation.md

REQ-022 Monthly settlement read-model foundation

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

1. Intent

Build the internal read-only monthly settlement summary model that later dashboard slices can consume without duplicating formulas in Streamlit UI code.

2. In Scope

• Parse and validate a target month in YYYY-MM form.
• Compute the selected month basis date as the KST month end.
• Add an application/service-layer read model for monthly settlement summary.
• Reuse existing monthly cashflow, budget, uncategorized/review, account/import, and asset snapshot services where available.
• Return a structured summary with at least:
  • selected month and basis date
  • actual income, actual expense, net cashflow, savings rate
  • budget overrun count
  • unresolved blocker count skeleton
  • source coverage/status fields needed by later UI slices
• Add focused tests for month parsing, basis date, empty/synthetic DB behavior, and core summary shape.

3. Out of Scope

• Streamlit 월정산 page or routing.
• Detailed blocker/import/account/asset section UI.
• Monthly close persistence, monthly_settlements table, transaction locks, MCP tool, or export.

4. Acceptance Criteria

• AC-1: A service/application entrypoint returns a deterministic monthly settlement summary for a selected month.
• AC-2: Invalid month input fails with a clear validation error or documented fallback.
• AC-3: Basis date is the selected month end under KST assumptions.
• AC-4: KPI values reuse existing service definitions rather than dashboard-local formulas.
• AC-5: The returned model is suitable for later Streamlit and MCP extension without exposing raw import payloads or raw local paths.
• AC-6: Focused automated tests cover summary shape and at least one synthetic fixture result.
• AC-7: python -m ruff check . and the relevant pytest slice pass.

5. Notes

This REQ is the foundation slice split out of the deleted umbrella REQ-022 Monthly settlement read-only dashboard.

6. Approval Notes

• 2026-07-11 21:05 KST: Lead approval after user directed continued progression from the dcy-015 split. This first slice is approved independently because it is the foundation read model and does not introduce Streamlit UI, close persistence, MCP tools, or export side effects.

Implementation Evidence

• PR: https://github.com/genichin/jarca-ledger-mcp/pull/5
• Merge commit: c0580f7173
• Validation: local pytest -q tests/test_service.py, local ruff check ., local pytest -q, and PR CI all passed.
• Scope note: Implemented read-model foundation only; UI/MCP/export/close persistence remain excluded.