jarca-ledger-mcp/docs/discovery/dcy-012_20260703_review-queue-reconciliation-workbench-persistence.md

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

- 상태: confirmed
- 문서 ID: dcy-012_20260703_review-queue-reconciliation-workbench-persistence
- 이슈명: 확인필요 큐 / 잔액대조 워크벤치 영속화 및 운영 모델 정립
- 작성 시각(KST): 2026-07-03 10:31 KST
- 마지막 갱신 시각(KST): 2026-07-07 23:53 KST
- 대체됨: 없음
- 후속 Discovery 참조: 없음
- 생성된 REQ 참조: `REQ-020` (`docs/srs/Interface/req-020_review-decision-persistence-reconciliation-workbench.md`)

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

- 연계 문서 현황:
	- 선행 Discovery: `docs/discovery/dcy-003_20260629_statement-unavailable-manual-evidence-balance-reconciliation.md` (statement-unavailable 계좌 수동 증빙/잔액대조 기준 확정), `docs/discovery/dcy-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow.md` (운영 경고 허브에 확인필요/잔액대조 필요 상태를 집계 노출)
	- 관련 후속 구현: `docs/discovery/dcy-011_20260703_backend-refactor-phase4-write-import-workflow-adapter-narrowing.md` 및 `REQ-017`/`BAT-013` (cross-transfer, reconciliation, uncategorized workbench service 분리), `REQ-018`/`BAT-014` (Streamlit/MCP adapter surface 축소)
	- 관련 baseline 문서: `docs/data-model.md`, `docs/project-structure.md`, `docs/runtime-flows.md`
	- 관련 project board: GitHub Project 4(Jarca)에서 statement-unavailable workflow와 Phase 4~7 refactor는 Done 상태이며, 본 Discovery에 직접 대응하는 review decision/workbench 영속화 TODO는 아직 없다.
- 해석:
	- 현재 저장소에는 `list_cross_transfer_review_queue`, `run_cross_account_transfer_match`, `get_balance_reconciliation_report`, `get_uncategorized_workbench`가 존재해 확인필요 큐·대조 preview·미분류 추천까지는 가능하지만, 운영자가 내린 판정과 예외 사유를 영속적으로 저장하고 다음 회차에 재사용하는 review-decision 모델은 없다.
	- 따라서 이번 Discovery는 dcy-003이 정의한 수동 증빙/잔액대조 규칙을 "preview/report" 단계에서 멈추지 않고, 확인필요 큐·잔액대조·미분류 검토를 하나의 운영 워크벤치로 묶는 후속 주기로 정식화한다. HTTP/network MCP endpoint 제공은 후속 `dcy-013`에서 별도 완료되었으므로 본 주기는 transport 구현이 아니라 review-decision/workbench persistence와 해당 기능의 MCP tool surface 범위에 집중한다.

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

- 판정: 신규
- 근거
	- dcy-003은 statement-unavailable 계좌의 수동 증빙 입력, 기준 잔액 대비 reconciliation preview, 확인필요 판정 기준을 정의했지만, 전용 잔액대조 워크벤치 전체 신설은 명시적으로 Out of Scope였다. 이번 요청은 그때 제외한 "결정 영속화 + 운영 워크벤치"를 독립 성공 기준으로 다룬다.
	- dcy-005는 운영 허브에서 미분류/확인필요/잔액대조 필요 상태를 집계해 보여주는 정보구조를 다뤘고, dcy-011/REQ-017은 내부 서비스 분리를 완료했다. 그러나 review decision persistence, reconciliation session 기록, 대량 검토 UX, 재검토/예외 관리 모델은 별도 문제 정의와 범위 경계를 필요로 하므로 새 Discovery로 분리하는 것이 명확하다.

> **판정이 `완전 중복`인 경우**: 이하 섹션 작성을 중단하고 `# 9. 파일 처리 결과`에 중복 판정 사유와 참조 문서 경로를 기록한 뒤 문서를 닫는다. REQ 초안 작성으로 넘기지 않는다.

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

