jarca-ledger-mcp/docs/discovery/dcy-003_20260629_statement-unavailable-manual-evidence-balance-reconciliation.md

0. 문서 상태

이 문서의 현재 상태와 식별 정보를 기록한다. 문서 추적과 승인 흐름에 필요한 최소 메타데이터를 적는다.

• 상태: confirmed
• 문서 ID: dcy-003_20260629_statement-unavailable-manual-evidence-balance-reconciliation
• 이슈명: Statement-unavailable 계좌 수동 증빙 및 잔액대조 워크플로우 정립
• 작성 시각(KST): 2026-06-29 12:33
• 마지막 갱신 시각(KST): 2026-06-29 13:06
• 대체됨: 없음
• 후속 Discovery 참조: docs/discovery/dcy-012_20260703_review-queue-reconciliation-workbench-persistence.md
• 생성된 REQ 참조: REQ-003 (docs/srs/Interface/req-003_statement-unavailable-manual-evidence-balance-reconciliation.md)

1. 계획 상태 요약

현재 Discovery가 어떤 배경에서 작성되고 있는지, 연계 문서가 있는지, 지금 시점의 해석이 무엇인지 짧게 요약한다.

• 연계 문서 현황:
  • 관련 GitHub Project 항목: https://github.com/users/genichin/projects/4 DraftIssue
  • 관련 TODO/메모: Statement-unavailable 계좌 수동 증빙 및 잔액대조 워크플로우 정립
• 해석:
  • dcy-001(분류·환급 UX)과 dcy-002(백업·복구 안전장치)는 모두 statement(거래내역 파일)가 존재하는 계좌의 import·분류·검증 흐름을 전제로 하며, statement가 없거나 자동 import가 어려운 계좌를 다루는 표준 절차는 아직 정의되지 않았다.
  • 이번 Discovery는 거래내역 파일이 없는 계좌에 대한 수동 증빙 입력, 잔액대조(reconciliation), 확인필요 큐 처리, 계좌이동/실지출 판정 기준을 독립 주기로 정의한다.

2. 요구사항 판정 결과

이번 요청이 기존 요구사항과 비교해 신규인지, 유사한지, 중복인지 판단하고 그 근거를 남긴다.

• 판정: 신규
• 근거
  • 기존 Discovery dcy-001/dcy-002와 REQ-001/REQ-002는 statement 기반 import·분류·백업 범위를 다루며, statement-unavailable 계좌의 수동 증빙·잔액대조를 독립 성공 기준으로 다루지 않는다.
  • 코드에는 source='manual' 거래, ledger_accounts.last_balance, transactions.balance_after, transfer 매칭/확인필요 큐가 부분적으로 존재하나, 이를 잔액대조 워크플로우로 묶는 명시적 절차·acceptance criteria가 없어 별도 주기로 추적할 필요가 있다.

3. 문제점의 요약

문제의 현재 상태, 기대 상태, 관련 이해관계자, 제약사항을 정리한다. Discovery의 핵심 맥락을 가장 먼저 이해할 수 있어야 한다.

• 현재 상태
  • import 경로는 statement 파일을 전제로 한다: service.py의 preview_ledger_csv_import, preview_kb_bank_pdf_import, preview_seoulpay_xlsx_import, preview_toss_bank_pdf_import, preview_toss_securities_pdf_import 등은 모두 입력 파일이 있어야 동작한다.
  • 스키마에는 수동 증빙·잔액대조의 토대가 일부 존재한다: db.py의 ledger_accounts.last_balance/last_synced_at, transactions.balance_after, transactions.source(기본값 manual).
  • 계좌이동/실지출 판정 요소가 분산되어 있다: find_self_transfer_candidates, link_self_transfer_pair, run_cross_account_transfer_match/list_cross_transfer_review_queue(확인필요 성격의 review 큐), infer_cashflow_kind(category→cashflow_kind 추론). 그러나 statement가 없는 계좌에 대해 수동 입력 거래를 어떤 기준으로 계좌이동 또는 실지출로 판정할지에 대한 단일 규칙·증빙 요건은 문서화되어 있지 않다.
  • docs/runbooks/에는 ledger-backup-restore.md만 있고, 수동 증빙/잔액대조 운영 절차 runbook이 없다. docs/runtime-flows.md도 statement-unavailable 계좌의 입력·대조 흐름을 다루지 않는다.
