docs: draft review workbench requirement

2026-07-07 23:54:29 +09:00
parent 0e4534880e
commit 62efc30fd8
3 changed files with 126 additions and 3 deletions
@@ -5,10 +5,10 @@
 - 문서 ID: dcy-012_20260703_review-queue-reconciliation-workbench-persistence
 - 이슈명: 확인필요 큐 / 잔액대조 워크벤치 영속화 및 운영 모델 정립
 - 작성 시각(KST): 2026-07-03 10:31 KST
- 마지막 갱신 시각(KST): 2026-07-07 23:37 KST
+- 마지막 갱신 시각(KST): 2026-07-07 23:53 KST
 - 대체됨: 없음
 - 후속 Discovery 참조: 없음
- 생성된 REQ 참조: 없음
+- 생성된 REQ 참조: `REQ-020` (`docs/srs/Interface/req-020_review-decision-persistence-reconciliation-workbench.md`)

 # 1. 계획 상태 요약
 현재 Discovery가 어떤 배경에서 작성되고 있는지, 연계 문서가 있는지, 지금 시점의 해석이 무엇인지 짧게 요약한다.
@@ -0,0 +1,121 @@
+# req-020: Review decision persistence and reconciliation workbench
+
+- Status: Proposed
+- 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.
@@ -33,7 +33,7 @@

 ## Next Requirement ID

- Current: `REQ-020`
+- Current: `REQ-021`
 - Rule: `Requirement Register`에 있는 가장 큰 REQ 번호보다 정확히 1 커야 한다.

 ## Requirement Register
@@ -59,6 +59,7 @@
 | REQ-017 | Advanced finance workflow service split and compatibility-preserving domain isolation | Non-Functional | Implemented | High | 렛저장인 | [req-017_advanced-finance-workflow-service-split.md](Non-Functional/req-017_advanced-finance-workflow-service-split.md) |
 | REQ-018 | MCP/Streamlit adapter surface narrowing and baseline refresh for dcy-011 completion | Interface | Implemented | High | 렛저장인 | [req-018_adapter-surface-narrowing-baseline-refresh.md](Interface/req-018_adapter-surface-narrowing-baseline-refresh.md) |
 | REQ-019 | Docker network MCP deployment and operating DB migration | Deployment | Implemented | High | 렛저장인 | [req-019_docker-network-mcp-deployment.md](Deployment/req-019_docker-network-mcp-deployment.md) |
+| REQ-020 | Review decision persistence and reconciliation workbench | Interface | Proposed | High | 렛저장인 | [req-020_review-decision-persistence-reconciliation-workbench.md](Interface/req-020_review-decision-persistence-reconciliation-workbench.md) |

 ## Recent Change Log Summary

@@ -94,3 +95,4 @@
 - 2026-07-03 08:03 KST: dcy-011 Phase 7 adapter narrowing + baseline refresh 범위를 `REQ-018`로 생성하고 BAT-014 입력으로 Approved 상태를 확정했다.
 - 2026-07-03 08:23 KST: BAT-014 adapter narrowing + baseline refresh 구현과 AppTest/full pytest/MCP discovery evidence를 근거로 `REQ-018`을 Implemented로 전환했다.
 - 2026-07-07 22:23 KST: dcy-013 Docker network MCP 배포 범위로 REQ-019를 생성하고, BAT-015 구현·검증 evidence 및 운영 DB 이전 완료를 근거로 Implemented 상태로 등록했다.
+- 2026-07-07 23:53 KST: dcy-012 confirmed 범위를 `REQ-020` Proposed 상태로 생성하고 review decision persistence/reconciliation workbench 요구사항으로 등록했다.