- 현재 상태
	- `jarca_ledger_mcp.application.cross_transfer_service.list_cross_transfer_review_queue()`는 `transactions.memo LIKE '%cross_transfer_review:%'` 태그가 붙은 active 거래를 최신순으로 조회하는 큐를 제공한다. 하지만 review item의 판정 상태, 결정자, 결정 시각, 재검토 메모, 예외 사유를 별도 엔터티로 저장하지 않고 거래 메모 태그와 현재 카테고리/타입 상태에 암묵적으로 의존한다.
	- `jarca_ledger_mcp.application.reconciliation_service.get_balance_reconciliation_report()`는 `statement_status in (manual_only, partial_import)` 계좌에 대한 baseline 대비 차이를 preview/report 형태로 계산하고 `REVIEW_NEEDED` 여부와 권장 결정값을 반환한다. 그러나 이 결과는 실행 시점 계산값이며, 어떤 차이를 어떤 사유로 인정/보류/재검토했는지 persist하지 않는다.
	- `jarca_ledger_mcp.application.uncategorized_workbench_service.get_uncategorized_workbench()`는 미분류 거래와 추천 분류를 제공하지만, 운영자가 추천을 채택/거부/보류한 결정 이력과 이유는 구조화되어 있지 않다.
	- `docs/data-model.md`는 현재 gap으로 “dedicated reconciliation workbench and persistent review-decision queue”를 명시하고 있다. `docs/runtime-flows.md`와 `docs/project-structure.md`도 확인필요 큐/미분류/잔액대조가 개별 화면과 게이트웨이로는 존재하나, 공통 review-decision persistence 계층은 아직 없음을 암시한다.
	- GitHub Project 4 기준으로 statement-unavailable workflow와 Phase 4~7 refactor는 완료되었지만, review queue persistence/workbench 운영 모델을 대표하는 활성 보드 항목은 아직 없다. 즉 현재는 기능 조각은 있으나 운영 워크플로우 단위의 후속 주기가 비어 있다.
- 기대 상태
	- 운영자는 확인필요 큐, 잔액대조 차이, 미분류 추천 항목을 단순 조회가 아니라 하나의 workbench에서 검토하고, 각 항목을 `확인필요`, `계좌이동`, `실지출`, `실수입`, `투자이동`, `분석제외`, `보류/재검토` 등 구조화된 결정으로 저장할 수 있어야 한다.
	- review decision은 거래 row의 현재 상태와 별개로 영속 기록되어 결정 시각, 근거 메모, 관련 짝거래/계좌, 재검토 필요 여부를 남기고, 이후 재대조/재import/월마감 시 재사용 가능해야 한다.
	- 잔액대조는 preview report를 넘어 “이번 기준 시점의 차이를 어떤 판단으로 정리했는가”를 session 또는 decision log로 남겨 미해결 항목과 완료 항목을 구분해야 한다.
	- Streamlit과 MCP는 공통 application/domain 모델 위에서 같은 review-decision 규칙을 사용해야 하고, 운영 허브는 미처리 review queue/보류 항목/미대조 계좌 상태를 신뢰성 있게 집계할 수 있어야 한다.
- 이해관계자
	- 가계부 운영자(진환 고) — 확인필요/대조/미분류 항목을 직접 판정하고 월말 운영 상태를 정리하는 1차 사용자
	- 구현 담당자/검수 담당자 — review decision 모델, workbench UI, MCP tool contract를 설계·구현·검증하는 주체
	- 향후 자동화/리포트 소비자 — 월말 close, 운영 경고, 향후 HTTP adapter 또는 외부 자동화에서 review 상태를 읽게 될 잠재적 소비자
- 제약사항
	- 기존 MCP tool 이름, 주요 응답 필드, 카테고리·현금흐름 의미, import 증빙 필드 보존 원칙은 유지되어야 하며, review decision 도입이 기존 실지출/실수입 해석을 깨뜨리면 안 된다.
	- 금융 데이터 특성상 원본 계좌정보·비밀번호·raw payload는 저장/커밋하지 않아야 하고, review 근거 메모도 최소 보관/마스킹 원칙을 따라야 한다.
	- destructive migration 없이 additive schema만 허용되며, 운영 DB가 아닌 fixture/validation DB에서 흐름을 검증해야 한다.
	- 이번 주기는 review-decision/workbench 모델 정립에 집중하며, Phase 8 HTTP adapter, 멀티유저 권한, 원격 운영 재설계로 확장하지 않는다.

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

