gitea-impl-agent/jarca-ledger-mcp
1
0
Fork 0
forked from jsfamily/jarca-ledger-mcp
Code Pull Requests Activity
Files
02380a88abcb0986ee0dc949adc467f7adfb53f9
jarca-ledger-mcp/docs/srs/Interface/req-003_statement-unavailable-manual-evidence-balance-reconciliation.md
T

5.1 KiB
Raw Blame History

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