jarca-ledger-mcp/docs/srs/Interface/req-020_review-decision-persistence-reconciliation-workbench.md

# req-020: Review decision persistence and reconciliation workbench

- Status: Approved
- Type: Interface
- Priority: High
- Owner: 렛저장인

## Intent
- `dcy-012`에서 승인된 확인필요 큐 / 잔액대조 / 미분류 추천 운영 모델을 구현 가능한 requirement로 정규화한다.
- 운영자는 preview/report 결과에 머무르지 않고 review decision과 reconciliation session을 영속 기록하고, Streamlit 및 network MCP를 통해 같은 source of truth를 조회·갱신할 수 있어야 한다.
- 기존 MCP/Streamlit contract와 금융 데이터 안전성은 보존하면서, 운영 허브가 미처리·보류·미대조 상태를 재현 가능하게 집계할 수 있게 한다.

## Requirement
- 시스템은 확인필요 큐, 잔액대조 차이, 미분류 추천 항목에 대해 별도 `review_decisions` 테이블 중심의 공통 decision envelope를 제공해야 한다.
- 시스템은 계좌별/기준시점별 `reconciliation_sessions`를 제공하고, review decision이 session 또는 session 내 차이 항목을 target으로 삼을 수 있게 해야 한다.
- `list_cross_transfer_review_queue`, `get_balance_reconciliation_report`, `get_uncategorized_workbench` 및 관련 Streamlit/MCP surface는 persisted decision/session 상태를 반영해 미처리, 처리완료, 보류, 재검토 상태를 구분해야 한다.
- Streamlit workbench는 운영자가 review decision을 생성, 수정, 보류, 재검토 표시, 해제할 수 있는 최소 작업 흐름을 제공해야 한다.
- network MCP surface는 review decision 조회·기록·수정·보류/해제와 reconciliation session 조회·기록·마감에 필요한 additive tool을 제공해야 하며, destructive delete/reset tool은 포함하지 않아야 한다.
- `docs/data-model.md`, `docs/project-structure.md`, `docs/runtime-flows.md`는 review decision persistence, reconciliation/workbench 흐름, 운영 허브 집계 기준을 반영해야 한다.

## Acceptance Criteria
1. Given synthetic/validation DB가 준비되어 있을 때, When 구현이 schema migration을 실행하면, Then `review_decisions`와 `reconciliation_sessions` 또는 동등한 additive/idempotent persistence 구조가 생성되고 기존 데이터와 기존 schema version migration 흐름이 파괴되지 않아야 한다.
2. Given 확인필요 거래, 잔액대조 대상 계좌, 미분류 추천 항목이 있을 때, When review decision을 기록한 뒤 같은 항목을 재조회하면, Then `target_type`, `target_id`, `status`, `decision_type`, `reason_code`, `memo`, `operator`, `decided_at`, `review_after`, `target_payload`에 해당하는 최소 정보가 보존되고 미처리/처리완료/보류/재검토 상태가 재현되어야 한다.
3. Given 계좌별 기준일 대조 결과가 있을 때, When reconciliation session을 기록하거나 마감하면, Then account_id, basis_date, expected_balance, actual_balance, difference, status, closed_at에 해당하는 최소 session 정보가 보존되고 운영 허브가 미대조 계좌 수와 마지막 대조 완료 시각을 계산할 수 있어야 한다.
4. Given persisted decision/session 데이터가 있을 때, When `list_cross_transfer_review_queue`, `get_balance_reconciliation_report`, `get_uncategorized_workbench`를 호출하면, Then 기존 응답 필드는 additive compatibility를 유지하면서 현재 decision/session 상태를 함께 참조할 수 있어야 한다.
5. Given network MCP endpoint가 실행 중일 때, When MCP client가 review decision/session 관련 tool discovery와 대표 조회·기록·수정·보류/해제·마감 smoke를 실행하면, Then destructive delete/reset 없이 성공 응답과 contract-compatible payload를 받아야 한다.
6. Given Streamlit dashboard가 synthetic fixture DB를 사용 중일 때, When 운영자가 workbench에서 decision을 기록·수정·보류·해제하면, Then 재조회와 화면 집계에서 동일 상태가 유지되고 기존 dashboard AppTest/HTTP smoke가 회귀 없이 통과해야 한다.
7. Given 운영 허브 또는 동등한 집계 화면이 열릴 때, When persisted decision/session 상태가 존재하면, Then 1) 미처리 review 건수, 2) 보류/재검토 건수, 3) 미대조 계좌 수, 4) 마지막 대조 완료 시각, 5) 미분류 추천 대기 건수 순으로 우선 지표를 계산 또는 표시할 수 있어야 한다.
8. Given 금융 데이터 안전 기준이 적용될 때, When review decision memo와 payload를 저장하면, Then raw financial evidence 원문, 계좌 비밀번호, 불필요한 raw payload 확대 저장이 없어야 하며 테스트/문서/fixture에 민감자료가 포함되지 않아야 한다.
9. Given 변경이 완료되었을 때, When `ruff check .`, full pytest, contract regression, dashboard AppTest/HTTP smoke, DB safety smoke를 실행하면, Then 모두 통과해야 하며 실패 시 batch verification에서 blocker로 기록해야 한다.
10. Given delivery 문서화가 완료되었을 때, When baseline 문서 diff를 검토하면, Then `docs/data-model.md`, `docs/project-structure.md`, `docs/runtime-flows.md`가 review decision entity, reconciliation session, workbench runtime flow, 운영 허브 집계 기준을 반영해야 한다.