- 운영자가 KB↔토스 거래를 자동 매칭한 뒤 `확인필요 큐`에 남은 항목을 열어 “내 계좌 간 이동”, “타인 송금”, “실제 소비”, “보류/재검토”로 판정하고 그 근거를 저장한다.
- 운영자가 `get_balance_reconciliation_report`로 차이가 발생한 계좌를 검토하면서, 어떤 차이를 허용 예외로 남겼는지, 어떤 거래를 추가 보완해야 하는지, 언제 다시 확인할지를 workbench에 기록한다.
- 운영자가 미분류 거래 추천을 검토할 때 추천을 수락/거부하고, 동일 merchant 패턴에 대해 이후 자동화가 재사용할 수 있도록 결정 이력을 남긴다.
- 월말에 운영 허브에서 “미처리 review 항목”, “재검토 대기”, “미대조 계좌”를 한 번에 보고, 남은 정리 작업을 workbench로 이동해 마감한다.

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

- review decision persistence 도입: 확인필요 큐, 잔액대조 차이, 미분류 추천에 공통으로 적용 가능한 review-decision 엔터티(상태, 결정 유형, 근거 메모, 관련 거래/계좌/session, 재검토 플래그)를 정의한다.
- reconciliation/workbench 운영 모델 정립: preview-only 대조 리포트를 session/decision 기록으로 연결하고, Streamlit workbench와 MCP workflow가 동일한 review queue 상태를 읽고 갱신하는 흐름을 정의한다.
- 운영 허브 연계 기준 확정: 운영 경고·월마감·미처리 review 집계가 어떤 상태 정의를 source of truth로 삼는지 정하고, `docs/data-model.md`, `docs/project-structure.md`, `docs/runtime-flows.md` 갱신 요구를 포함한다.

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

- 코드 영향:
	- 신규 review decision / reconciliation session persistence 계층 후보 (`jarca_ledger_mcp/application/*`, `infrastructure/sqlite`, schema additive migration)
	- `cross_transfer_service`, `reconciliation_service`, `uncategorized_workbench_service`의 preview/report 결과를 persisted decision 상태와 연결하는 service 확장
	- `adapters/streamlit/transfers_gateway.py`, `reconciliation_gateway.py`, `categorization_gateway.py`, `dashboard/app.py`의 workbench UI 액션 추가
	- `adapters/mcp/tool_contracts.py`, `adapters/mcp/server.py`의 review queue decision mutation/조회 도구 추가 여부 검토
- 문서 영향:
	- `docs/data-model.md` — review decision/session 엔터티와 상태 정의 반영 필요
	- `docs/project-structure.md` — workbench/review persistence 계층 추가 시 구조 반영 필요
	- `docs/runtime-flows.md` — review queue 처리, 대조 session 정리, 운영 허브 집계 흐름 반영 필요
	- 관련 runbook 또는 월마감 운영 절차 문서 신설 후보
- 운영 영향:
	- 미처리/보류/재검토 항목을 운영적으로 추적하는 월말 루틴이 생기며, review decision이 실제 현금흐름/분류/대조 마감 상태의 source of truth 역할을 하게 된다.

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

## 기능 요구사항
- FR-1: 확인필요 큐, 잔액대조 차이, 미분류 추천 항목에 대해 별도 `review_decisions` 테이블 중심의 공통 decision envelope를 제공해야 한다. 최소 필드는 `target_type`, `target_id`, `status`, `decision_type`, `reason_code`, `memo`, `operator`, `decided_at`, `review_after`, `target_payload`여야 하며, 기존 거래/계좌 row의 회계 반영값과 운영 판정 기록을 분리한다.
- FR-2: `list_cross_transfer_review_queue`와 `get_balance_reconciliation_report`, `get_uncategorized_workbench`는 persisted decision 상태를 반영해 미처리/처리완료/보류 항목을 구분할 수 있어야 한다. preview 결과만 반환하더라도 현재 결정 상태를 함께 참조할 수 있어야 한다.
- FR-3: Streamlit workbench는 운영자가 review decision을 생성/수정/보류/재검토 표시할 수 있는 최소 작업 흐름을 제공해야 한다. 결정 결과는 해당 거래/계좌/추천 항목의 후속 집계(운영 허브, 월마감, 대조 상태)에 반영되어야 한다.
- FR-4: network MCP surface는 review decision 조회·기록·수정·보류/해제와 reconciliation session 조회·기록·마감에 필요한 additive tool을 제공해야 한다. destructive delete/reset tool은 이번 범위에서 제외하고, 기존 tool 이름과 기존 응답 필드는 유지한다.
- FR-5: `docs/data-model.md`, `docs/project-structure.md`, `docs/runtime-flows.md`에 review decision persistence, reconciliation/workbench 흐름, 운영 허브 집계 기준을 반영해야 한다.

