docs: confirm review workbench discovery

2026-07-07 23:39:11 +09:00
parent 7c420e498f
commit 0e4534880e
2 changed files with 33 additions and 31 deletions
@@ -1,11 +1,11 @@
 # 0. 문서 상태
 이 문서의 현재 상태와 식별 정보를 기록한다. 문서 추적과 승인 흐름에 필요한 최소 메타데이터를 적는다.
- 상태: draft
+- 상태: confirmed
 - 문서 ID: dcy-012_20260703_review-queue-reconciliation-workbench-persistence
 - 이슈명: 확인필요 큐 / 잔액대조 워크벤치 영속화 및 운영 모델 정립
 - 작성 시각(KST): 2026-07-03 10:31 KST
- 마지막 갱신 시각(KST): 2026-07-03 10:31 KST
+- 마지막 갱신 시각(KST): 2026-07-07 23:37 KST
 - 대체됨: 없음
 - 후속 Discovery 참조: 없음
 - 생성된 REQ 참조: 없음
@@ -20,7 +20,7 @@
 	- 관련 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" 단계에서 멈추지 않고, 확인필요 큐·잔액대조·미분류 검토를 하나의 운영 워크벤치로 묶는 후속 주기로 정식화한다. Phase 8 optional HTTP adapter는 별도 Deferred 후보로 유지하고 본 주기 범위에 포함하지 않는다.
+	- 따라서 이번 Discovery는 dcy-003이 정의한 수동 증빙/잔액대조 규칙을 "preview/report" 단계에서 멈추지 않고, 확인필요 큐·잔액대조·미분류 검토를 하나의 운영 워크벤치로 묶는 후속 주기로 정식화한다. HTTP/network MCP endpoint 제공은 후속 `dcy-013`에서 별도 완료되었으므로 본 주기는 transport 구현이 아니라 review-decision/workbench persistence와 해당 기능의 MCP tool surface 범위에 집중한다.
 # 2. 요구사항 판정 결과
 이번 요청이 기존 요구사항과 비교해 신규인지, 유사한지, 중복인지 판단하고 그 근거를 남긴다.
@@ -91,10 +91,10 @@
 실제로 구현과 검증으로 이어질 요구사항을 기능/비기능으로 나누어 정리하고, 범위 경계를 명확히 적는다.
 ## 기능 요구사항
- FR-1: 확인필요 큐, 잔액대조 차이, 미분류 추천 항목에 대해 공통 또는 호환 가능한 `review decision` 저장 모델을 제공해야 한다. 최소 필드는 대상 타입(queue/reconciliation/uncategorized), 대상 식별자, 결정 상태, 결정 유형, 근거 메모, 결정 시각, 재검토 필요 여부여야 한다.
+- 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: MCP surface는 review queue decision 조회·기록·보류/해제 등 운영 자동화에 필요한 최소 도구를 제공하거나, 제공하지 않는다면 그 제외 경계를 명확히 정의해야 한다. 기존 tool 이름은 유지하고 필요한 경우 additive new tools로 확장한다.
+- 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 흐름, 운영 허브 집계 기준을 반영해야 한다.
 ## 비기능 요구사항
@@ -108,11 +108,11 @@
 - In Scope
 	- 확인필요 큐 / 잔액대조 / 미분류 추천에 대한 review decision persistence 모델 정의
-	- reconciliation session 또는 동등한 정리 단위의 최소 운영 모델 정의
+	- 계좌별/기준시점별 `reconciliation_sessions` 엔터티의 최소 운영 모델 정의
-	- Streamlit/MCP workbench에서 persisted decision을 읽고 갱신하는 흐름 정의
+	- Streamlit과 network MCP workbench에서 persisted decision을 읽고 안전하게 기록/수정/보류/해제하는 흐름 정의
 	- baseline 문서와 운영 허브 집계 기준 갱신 요구
 - Out of Scope