## Impacted Area
- Docs:
  - `docs/discovery/dcy-012_20260703_review-queue-reconciliation-workbench-persistence.md`
  - `docs/data-model.md`
  - `docs/project-structure.md`
  - `docs/runtime-flows.md`
  - `docs/batches/*` 후속 batch planning/design/verification 문서
- Modules:
  - `jarca_ledger_mcp/infrastructure/sqlite/*`
  - `jarca_ledger_mcp/application/cross_transfer_service.py`
  - `jarca_ledger_mcp/application/reconciliation_service.py`
  - `jarca_ledger_mcp/application/uncategorized_workbench_service.py`
  - `jarca_ledger_mcp/adapters/mcp/tool_contracts.py`
  - `jarca_ledger_mcp/adapters/mcp/server.py`
  - `jarca_ledger_mcp/adapters/streamlit/transfers_gateway.py`
  - `jarca_ledger_mcp/adapters/streamlit/reconciliation_gateway.py`
  - `jarca_ledger_mcp/adapters/streamlit/categorization_gateway.py`
  - `dashboard/app.py`
- Tests:
  - review decision persistence pytest 추가
  - reconciliation session pytest 추가
  - MCP contract/smoke test 추가 또는 갱신
  - Streamlit AppTest/HTTP smoke 갱신
  - DB safety/migration regression 갱신

## Notes
- Source Discovery: `docs/discovery/dcy-012_20260703_review-queue-reconciliation-workbench-persistence.md`.
- Confirmed decisions from dcy-012:
  - review decision storage model: 별도 `review_decisions` 테이블 중심의 공통 decision envelope.
  - reconciliation model: 계좌별/기준시점별 `reconciliation_sessions`.
  - internal status: `pending`, `decided`, `held`, `needs_recheck`, `ignored`.
  - internal decision_type: `account_transfer`, `real_expense`, `real_income`, `investment_transfer`, `excluded_from_analysis`, `duplicate_or_cancel`, `unknown`.
  - MCP scope: additive 조회·기록·수정·보류/해제·session 마감 tool 포함, destructive delete/reset 제외.
  - operating hub priority: 미처리 review, 보류/재검토, 미대조 계좌, 마지막 대조 완료 시각, 미분류 추천 대기 순.