• 기대 상태
  • 운영자는 거래내역 파일이 없거나 자동 import가 어려운 계좌에 대해, 표준화된 수동 증빙(거래·증빙 출처·금액·일자) 입력 절차로 누락 없이 거래를 기록할 수 있다.
  • 각 계좌의 기준 잔액(last_balance)과 누적 거래로 산출한 계산 잔액을 대조하여 차이를 정량적으로 확인하고, 허용 오차를 벗어나는 차이는 확인필요 큐로 라우팅한다.
  • 수동 입력·대조 과정에서 발생한 모호 거래를 계좌이동/실지출 판정 기준에 따라 일관되게 분류하여 월간 현금흐름·카테고리 지출 보고서의 왜곡을 줄인다.
• 이해관계자
  • 렛저장인(운영자 겸 작성자) — 수동 증빙 입력과 잔액대조 실행 주체
  • 검수관/리뷰어 — 대조 결과와 판정 근거의 검증 주체
  • StagePilot 후속 SDLC(REQ/Batch) 수행자 — 본 Discovery를 후속 요구사항으로 정제
• 제약사항
  • 개인 금융정보를 다루므로 증빙 원문·계좌번호는 마스킹(account_number_masked)·최소 보관 원칙을 따른다.
  • 원본 운영 DB 훼손을 피하기 위해 dcy-002에서 정의한 백업·검증 DB 절차를 전제로 한다.
  • 수동 입력은 휴먼 에러 가능성이 높아 입력 검증과 재대조 가능성이 필요하다.

주요 사용자 시나리오

사용자 또는 운영자가 실제로 어떤 상황에서 이 변경을 필요로 하는지 대표 시나리오를 적는다.

• 운영자가 거래내역 파일을 제공하지 않는 계좌(예: 일부 현금 계좌, 모임 통장, 명세서 비공개 계좌)의 월말 잔액만 알고 있을 때, 누락 거래를 수동 증빙으로 입력하고 계산 잔액을 기준 잔액과 맞춘다.
• import는 되지만 일부 기간 데이터가 비어 있는 계좌에서, 비어 있는 구간의 거래를 수동 증빙으로 보완한 뒤 잔액대조로 정합성을 확인한다.
• 잔액대조 결과 차이가 허용 오차를 초과하여 확인필요 큐에 올라온 항목을, 운영자가 계좌이동(다른 내 계좌로의 이동)인지 실지출인지 판정하여 처리한다.

4. 이번에 정의할 변경

이번 Discovery에서 다루는 핵심 변경 항목을 목록으로 적는다. 기능, 구조, 규칙 변경을 함께 포함해도 된다.

• accounts.statement_status를 추가해 manual_only를 statement-unavailable 계좌로 정의하고, partial_import도 수동 보완/잔액대조 대상으로 포함한다.
• statement-unavailable 계좌에 대한 수동 증빙 입력 표준(필수 필드: 일자, 금액, 출처/증빙 유형, 메모, source=manual)과 입력 검증 규칙을 정의한다.
• 계좌별 기준 잔액(last_balance) 대비 누적 거래 계산 잔액을 비교하는 잔액대조 절차를 정의한다. 정기 기준 시점은 매월 말일 23:59 KST, 수시 기준 시점은 사용자 입력 스냅샷 시각이며, 초기 허용 오차는 1,000원으로 한다.
• 확인필요 큐 항목에 대한 계좌이동/실지출/실수입/투자이동/분석제외/확인필요 판정 기준을 문서화한다. 자동 확정은 제한하고 추천/후보 제시 후 사용자 수동 확정을 기본으로 한다.
• 수동 증빙·잔액대조 운영 절차를 docs/runtime-flows.md(신규 흐름)와 신규 runbook 후보(docs/runbooks/)에 반영할 필요를 명시한다.

영향 범위

변경이 미칠 코드/문서/운영 범위를 명시해 REQ 정제와 batch planning에서 추정 누락을 줄인다.

• 코드 영향:
  • jarca_ledger_mcp/service.py — 수동 증빙 입력/잔액대조/확인필요 라우팅 서비스 로직 신설 또는 기존 transfer·workbench 로직 확장
  • jarca_ledger_mcp/server.py — 대조·증빙 관련 MCP tool 노출 (필요 시)
  • dashboard/app.py — 계좌 화면의 statement_status 표시/수정, 최소 잔액대조 결과 표시. 전용 잔액대조 워크벤치 전체 신설은 후속 범위로 분리
  • jarca_ledger_mcp/db.py — accounts.statement_status 추가 및 대조 메타(기준 잔액 스냅샷, 대조 시각 등) 보강 필요 여부 검토
