# 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: c0580f7173bd3dd618e6fff0104e3f26a0d0dec9
- 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.