- Out of scope:
  - 추가 HTTP transport/remote operation 재설계. network MCP endpoint 제공은 `dcy-013`에서 완료된 선행 조건이다.
  - 멀티유저 권한/승인 체계, 역할별 접근제어.
  - 자동 스케줄링, 푸시 알림, 외부 메시징 연동.
  - AI 기반 자동 판정 확정.
  - raw financial evidence 원문 저장 확대 또는 민감자료 보관 범위 확장.
- NFR handling:
  - contract preservation, auditability, DB safety, operational determinism은 별도 REQ로 분리하지 않고 본 REQ의 Acceptance Criteria와 batch verification gate에 포함한다.
- Delivery harness note:
  - 이 REQ가 Approved 되면 StagePilot harness 기준으로 lead가 `delivery-runner`에게 canonical kickoff를 발행하고, delivery-runner가 `dev-builder` 구현과 `dev-reviewer` 독립 QC를 분리해 운영해야 한다.

## Change Log

### CHG-20260707-01
- Date: 2026-07-07
- Author: 가웨인

#### Change Summary
- dcy-012 confirmed 범위를 REQ-020 Proposed 요구사항으로 생성했다.

#### Intent
- 확인필요 큐 / 잔액대조 / 미분류 추천의 review decision persistence와 reconciliation workbench를 delivery input으로 사용할 수 있는 단일 requirement로 정규화하기 위해 생성했다.

#### Acceptance Criteria Delta
- Added:
  - review decision persistence, reconciliation session, Streamlit workbench, network MCP additive tools, 운영 허브 집계, baseline 문서 갱신, regression gates를 acceptance criteria로 추가했다.
- Updated:
  - none
- Removed:
  - none

#### Impacted Area Delta
- Docs:
  - `docs/srs/index.md`
  - `docs/srs/Interface/req-020_review-decision-persistence-reconciliation-workbench.md`
  - `docs/discovery/dcy-012_20260703_review-queue-reconciliation-workbench-persistence.md`
- Modules:
  - none yet; implementation pending
- Tests:
  - none yet; implementation pending

#### Delivery Trace Delta
- Batches:
  - none yet
- Releases:
  - none

#### Revalidation Impact
- Reverification Needed: yes
- Existing Implementation Invalidated: no
- Status Recommendation: keep-current
- Follow-up Action: run `confirm-req` for REQ-020, then batch selection/drafting before delivery-runner kickoff.

#### Validation Plan
- Before implementation approval, verify additive migration safety, persisted decision/session round-trip, MCP and Streamlit contract compatibility, full pytest, lint, dashboard smoke, DB safety smoke, and baseline document updates.

### CHG-20260708-01
- Date: 2026-07-08
- Author: 가웨인

#### Change Summary
- REQ-020 승인 게이트를 통과해 Status를 Approved로 전환했다.

#### Intent
- dcy-012 confirmed 범위가 delivery input으로 충분히 구체화되었고, Priority/Owner/범위/Acceptance Criteria에 승인 blocker가 남아 있지 않아 batch planning 대상으로 확정하기 위해 승인했다.

#### Acceptance Criteria Delta
- Added:
  - none
- Updated:
  - none
- Removed:
  - none

#### Impacted Area Delta
- Docs:
  - `docs/srs/Interface/req-020_review-decision-persistence-reconciliation-workbench.md`
  - `docs/srs/index.md`
- Modules:
  - none
- Tests:
  - none

#### Delivery Trace Delta
- Batches:
  - none yet
- Releases:
  - none

#### Revalidation Impact
- Reverification Needed: yes
- Existing Implementation Invalidated: no
- Status Recommendation: keep-current
- Follow-up Action: run `suggest-batch-reqs` or draft the batch, then issue the StagePilot `lead -> delivery-runner` kickoff after the batch boundary is ready.

#### Validation Plan
- Validate through StagePilot doctor, index consistency checks, and CI after commit. Delivery validation remains owned by the later batch verification gate.