-	- Phase 8 optional HTTP adapter(`adapters/http/*`) 구현 또는 원격 운영 재설계
+	- 추가 HTTP transport/remote operation 재설계. network MCP endpoint 제공 자체는 `dcy-013`에서 완료된 선행 조건으로 간주하고, 본 주기는 review-decision tool surface만 다룬다
 	- 멀티유저 권한/승인 체계, 역할별 접근제어
 	- 자동 스케줄링, 푸시 알림, 외부 메시징 연동
 	- AI 기반 자동 판정 확정. 이번 주기는 추천/후보 제시와 운영자 수동 결정을 전제로 한다.
@@ -143,13 +143,13 @@
 답을 아직 모르는 항목을 적는다. 추정으로 덮지 말고 REQ 초안 작성 이전에 확인할 질문으로 남긴다.
 - OQ-1: review decision을 별도 테이블로 둘지, 기존 transaction/account row의 상태 필드 확장과 혼합할지?
-	- 상태: Open
+	- 상태: Answered
-	- 처리 방안: REQ 초안에서 대안 A(별도 decision table) / 대안 B(기존 row 상태 확장) / 대안 C(공통 envelope + 타입별 payload) 비교 후 결정한다.
+	- 결정: 별도 `review_decisions` 테이블 중심의 공통 decision envelope를 채택한다. 대상별 차이는 `target_type`, `target_id`, `target_payload`로 표현하고, 거래/계좌 row에는 최종 회계 반영값만 남겨 source of truth 이원화를 줄인다.
-	- 종료 조건: persistence source of truth와 migration 경로가 REQ에서 단일안으로 확정되면 종료한다.
+	- 반영 위치: FR-1, 범위 경계, REQ handoff 확인 체크, 사용자 결정 필요 항목 요약.
 - OQ-2: reconciliation 결과를 계좌 단위 session으로 영속화할지, 차이 항목별 decision만 남길지?
-	- 상태: Open
+	- 상태: Answered
-	- 처리 방안: 운영 허브/월마감에서 필요한 집계(미대조 계좌, 보류 예외, 완료 시각)를 기준으로 session 단위의 필요성을 판단한다.
+	- 결정: 계좌별/기준시점별 `reconciliation_sessions`를 둔다. session은 account_id, basis_date, expected_balance, actual_balance, difference, status, closed_at을 포함하고, review decision은 session 또는 session 내 차이 항목을 target으로 삼는다.
-	- 종료 조건: REQ에서 session entity 필요 여부와 최소 필드가 확정되면 종료한다.
+	- 반영 위치: FR-2, In Scope, 운영 허브 우선 지표, REQ handoff 확인 체크.
 - OQ-3: 미분류 추천 거부/수락 이력을 향후 자동 규칙 학습 입력으로 재사용할지, 이번 주기에서는 단순 감사 로그로만 남길지?
 	- 상태: Deferred
 	- 처리 방안: 이번 주기 기본값은 감사 로그 우선이며, 규칙/추천 자동화 재사용 여부는 후속 categorization intelligence 주기로 넘긴다.
@@ -168,7 +168,7 @@
 이 변경이 성공했다고 판단할 기준을 측정 가능하게 정의한다. 가능하면 데이터 출처까지 연결한다.
 - S-1: 운영자는 확인필요 큐, 잔액대조 차이, 미분류 추천 항목에 대해 persisted review decision을 남길 수 있고, 재조회 시 미처리/처리완료/보류 상태가 유지된다.
- S-2: 운영 허브 또는 동등한 집계 화면에서 미처리 review 항목 수, 보류/재검토 항목 수, 미대조 계좌 상태가 persisted 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 기준으로 회귀 없이 유지된다.
@@ -184,15 +184,15 @@
 REQ 초안 작성 단계로 넘기기 전에 무엇이 확정되어야 하는지 확인한다. 미완료 항목은 후속 결정이 필요함을 뜻한다.
 - [x] 범위(In Scope/Out of Scope) 초안 제시