## 비기능 요구사항
- NFR-1 (contract preservation): 기존 MCP/Streamlit 동작과 cashflow/category 의미는 review decision 도입 후에도 호환되어야 하며, 기존 응답 필드 변경은 additive 수준을 넘지 않아야 한다.
- NFR-2 (auditability): review decision은 누가/언제/어떤 근거로 판단했는지 최소한의 감사 흔적을 남겨야 하며, raw payload나 민감 원문은 저장하지 않는다.
- NFR-3 (DB safety): schema 변화는 additive/idempotent여야 하고, preview/report 재실행이 기존 persisted decision을 파괴하지 않아야 한다.
- NFR-4 (operational determinism): 같은 기준 데이터와 같은 persisted decision 세트에 대해 운영 허브의 미처리 건수, 대조 상태, 추천 수락 여부 집계가 재현 가능해야 한다.

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

- In Scope
	- 확인필요 큐 / 잔액대조 / 미분류 추천에 대한 review decision persistence 모델 정의
	- 계좌별/기준시점별 `reconciliation_sessions` 엔터티의 최소 운영 모델 정의
	- Streamlit과 network MCP workbench에서 persisted decision을 읽고 안전하게 기록/수정/보류/해제하는 흐름 정의
	- baseline 문서와 운영 허브 집계 기준 갱신 요구
- Out of Scope
	- 추가 HTTP transport/remote operation 재설계. network MCP endpoint 제공 자체는 `dcy-013`에서 완료된 선행 조건으로 간주하고, 본 주기는 review-decision tool surface만 다룬다
	- 멀티유저 권한/승인 체계, 역할별 접근제어
	- 자동 스케줄링, 푸시 알림, 외부 메시징 연동
	- AI 기반 자동 판정 확정. 이번 주기는 추천/후보 제시와 운영자 수동 결정을 전제로 한다.
	- raw financial evidence 원문 저장 확대 또는 민감자료 보관 범위 확장

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

## 리스크
- R-1 (High): review decision 모델을 거래 상태와 별도로 도입할 때 source of truth가 이원화되어, 같은 항목이 현재 category/cashflow와 persisted decision 사이에서 불일치할 수 있다.
	- 완화 방안: 어떤 필드가 "운영 판정 기록"이고 어떤 필드가 "최종 회계 반영값"인지 명시하고, decision 적용 규칙과 미적용 preview 상태를 분리한다.
- R-2 (High): 잔액대조 차이와 cross-transfer review를 같은 workbench로 묶는 과정에서 항목 단위(거래 1건 vs pair vs 계좌-session)가 섞여 UX와 데이터 모델이 복잡해질 수 있다.
	- 완화 방안: review target type을 명시적으로 분리하고, 공통 decision envelope + 타입별 payload 구조를 사용하는 방안을 우선 검토한다.
- R-3 (Medium): 운영 메모/근거 필드가 자유 텍스트로만 남으면 구조화된 보고나 재자동화에 재사용하기 어려워질 수 있다.
	- 완화 방안: 자유 메모와 함께 결정 유형, 보류 이유 코드, 재검토 여부 같은 구조화 필드를 최소셋으로 둔다.
- R-4 (Medium): 운영 허브 집계가 persisted decision을 읽기 시작하면 미처리/보류 상태 정의가 바뀌어 기존 대시보드 지표와 어긋날 수 있다.
	- 완화 방안: baseline 문서에 상태 정의를 명시하고 representative fixture/browser evidence로 운영 허브 표시를 검증한다.

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

- A-1: `accounts.statement_status`, `last_balance`, `transactions.balance_after`, `cross_transfer_review` memo tag, uncategorized recommendation 흐름을 review decision persistence의 입력 신호로 재사용할 수 있다.
- A-2: 현재 single-user 운영 모델에서는 결정자 identity를 최소 수준(예: operator string 또는 system default)으로 기록해도 충분하다. 정교한 권한 모델은 후속 범위다.
- A-3: review decision persistence는 additive schema와 기존 service 분리 구조(REQ-017/BAT-013, REQ-018/BAT-014)를 활용해 구현할 수 있다.
- A-4: GitHub Project 4에는 아직 직접 대응 카드가 없으므로, 이 Discovery가 승인되면 새 project board item 또는 후속 REQ/BAT 항목으로 대표 주제를 생성해야 한다.

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

