chore(jarca-ledger): finalize approved batch docs, dashboard, and CI smoke updates

docs/srs/Interface/req-003_statement-unavailable-manual-evidence-balance-reconciliation.md

@@ -0,0 +1,80 @@
+# REQ-003 Statement-unavailable 계좌 수동 증빙 및 잔액대조
+
+- Status: Implemented
+- Type: Interface
+- Priority: High
+- Owner: 렛저장인
+- Source Discovery: `docs/discovery/dcy-003_20260629_statement-unavailable-manual-evidence-balance-reconciliation.md`
+- Batch: `docs/batches/bat-003_20260629_statement-unavailable-reconciliation/`
+- Created At (KST): 2026-06-29
+- Implemented At (KST): 2026-06-29
+
+## 1. 배경
+
+거래내역 파일이 없거나 일부 기간만 import 가능한 계좌는 기존 statement import 흐름만으로 정합성을 보장할 수 없다. dcy-003 confirmed Discovery에 따라 계좌별 statement 지원 상태를 명시하고, 수동 실행 가능한 잔액대조 report 및 계좌 화면의 최소 UI를 제공한다.
+
+## 2. 범위
+
+### In Scope
+- `accounts.statement_status` 필드 추가 및 서비스 검증.
+- 허용값: `unknown`, `import_supported`, `manual_only`, `partial_import`.
+- `manual_only`는 statement-unavailable 계좌로 정의한다.
+- `partial_import`도 수동 보완 및 잔액대조 대상에 포함한다.
+- 기준 잔액 입력 포맷: `account_id`, `statement_status`, `baseline_balance`, `baseline_at`, `source_note`, `memo`.
+- 수동 실행 잔액대조 report: 계산 잔액, 차액, 허용 오차, 0.1% 참고 비율, `OK`/`REVIEW_NEEDED`/`BASELINE_REQUIRED` 상태.
+- 계좌 화면의 `statement_status` 표시/수정 및 최소 잔액대조 결과 표시.
+- MCP tool surface에 계좌 update 및 잔액대조 report를 additive로 노출.
+- dcy-002 백업/검증 DB 절차 선행 원칙 문서화.
+
+### Out of Scope
+- 자동 스케줄링/알림.
+- 전용 잔액대조 워크벤치 전체 신설.
+- 사용자 승인 없는 restore 실행 또는 restore MCP tool 노출.
+- 자동 확정형 확인필요 라우팅 mutation. 이번 구현은 preview/report 중심이며 수동 확정을 전제로 한다.
+
+## 3. 기능 요구사항
+
+### FR-1. 계좌 statement 상태
+- `accounts.statement_status`는 `TEXT NOT NULL DEFAULT 'unknown'`이어야 한다.
+- 서비스 계층은 허용값 외 입력을 `validation_error`로 거부해야 한다.
+- `create_ledger_account`, `list_ledger_accounts`, `update_ledger_account`에서 해당 필드를 사용할 수 있어야 한다.
+
+### FR-2. 잔액대조 입력 및 기준 시각
+- 잔액대조 입력은 다음 포맷을 지원해야 한다.
+  - `account_id`: 선택. 비어 있으면 `manual_only`, `partial_import` 활성 계좌 전체를 대상으로 한다.
+  - `baseline_balance`: 선택. 없으면 계좌의 `last_balance`를 사용한다.
+  - `baseline_at`: 선택. `YYYY-MM`이면 해당 월 말일 `23:59:00+09:00`, `YYYY-MM-DD`이면 해당일 `23:59:00+09:00`, ISO datetime이면 원문 기준으로 정규화 검증한다.
+  - `source_note`, `memo`: 선택 메타데이터. 원문 증빙이나 민감 식별자는 저장·출력하지 않는다.
+- 정기 대조 기준은 매월 말일 23:59 KST이며, 수시 대조는 사용자 입력 스냅샷 시각을 사용한다.
+
+### FR-3. 잔액대조 판정
+- 계산 잔액은 우선 `transactions.balance_after`의 최신 값을 사용하고, 없으면 기준 시점까지의 계좌 거래 순증감을 사용한다.
+- 차액은 `baseline_balance - calculated_balance`로 산출한다.
+- 초기 허용 오차는 절대 금액 1,000원이다.
+- `abs(difference) <= 1000`이면 `OK`, 초과하면 `REVIEW_NEEDED`로 표시한다.
+- 기준 잔액 대비 0.1%는 `difference_ratio`와 `reference_ratio_threshold=0.001`로 참고 표시만 하고 판정에는 사용하지 않는다.
+
+### FR-4. 확인필요 후보 판정값
+- `REVIEW_NEEDED` 결과는 다음 수동 판정 후보를 제시해야 한다: `계좌이동`, `실지출`, `실수입`, `투자이동`, `분석제외`, `확인필요`.
+- 자동 확정이 아닌 후보 제시/수동 확정을 기본으로 한다.
+
+### FR-5. 운영 안전
+- 운영 DB 변경 전 dcy-002 백업은 필수다.
+- 검증 DB에서 preview/reconcile을 먼저 수행한다.
+- restore는 사용자 명시 승인 없이 실행하지 않는다.
+
+## 4. Acceptance Criteria
+
+- AC-1: 새 DB 및 기존 DB migration 후 `accounts.statement_status`가 존재하고 기본값은 `unknown`이다.
+- AC-2: 잘못된 `statement_status`로 계좌 생성/수정 시 `validation_error`가 반환된다.
+- AC-3: `manual_only` 또는 `partial_import` 계좌에 대해 잔액대조 report가 `baseline_balance`, `calculated_balance`, `difference`, `tolerance=1000`, `difference_ratio`, `status`를 반환한다.
+- AC-4: 차액이 1,000원 이내면 `OK`, 초과면 `REVIEW_NEEDED`이며 확인필요 후보 판정값 6개가 표시된다.
+- AC-5: dashboard 계좌 화면에서 `statement_status`를 확인/수정하고 최소 잔액대조 report를 실행할 수 있다.
+- AC-6: MCP tool로 `update_ledger_account`, `get_balance_reconciliation_report`가 additive 노출된다.
+- AC-7: data model, interface contract, runtime flow, runbook 문서가 dcy-003 범위를 반영한다.
+
+## 5. 구현 메모
+
+- Schema version은 `7`로 올린다.
+- 잔액대조는 현재 preview/report만 수행하며 transaction/category mutation은 하지 않는다.
+- 대조 기준 잔액 실제 값은 운영 시점에 사용자가 입력한다.