-	- 기준: review decision persistence/workbench 모델은 포함하고, HTTP adapter/멀티유저/알림/자동 판정 확정은 제외로 제안했다.
+	- 기준: review decision persistence/workbench 모델과 해당 기능의 network MCP tool surface는 포함하고, 추가 transport 구현/멀티유저/알림/자동 판정 확정은 제외로 제안했다.
 - [x] 성공 지표의 측정 방식/데이터 출처 초안 제시
 	- 기준: persisted decision 재조회, 운영 허브 집계, baseline 문서 반영, 대표 회귀 검증을 데이터 출처와 함께 연결했다.
- [ ] High 영향 리스크에 대한 구조 대안 확정
+- [x] High 영향 리스크에 대한 구조 대안 확정
-	- 기준: OQ-1/OQ-2에서 persistence source of truth와 session 모델이 확정되어야 한다.
+	- 기준: 별도 `review_decisions` 테이블 중심의 공통 decision envelope와 계좌별/기준시점별 `reconciliation_sessions` 모델을 채택한다.
 - [x] 병렬 주기 충돌 여부 검토
 	- 기준: 현재 GitHub Project Todo는 `Import provenance 및 민감자료 저장 정책 정리`, `Phase 8: optional HTTP adapter 준비` 2개이며, 본 Discovery는 review decision/workbench persistence라는 별도 문제 정의를 다루므로 병렬 신규 주기로 생성 가능하다.
- [ ] Freeze 확정 담당자(CONFIRMED_BY) 지정
+- [x] Freeze 확정 담당자(CONFIRMED_BY) 지정
-	- 기준: 사용자가 범위/판정 모델 초안을 승인하면 Confirmed By/At를 기록한다.
+	- 기준: 사용자가 권고안을 승인했으므로 `고진환`을 Confirmed By로 기록한다.
 # 9. 파일 처리 결과
 이 Discovery 문서 생성/갱신 결과와 참조 문서를 기록한다. 이후 추적과 리뷰 시 근거로 사용한다.
@@ -213,15 +213,17 @@ REQ 초안 작성 단계로 넘기기 전에 무엇이 확정되어야 하는지
 사용자나 승인자가 결정해야 하는 항목만 모아 정리한다. 결정, 확인, 데이터 요청을 구분해서 적는다.
 ## DECIDE
- {{DECIDE_REVIEW_DECISION_STORAGE_MODEL}} — review decision을 별도 테이블 중심으로 둘지, 기존 거래/계좌 상태 확장 중심으로 둘지, 혼합 모델로 둘지 결정 필요
+- DECIDE_REVIEW_DECISION_STORAGE_MODEL: 승인됨 — 별도 `review_decisions` 테이블 중심의 공통 decision envelope를 채택한다. 대상별 차이는 `target_type`, `target_id`, `target_payload`로 표현한다.
- {{DECIDE_RECONCILIATION_SESSION_MODEL}} — 잔액대조를 계좌별 session 단위로 기록할지, decision 단위 기록만으로 충분한지 결정 필요
+- DECIDE_RECONCILIATION_SESSION_MODEL: 승인됨 — 잔액대조는 계좌별/기준시점별 `reconciliation_sessions`를 두고, decision은 session 또는 session 내 차이 항목을 target으로 삼는다.
 ## CONFIRM