• 문서 영향:
  • docs/runtime-flows.md — statement-unavailable 수동 증빙·잔액대조 흐름 추가
  • docs/runbooks/ — 수동 증빙·잔액대조 운영 runbook 신규 후보
  • docs/data-model.md — 대조 관련 필드 의미 보강 필요 여부 검토
• 운영 영향:
  • 월말/정기 잔액대조 운영 루틴이 신설되며, 대조 전 dcy-002 백업 절차 선행이 요구된다.

5. 요구사항 목록

실제로 구현과 검증으로 이어질 요구사항을 기능/비기능으로 나누어 정리하고, 범위 경계를 명확히 적는다.

기능 요구사항

• FR-1: accounts.statement_status 필드를 unknown, import_supported, manual_only, partial_import 값으로 관리하고, manual_only 계좌를 statement-unavailable 계좌로 정의해야 한다. partial_import 계좌는 수동 보완 및 잔액대조 대상으로 포함한다.
• FR-1a: statement-unavailable 계좌에 대해 일자·금액·증빙유형·메모를 갖춘 수동 증빙 거래를 source='manual'로 입력·수정할 수 있어야 하며, 필수 필드 누락 시 입력을 거부해야 한다.
• FR-2: 계좌별 기준 잔액(last_balance)과 누적 거래 기반 계산 잔액을 비교하여 차액과 대조 시점을 산출하는 잔액대조 기능을 제공해야 한다. 정기 대조 기준 시점은 매월 말일 23:59 KST이고, 수시 대조는 사용자가 입력한 스냅샷 시각을 기준으로 한다.
• FR-3: 잔액대조 차액이 초기 허용 오차 1,000원을 초과하면 해당 항목을 확인필요 큐로 라우팅하고, 운영자가 계좌이동/실지출/분석제외로 판정해 처리할 수 있어야 한다. 기준 잔액 대비 0.1% 비율은 참고값으로만 표시하고 1차 판정 기준에는 사용하지 않는다.
• FR-4: 확인필요 항목은 계좌이동, 실지출, 실수입, 투자이동, 분석제외, 확인필요 6개 판정값으로 처리할 수 있어야 한다. 자동 확정보다는 후보 추천과 사용자 수동 확정을 기본으로 하며, 확정 결과는 cashflow_kind에 반영되어 월간 현금흐름·카테고리 지출 보고서에 일관되게 적용되어야 한다.
• FR-5: 수동 증빙·잔액대조 운영 흐름을 docs/runtime-flows.md에 반영하고, 운영 절차 runbook을 docs/runbooks/ 후보로 추가해야 한다.

비기능 요구사항

성능, 운영성, 일관성, 자동화 안정성 등 기능 외 요구사항을 적는다.

• NFR-1: 모든 대조·증빙 작업은 dcy-002의 백업·검증 DB 절차를 전제로 수행되어 원본 운영 DB 훼손 위험을 낮춰야 한다.
• NFR-2: 증빙 원문·계좌 식별정보는 마스킹·최소 보관 원칙을 따르고, 문서·로그에 평문 계좌번호/자격증명을 남기지 않아야 한다.
• NFR-3: 잔액대조 결과는 재현 가능해야 하며, 동일 입력에 대해 동일한 차액·확인필요 분류 결과를 산출해야 한다.

범위 경계

이번 반복에서 반드시 포함할 범위와 명시적으로 제외할 범위를 구분한다.

• In Scope
  • accounts.statement_status 기반 statement-unavailable 계좌 분류와 수동 증빙 입력·검증 규칙 정의
  • 기준 잔액 대비 계산 잔액 대조, 월말/수시 기준 시점, 1,000원 허용 오차 및 확인필요 라우팅 규칙 정의
  • 계좌이동/실지출 판정 기준의 문서화
• Out of Scope
  • statement 파일 기반 자동 import 파서 신규 추가(기존 KB/Toss/SeoulPay 경로 변경 없음)
  • 잔액대조 자동 스케줄링/알림. 이번 반복은 수동 실행 가능한 잔액대조와 결과 리포트까지만 포함한다.
  • 전용 잔액대조 워크벤치 전체 신설. 이번 반복은 계좌 화면의 statement_status 표시/수정과 최소 잔액대조 결과 표시까지만 포함한다.

6. 리스크/가정 목록

불확실성과 전제 조건을 분리해서 적는다. 리스크는 영향과 완화 방안을, 가정은 현재 판단의 전제를 기록한다.

리스크

• R-1 (High): 수동 입력 휴먼 에러로 거래가 중복·누락되어 잔액대조 차액이 실제 오류를 가릴 수 있다.
  • 완화 방안: 필수 필드 검증, 입력 후 재대조, 차액 변화 로그로 추적 가능성 확보