- OQ-1: review decision을 별도 테이블로 둘지, 기존 transaction/account row의 상태 필드 확장과 혼합할지?
	- 상태: Answered
	- 결정: 별도 `review_decisions` 테이블 중심의 공통 decision envelope를 채택한다. 대상별 차이는 `target_type`, `target_id`, `target_payload`로 표현하고, 거래/계좌 row에는 최종 회계 반영값만 남겨 source of truth 이원화를 줄인다.
	- 반영 위치: FR-1, 범위 경계, REQ handoff 확인 체크, 사용자 결정 필요 항목 요약.
- OQ-2: reconciliation 결과를 계좌 단위 session으로 영속화할지, 차이 항목별 decision만 남길지?
	- 상태: Answered
	- 결정: 계좌별/기준시점별 `reconciliation_sessions`를 둔다. session은 account_id, basis_date, expected_balance, actual_balance, difference, status, closed_at을 포함하고, review decision은 session 또는 session 내 차이 항목을 target으로 삼는다.
	- 반영 위치: FR-2, In Scope, 운영 허브 우선 지표, REQ handoff 확인 체크.
- OQ-3: 미분류 추천 거부/수락 이력을 향후 자동 규칙 학습 입력으로 재사용할지, 이번 주기에서는 단순 감사 로그로만 남길지?
	- 상태: Deferred
	- 처리 방안: 이번 주기 기본값은 감사 로그 우선이며, 규칙/추천 자동화 재사용 여부는 후속 categorization intelligence 주기로 넘긴다.
	- 종료 조건: 후속 Discovery 또는 REQ에서 학습/재사용 범위를 다룰 때 재오픈한다.

### 오픈 질문 처리 기준
- `Open`: 아직 답이 없고 다음 단계 진행에 영향이 있는 상태다. 문서에 유지한다.
- `Answered`: 답이 확정된 상태다. 관련 본문/요구사항에 반영한 뒤 오픈 질문 목록에서는 제거하거나 resolved 기록으로 이동한다.
- `Deferred`: 지금 단계에서 결정하지 않고 다음 단계 또는 후속 이슈로 넘기는 상태다. 넘길 대상과 이유를 반드시 적는다.
- `Dropped`: 더 이상 유효하지 않은 질문이다. 삭제 사유를 짧게 남기고 목록에서 제거한다.
- 처리 원칙 1: 질문만 남기지 말고 반드시 `상태`, `처리 방안`, `종료 조건`을 함께 적는다.
- 처리 원칙 2: 답이 나온 질문은 본문 반영 없이 단순 삭제하지 않는다. 반영 위치를 먼저 갱신한다.
- 처리 원칙 3: High 영향 질문은 `Deferred` 처리 후 처리 방안에 REQ 인계 추적 방식을 명시한다.

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

- S-1: 운영자는 확인필요 큐, 잔액대조 차이, 미분류 추천 항목에 대해 persisted review decision을 남길 수 있고, 재조회 시 미처리/처리완료/보류 상태가 유지된다.
- S-2: 운영 허브 또는 동등한 집계 화면에서 미처리 review 건수, 보류/재검토 건수, 미대조 계좌 수, 마지막 대조 완료 시각, 미분류 추천 대기 건수가 persisted decision/session 기준으로 일관되게 표시된다.
- S-3: review decision persistence와 reconciliation/workbench 흐름이 `docs/data-model.md`, `docs/project-structure.md`, `docs/runtime-flows.md`에 반영되어 이후 REQ/BAT/verification에서 기준선으로 재사용 가능하다.
- S-4: 기존 MCP tool contract와 Streamlit 페이지 흐름은 additive 확장만 발생하고, representative pytest/AppTest/browser evidence 기준으로 회귀 없이 유지된다.

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

- S-1 측정 방식: synthetic/validation DB에서 review decision 생성 후 동일 항목 재조회 시 상태 유지 확인 / 데이터 출처: 신규 persistence 테이블 또는 상태 필드, `list_cross_transfer_review_queue`, `get_balance_reconciliation_report`, `get_uncategorized_workbench`
- S-2 측정 방식: 운영 허브/워크벤치 표시 건수와 persisted decision 상태별 count 비교 / 데이터 출처: Streamlit UI, MCP 응답, decision/session persistence rows
- S-3 측정 방식: baseline 문서 diff에서 review decision entity, workbench runtime flow, 운영 경고 집계 기준 반영 여부 확인 / 데이터 출처: `docs/data-model.md`, `docs/project-structure.md`, `docs/runtime-flows.md`
- S-4 측정 방식: representative pytest/AppTest/contract regression/browser evidence 통과 여부 확인 / 데이터 출처: `tests/`, browser evidence artifact, MCP discovery/contract tests

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