docs/srs/Interface/req-005_dashboard-operations-hub-liquidity-monthly-cashflow.md

@@ -0,0 +1,93 @@
+# REQ-005 Dashboard operations hub/liquidity/monthly cashflow
+
+- Status: Approved
+- Type: Interface
+- Priority: High
+- Owner: 렛저장인
+- Source Discovery: `docs/discovery/dcy-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow.md`
+- Batch: BAT-005
+- Created At (KST): 2026-06-29
+- Approved At (KST): 2026-06-29 21:08 KST
+
+## 1. 배경
+
+현재 Streamlit 대시보드 첫 화면은 전체 기간 누적 현금흐름과 계좌 입출금 중심으로 구성되어 있어, 운영자가 월중에 필요한 "이번 달 수입/지출 현황", "현재 자산 유동성", "미처리 운영 경고"를 한 화면에서 즉시 판단하기 어렵다. dcy-005 confirmed Discovery에 따라 대시보드 첫 화면을 운영 허브로 재정의하고, 계좌 단위 `liquidity_bucket` 축을 도입해 자산 유동성/구성/순자산 계산을 일관되게 제공한다.
+
+## 2. 범위
+
+### In Scope
+- `page_overview`를 다음 우선순위 섹션으로 재구성한다: ① 이번 달 수입/지출 현황 ② 자산 유동성 현황 ③ 자산 구성 ④ 지출 구조/예산 ⑤ 운영 경고.
+- 이번 달 수입/지출 현황은 KST 현재 월의 `transaction_date` 기준으로 실제 수입, 실제 지출, 순현금흐름, 저축률을 표시한다.
+- 자산 유동성 현황은 계좌 단위 `accounts.liquidity_bucket` 값을 기준으로 `cash`, `investment`, `deposit`, `real_estate`, `loan`, `other` 버킷별 금액과 비율을 표시한다.
+- `accounts.liquidity_bucket`은 additive/idempotent schema migration으로 도입하고, 미지정 계좌는 `other`로 폴백한다.
+- 비거래 자산/부채는 초기 구현에서 `ledger_accounts` 항목의 `last_balance`, `last_synced_at`, `memo`를 수동 입력 소스로 사용한다.
+- 운영 경고 섹션은 미분류 거래, 확인필요 큐, 잔액대조 필요 계좌, 최근 백업/import 상태를 한 화면에 노출하고 상세 화면/절차로 이동할 단서를 제공한다.
+- `docs/data-model.md`, `docs/project-structure.md`, `docs/runtime-flows.md`, 필요 시 `docs/interface-contract.md`에 대시보드 운영 허브와 `liquidity_bucket` 흐름을 반영한다.
+
+### Out of Scope
+- 다계좌 실시간 잔액 연동, 외부 시세/투자 평가액 자동 연동.
+- 카드 미결제금, 보험 해지환급금, 자동 시세 연동 자산 반영.
+- `asset_snapshots`, `manual_assets` 같은 별도 자산 평가 테이블 신설.
+- 거래/카테고리 단위 `liquidity_bucket` override.
+- 사용자 정의 회계 월 마감 또는 `posted_date` 기준 월간 현금흐름 전환.
+
+## 3. 기능 요구사항
+
+### FR-1. 이번 달 수입/지출 현황
+- 대시보드 최상단 1순위 섹션은 "이번 달 수입/지출 현황"이어야 한다.
+- 기본 기간은 KST 현재 월의 시작일부터 종료일까지이며, 집계 기준일은 `transactions.transaction_date`다.
+- 실제 수입/지출 판정은 기존 `ledger_categories.cashflow_kind` 기준을 재사용한다.
+- 표시 지표는 실제 수입, 실제 지출, 순현금흐름, 저축률을 포함해야 한다.
+- 저축률은 기존 정의와 동일하게 `순현금흐름 ÷ 실제 수입`을 당월 범위에 적용한다. 실제 수입이 0인 경우에는 나누기 오류 없이 안전한 대체 표시를 제공한다.
+
+### FR-2. 자산 유동성 분류 축
+- `accounts.liquidity_bucket`은 `TEXT NOT NULL DEFAULT 'other'` 성격의 additive 필드로 도입해야 한다.
+- 허용값은 `cash`, `investment`, `deposit`, `real_estate`, `loan`, `other`다.
+- 서비스 계층은 허용값 외 입력을 검증 오류로 거부해야 한다.
+- 계좌 생성, 계좌 목록, 계좌 수정 흐름에서 `liquidity_bucket`을 사용할 수 있어야 한다.
+- 기존 계좌 또는 미지정 계좌는 `other`로 안전하게 폴백해야 한다.
+
+### FR-3. 자산 유동성/구성/순자산 계산
+- 자산 유동성 현황은 `accounts.liquidity_bucket`을 단일 권위 소스로 사용한다.
+- 버킷별 금액은 각 계좌의 최신 `last_balance`를 우선 사용한다. `last_balance`가 없는 계좌는 계산에서 제외하거나 별도 미입력 경고로 표시하되, 임의의 거래 합계로 자산 평가액을 추정하지 않는다.
+- 자산 구성 비율의 분모는 `cash`, `investment`, `deposit`, `real_estate`, `other` 버킷 합계이며, `loan`은 제외한다.
+- 총부채는 `loan` 버킷 합계로 표시하고, 순자산은 대출을 제외한 자산 합계에서 총부채를 차감해 계산한다.
+- 부동산, 예적금, 대출 등 비거래 자산/부채는 `last_balance`를 현재 평가액/잔액, `last_synced_at`을 기준일, `memo`를 출처 메모로 사용한다.
+
+### FR-4. 운영 허브 화면 구성
+- `page_overview`는 다음 순서로 섹션을 배치해야 한다.
+  1. 이번 달 수입/지출 현황
+  2. 자산 유동성 현황
+  3. 자산 구성
+  4. 지출 구조/예산
+  5. 운영 경고
+- 각 섹션은 기준 기간 또는 기준일을 명확히 표시해야 한다.
+- 운영 경고 섹션은 최소한 미분류 거래 건수, 확인필요 큐 상태, 잔액대조 필요 계좌, 최근 백업/import 상태를 표시해야 한다.
+- 운영 경고 항목은 해당 상세 화면 또는 관련 실행 절차로 이동할 수 있는 라벨, 메뉴 안내, 버튼 등 명확한 단서를 제공해야 한다.
+
+### FR-5. 문서 및 기준선 정렬
+- `docs/data-model.md`는 `LedgerAccount`의 `liquidity_bucket`, 비거래 자산 수동 입력 방식, 자산/부채/순자산 계산 규칙을 설명해야 한다.
+- `docs/project-structure.md`는 대시보드 운영 허브와 관련 집계 책임이 `dashboard/app.py` 및 `jarca_ledger_mcp.service`에 걸치는 구조를 반영해야 한다.
+- `docs/runtime-flows.md`는 대시보드 운영 허브 조회 흐름과 KST 현재 월/`transaction_date` 기준, `last_balance` 기반 자산 유동성 집계 흐름을 반영해야 한다.
+- MCP/service/dashboard interface가 변경되면 `docs/interface-contract.md`도 함께 갱신해야 한다.
+
+## 4. Acceptance Criteria
+
+- AC-1: 새 DB 및 기존 DB migration 후 `accounts.liquidity_bucket`이 존재하고 기본값/폴백은 `other`다.
+- AC-2: 잘못된 `liquidity_bucket` 값으로 계좌 생성/수정 시 검증 오류가 반환된다.
+- AC-3: 계좌 생성, 계좌 목록, 계좌 수정 결과에서 `liquidity_bucket`을 확인·설정할 수 있다.
+- AC-4: 대시보드 첫 화면 최상단에 KST 현재 월 `transaction_date` 기준 실제 수입, 실제 지출, 순현금흐름, 저축률이 표시된다.
+- AC-5: 자산 유동성/구성 섹션이 `accounts.liquidity_bucket`과 `last_balance` 기준으로 버킷별 금액, 구성 비율, 총부채, 순자산을 표시한다.
+- AC-6: `loan` 버킷은 자산 구성 비율 분모에서 제외되고 총부채/순자산 계산에만 반영된다.
+- AC-7: `last_balance`가 없는 비거래 자산/부채는 임의 추정하지 않고 미입력 또는 제외 상태가 화면에 명확히 표시된다.
+- AC-8: 운영 경고 섹션이 미분류, 확인필요 큐, 잔액대조 필요, 백업/import 상태를 표시하고 상세 화면/절차 이동 단서를 제공한다.
+- AC-9: `pytest -q`가 통과하고, `dashboard/app.py` 영향 변경이므로 `scripts/streamlit_browser_evidence.py` 기반 screenshot/DOM evidence가 생성된다.
+- AC-10: `docs/data-model.md`, `docs/project-structure.md`, `docs/runtime-flows.md`, 필요 시 `docs/interface-contract.md`가 REQ-005 범위를 반영한다.
+
+## 5. 구현 메모
+
+- Schema version은 후속 batch에서 현재 값보다 1 증가시키고, migration은 additive/idempotent로 작성한다.
+- `liquidity_bucket`의 권위 소스는 계좌 단위로 고정하며 거래/카테고리 override는 이번 범위에서 제외한다.
+- 운영 DB, 원본 금융 파일, 민감정보를 사용하지 않고 synthetic/validation DB에서 대시보드 evidence를 생성한다.
+- dcy-004 QC 결과에 따라 UI 영향 batch는 browser screenshot/snapshot evidence를 필수로 한다.
+- 이 REQ는 구현 기준으로 승인되었으며, 후속 batch에서 구현·검증을 진행한다.