• R-2 (Medium): 계좌이동/실지출 판정 기준이 모호하면 동일 거래가 작업자마다 다르게 분류되어 보고서 일관성이 깨진다.
  • 완화 방안: 자기계좌 간 이동·외부 지출·분석제외에 대한 명시적 판정표 정의 및 기존 infer_cashflow_kind/transfer 매칭과 정합
• R-3 (Medium): 허용 오차 임계값이 부적절하면 확인필요 큐가 과도하게 커지거나 실제 차이를 놓친다.
  • 완화 방안: 초기 임계값을 보수적으로 설정하고 운영 데이터로 조정, 임계값을 설정값으로 외부화

가정

아직 확정되지 않았지만 현재 문서 작성의 기반이 되는 전제를 적는다.

• A-1: ledger_accounts.last_balance, transactions.balance_after/source, 신규 accounts.statement_status 필드를 잔액대조의 기준 데이터로 재사용할 수 있다.
• A-2: 기존 transfer 매칭(link_self_transfer_pair, cross-account match)과 확인필요 review 큐 구조를 계좌이동 판정 흐름에 연계할 수 있다.
• A-3: 대조 작업은 dcy-002 백업·검증 DB 절차가 이미 운영 가능한 상태임을 전제로 한다.

오픈 질문

답을 아직 모르는 항목을 적는다. 추정으로 덮지 말고 REQ 초안 작성 이전에 확인할 질문으로 남긴다.

• OQ-1: 잔액대조 허용 오차(절대 금액/비율)와 기준 시점(월말/임의 스냅샷)을 어떻게 정의할 것인가?
  • 상태: Answered
  • 처리 방안: 정기 잔액대조는 매월 말일 23:59 KST 기준으로 수행한다. 수시 대조는 사용자가 입력한 스냅샷 시각을 기준으로 허용한다. 초기 허용 오차는 절대 금액 1,000원으로 두며, 차액이 1,000원을 초과하면 확인필요 큐로 라우팅한다. 기준 잔액 대비 0.1% 비율은 표시/참고값으로만 제공하고, 1차 판정 기준으로는 사용하지 않는다.
  • 종료 조건: REQ의 acceptance criteria에 기준 시점, 허용 오차 1,000원, 확인필요 라우팅 조건이 수치로 반영되면 Answered
• OQ-2: 어떤 계좌를 "statement-unavailable"로 분류·표시할 것인가(계좌 속성 신설 여부)?
  • 상태: Answered
  • 처리 방안: accounts 테이블에 statement_status 필드를 추가한다. 허용값은 unknown, import_supported, manual_only, partial_import로 정의한다. 기본값은 unknown이다. manual_only 계좌를 dcy-003의 statement-unavailable 계좌로 간주하고, partial_import 계좌는 수동 보완 및 잔액대조 대상으로 포함한다.
  • 종료 조건: REQ의 데이터 모델/acceptance criteria에 statement_status 필드, 허용값, 기본값, 잔액대조 대상 조건이 반영되면 Answered

7. 초기 성공 기준

이 변경이 성공했다고 판단할 기준을 측정 가능하게 정의한다. 가능하면 데이터 출처까지 연결한다.

• S-1: statement_status=manual_only 또는 partial_import인 대상 계좌에 대해 수동 증빙 입력 후 계산 잔액과 기준 잔액의 차액이 1,000원 이내로 수렴한다.
• S-2: 잔액대조 차액이 1,000원을 초과하는 모든 항목이 확인필요 큐에 라우팅되고, 계좌이동/실지출/분석제외 중 하나로 판정·처리된다.
• S-3: 수동 증빙·잔액대조 운영 흐름이 docs/runtime-flows.md와 runbook 후보 문서로 정리되어 후속 REQ/Batch에서 참조 가능하다.

측정 방식 및 데이터 출처

각 성공 기준을 어떻게 측정할지와 어떤 데이터나 문서를 근거로 쓸지 적는다.

• S-1 측정 방식: 검증 DB에서 statement_status in (manual_only, partial_import) 계좌별 (계산 잔액 − 기준 잔액) 차액 산출 및 1,000원 이내 여부 확인 / 데이터 출처: accounts.statement_status, ledger_accounts.last_balance, transactions(amount/balance_after)
• S-2 측정 방식: 확인필요 큐 적재 건수와 미판정 잔여 건수 비교 / 데이터 출처: 확인필요 큐(서비스 로직 결과), 판정 처리 로그
• S-3 측정 방식: 문서 존재 및 흐름 반영 여부 리뷰 / 데이터 출처: docs/runtime-flows.md, docs/runbooks/

