From 62efc30fd88ae2e1665c4f878518e747d1dd10c2 Mon Sep 17 00:00:00 2001 From: Jarca Date: Tue, 7 Jul 2026 23:54:29 +0900 Subject: [PATCH] docs: draft review workbench requirement --- ...ue-reconciliation-workbench-persistence.md | 4 +- ...on-persistence-reconciliation-workbench.md | 121 ++++++++++++++++++ docs/srs/index.md | 4 +- 3 files changed, 126 insertions(+), 3 deletions(-) create mode 100644 docs/srs/Interface/req-020_review-decision-persistence-reconciliation-workbench.md diff --git a/docs/discovery/dcy-012_20260703_review-queue-reconciliation-workbench-persistence.md b/docs/discovery/dcy-012_20260703_review-queue-reconciliation-workbench-persistence.md index c13bc55..2328a7c 100644 --- a/docs/discovery/dcy-012_20260703_review-queue-reconciliation-workbench-persistence.md +++ b/docs/discovery/dcy-012_20260703_review-queue-reconciliation-workbench-persistence.md @@ -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가 어떤 배경에서 작성되고 있는지, 연계 문서가 있는지, 지금 시점의 해석이 무엇인지 짧게 요약한다. diff --git a/docs/srs/Interface/req-020_review-decision-persistence-reconciliation-workbench.md b/docs/srs/Interface/req-020_review-decision-persistence-reconciliation-workbench.md new file mode 100644 index 0000000..0e3864f --- /dev/null +++ b/docs/srs/Interface/req-020_review-decision-persistence-reconciliation-workbench.md @@ -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. diff --git a/docs/srs/index.md b/docs/srs/index.md index 0e3b2eb..ed7144f 100644 --- a/docs/srs/index.md +++ b/docs/srs/index.md @@ -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 요구사항으로 등록했다.