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은 하지 않는다.
+- 대조 기준 잔액 실제 값은 운영 시점에 사용자가 입력한다.