8. REQ로 넘기기 전 확인 체크

REQ 초안 작성 단계로 넘기기 전에 무엇이 확정되어야 하는지 확인한다. 미완료 항목은 후속 결정이 필요함을 뜻한다.

• 범위(In Scope/Out of Scope) 확정
  • 기준: 자동 스케줄링/알림과 전용 잔액대조 워크벤치 전체 신설은 제외하고, 수동 실행 잔액대조·결과 리포트·계좌 화면의 statement_status 표시/수정은 포함한다.
• 성공 지표의 측정 방식/데이터 출처 확정
  • 기준: 허용 오차 1,000원, 월말 23:59 KST 정기 기준 시점, 사용자 입력 수시 스냅샷 기준 시점이 측정 방식에 반영됨
• High 영향 리스크 우선순위 및 해소 책임자 지정
  • 기준: R-1(수동 입력 휴먼 에러)은 렛저장인이 필수 필드 검증·재대조·검증 DB evidence로 해소한다.
• 모든 오픈 질문(OQ) Open 상태 없음 확인
  • 기준: OQ 목록에 Open 상태 항목이 0개이거나, 잔여 항목 전부 Deferred 처리 완료
• Freeze 확정 담당자(CONFIRMED_BY) 지정
  • 기준: 사용자 진환 고가 본 Discovery 권장안을 승인하고 구현 위임을 지시했다.

9. 파일 처리 결과

이 Discovery 문서 생성/갱신 결과와 참조 문서를 기록한다. 이후 추적과 리뷰 시 근거로 사용한다.

• 처리 결과: 생성
• 생성 경로: docs/discovery/dcy-003_20260629_statement-unavailable-manual-evidence-balance-reconciliation.md
• 참조 문서:
  • docs/discovery/dcy-002_20260627_operational-safety-backup-restore-validation-db.md
  • docs/runtime-flows.md
  • docs/data-model.md

10. 사용자 결정 필요 항목 요약

사용자나 승인자가 결정해야 하는 항목만 모아 정리한다. 결정, 확인, 데이터 요청을 구분해서 적는다.

DECIDE

• 잔액대조 자동 스케줄링/알림은 이번 반복 범위에서 제외하고, 수동 실행 가능한 잔액대조와 결과 리포트까지만 포함한다.
• 전용 수동 증빙/잔액대조 워크벤치 전체 신설은 제외하고, 계좌 화면의 statement_status 표시/수정과 최소 잔액대조 결과 표시까지만 포함한다.
• 계좌이동, 실지출, 실수입, 투자이동, 분석제외, 확인필요 6개 판정값을 사용한다. 자동 확정보다는 추천/후보 제시 후 사용자 수동 확정을 기본으로 한다.

CONFIRM

• 대조 작업 전 dcy-002 백업·검증 DB 절차 선행을 운영 표준으로 확정한다. 운영 DB 변경 전 백업은 필수이며, 검증 DB에서 preview/reconcile을 먼저 수행한다. Restore는 사용자 명시 승인 없이는 실행하지 않는다.

DATA

• 실제 계좌별 기준 잔액 값은 운영 시점에 입력한다. REQ에는 account_id, statement_status, baseline_balance, baseline_at, source_note, memo 입력 포맷과 검증 규칙을 정의한다.

11. Discovery Freeze

REQ 초안 작성 인계 시점의 확정 플래그와 섹션 참조만 기록한다. 내용 재작성 없이 원본 섹션을 링크로 대신한다.

섹션 참조

• 범위: # 5. 요구사항 목록 > 범위 경계
• 리스크/오픈 질문: # 6. 리스크/가정 목록
• 성공 기준: # 7. 초기 성공 기준
• 인계 전 확인: # 8. REQ로 넘기기 전 확인 체크
• 사용자 결정 필요: # 10. 사용자 결정 필요 항목 요약

Freeze 플래그

• Handoff Decision: 승인
• Handoff Rationale: 사용자 승인으로 잔액대조 허용 오차, 기준 시점, statement-unavailable 계좌 분류 방식, 자동화/UI 범위, 판정 기준, 백업 선행 조건, 기준 잔액 데이터 처리 방식이 확정되었으므로 REQ 초안 작성과 구현 위임으로 넘긴다.
• Ready for REQ Drafting: true
• Confirmed By: 진환 고
• Confirmed At (KST): 2026-06-29 13:06