- {{CONFIRM_REVIEW_DECISION_VALUE_SET}} — `확인필요`, `계좌이동`, `실지출`, `실수입`, `투자이동`, `분석제외`, `보류/재검토`를 기본 결정 집합으로 사용할지 확인 필요
+- CONFIRM_REVIEW_DECISION_VALUE_SET: 승인됨 — 사용자 표시값은 `확인필요`, `계좌이동`, `실지출`, `실수입`, `투자이동`, `분석제외`, `보류/재검토`를 기본으로 하되, 내부 모델은 `status`와 `decision_type`을 분리한다.
- {{CONFIRM_MCP_SURFACE_SCOPE}} — MCP에 review decision mutation 도구를 추가하는 것을 이번 주기 범위에 포함할지, Streamlit 우선으로 두고 MCP는 조회만 허용할지 확인 필요
+  - `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}} — 월마감/운영 허브에서 가장 먼저 보고 싶은 상태 지표(예: 미처리 review 건수, 보류 건수, 미대조 계좌 수, 마지막 대조 완료 시각) 우선순위 필요
+- DATA_RECONCILIATION_WORKBENCH_PRIORITIES: 승인됨 — 운영 허브 우선 지표는 1) 미처리 review 건수, 2) 보류/재검토 건수, 3) 미대조 계좌 수, 4) 마지막 대조 완료 시각, 5) 미분류 추천 대기 건수 순으로 둔다.
 # 11. Discovery Freeze
 REQ 초안 작성 인계 시점의 확정 플래그와 섹션 참조만 기록한다. 내용 재작성 없이 원본 섹션을 링크로 대신한다.
@@ -234,8 +236,8 @@ REQ 초안 작성 인계 시점의 확정 플래그와 섹션 참조만 기록
 - 사용자 결정 필요: [# 10. 사용자 결정 필요 항목 요약](#10-사용자-결정-필요-항목-요약)
 ## Freeze 플래그
- Handoff Decision: 보류
+- Handoff Decision: 승인
- Handoff Rationale: 초기 Discovery 초안 생성 완료. persistence source of truth, reconciliation session 모델, MCP surface 범위에 대한 사용자 확인이 남아 있어 REQ 초안 작성 전 confirm-discovery 단계가 필요하다.
+- Handoff Rationale: 사용자가 권고안을 승인하여 review decision storage model, reconciliation session model, decision value set, MCP surface scope, 운영 허브 우선 지표, 승인자가 모두 확정되었다. REQ-020 초안 작성으로 인계 가능하다.
- Ready for REQ Drafting: false
+- Ready for REQ Drafting: true
- Confirmed By: {{CONFIRMED_BY}}
+- Confirmed By: 고진환
- Confirmed At (KST): {{CONFIRMED_AT_KST}}
+- Confirmed At (KST): 2026-07-07 23:37 KST
@@ -17,5 +17,5 @@
 | dcy-009_20260701_manual-asset-crud-month-end-snapshot-close-workflow | 20260701 | 수기 자산 CRUD + 월말 스냅샷 생성/마감 운영 워크플로우 | [Discovery](./dcy-009_20260701_manual-asset-crud-month-end-snapshot-close-workflow.md) | confirmed |
 | dcy-010_20260702_backend-core-layering-mcp-adapter-realignment | 20260702 | Jarca Ledger 백엔드 코어 분리 및 layered 아키텍처 재편, MCP adapter 재정렬 | [Discovery](./dcy-010_20260702_backend-core-layering-mcp-adapter-realignment.md) | confirmed |
 | dcy-011_20260703_backend-refactor-phase4-write-import-workflow-adapter-narrowing | 20260703 | Jarca Ledger 백엔드 리팩터링 Phase 4+ 후속 주기 (write service 분리 → import pipeline 분리 → advanced finance workflow 분리 → MCP/Streamlit adapter 표면 축소) | [Discovery](./dcy-011_20260703_backend-refactor-phase4-write-import-workflow-adapter-narrowing.md) | confirmed |
-| dcy-012_20260703_review-queue-reconciliation-workbench-persistence | 20260703 | 확인필요 큐 / 잔액대조 워크벤치 영속화 및 운영 모델 정립 | [Discovery](./dcy-012_20260703_review-queue-reconciliation-workbench-persistence.md) | draft |
+| dcy-012_20260703_review-queue-reconciliation-workbench-persistence | 20260703 | 확인필요 큐 / 잔액대조 워크벤치 영속화 및 운영 모델 정립 | [Discovery](./dcy-012_20260703_review-queue-reconciliation-workbench-persistence.md) | confirmed |
 | dcy-013_20260707_docker-network-mcp-deployment | 20260707 | Jarca Ledger 독립 Docker 배포 및 network MCP endpoint 제공 | [Discovery](./dcy-013_20260707_docker-network-mcp-deployment.md) | confirmed |