- [x] 범위(In Scope/Out of Scope) 초안 제시
	- 기준: review decision persistence/workbench 모델과 해당 기능의 network MCP tool surface는 포함하고, 추가 transport 구현/멀티유저/알림/자동 판정 확정은 제외로 제안했다.
- [x] 성공 지표의 측정 방식/데이터 출처 초안 제시
	- 기준: persisted decision 재조회, 운영 허브 집계, baseline 문서 반영, 대표 회귀 검증을 데이터 출처와 함께 연결했다.
- [x] High 영향 리스크에 대한 구조 대안 확정
	- 기준: 별도 `review_decisions` 테이블 중심의 공통 decision envelope와 계좌별/기준시점별 `reconciliation_sessions` 모델을 채택한다.
- [x] 병렬 주기 충돌 여부 검토
	- 기준: 현재 GitHub Project Todo는 `Import provenance 및 민감자료 저장 정책 정리`, `Phase 8: optional HTTP adapter 준비` 2개이며, 본 Discovery는 review decision/workbench persistence라는 별도 문제 정의를 다루므로 병렬 신규 주기로 생성 가능하다.
- [x] Freeze 확정 담당자(CONFIRMED_BY) 지정
	- 기준: 사용자가 권고안을 승인했으므로 `고진환`을 Confirmed By로 기록한다.

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

- 처리 결과: 생성
- 생성 경로: `docs/discovery/dcy-012_20260703_review-queue-reconciliation-workbench-persistence.md`
- 참조 문서:
	- `docs/discovery/dcy-003_20260629_statement-unavailable-manual-evidence-balance-reconciliation.md`
	- `docs/discovery/dcy-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow.md`
	- `docs/discovery/dcy-011_20260703_backend-refactor-phase4-write-import-workflow-adapter-narrowing.md`
	- `docs/data-model.md`
	- `docs/project-structure.md`
	- `docs/runtime-flows.md`
	- `stage-pilot/templates/project-structure.md`
	- `stage-pilot/templates/runtime-flows.md`

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

## DECIDE
- DECIDE_REVIEW_DECISION_STORAGE_MODEL: 승인됨 — 별도 `review_decisions` 테이블 중심의 공통 decision envelope를 채택한다. 대상별 차이는 `target_type`, `target_id`, `target_payload`로 표현한다.
- DECIDE_RECONCILIATION_SESSION_MODEL: 승인됨 — 잔액대조는 계좌별/기준시점별 `reconciliation_sessions`를 두고, decision은 session 또는 session 내 차이 항목을 target으로 삼는다.

## CONFIRM
- CONFIRM_REVIEW_DECISION_VALUE_SET: 승인됨 — 사용자 표시값은 `확인필요`, `계좌이동`, `실지출`, `실수입`, `투자이동`, `분석제외`, `보류/재검토`를 기본으로 하되, 내부 모델은 `status`와 `decision_type`을 분리한다.
  - `status`: `pending`, `decided`, `held`, `needs_recheck`, `ignored`
  - `decision_type`: `account_transfer`, `real_expense`, `real_income`, `investment_transfer`, `excluded_from_analysis`, `duplicate_or_cancel`, `unknown`
- CONFIRM_MCP_SURFACE_SCOPE: 승인됨 — network MCP에도 review decision 조회·기록·수정·보류/해제와 reconciliation session 조회·기록·마감 도구를 additive로 포함한다. destructive delete/reset 도구는 제외한다.

## DATA
- DATA_RECONCILIATION_WORKBENCH_PRIORITIES: 승인됨 — 운영 허브 우선 지표는 1) 미처리 review 건수, 2) 보류/재검토 건수, 3) 미대조 계좌 수, 4) 마지막 대조 완료 시각, 5) 미분류 추천 대기 건수 순으로 둔다.

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

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

## Freeze 플래그
- Handoff Decision: 승인
- Handoff Rationale: 사용자가 권고안을 승인하여 review decision storage model, reconciliation session model, decision value set, MCP surface scope, 운영 허브 우선 지표, 승인자가 모두 확정되었다. REQ-020 초안 작성으로 인계 가능하다.
- Ready for REQ Drafting: true
- Confirmed By: 고진환
- Confirmed At (KST): 2026-07-07 23:37 KST