gitea-impl-agent/jarca-ledger-mcp
1
0
Fork 0
forked from jsfamily/jarca-ledger-mcp
Code Pull Requests Activity
Files
37d23b0c5f303151d88f5f771ce5b2d8a00026fd
jarca-ledger-mcp/docs/discovery/dcy-001_20260626_streamlit-ux-e2e-categorization-refund-workflows.md
T
Jarca 67d8d4871b feat: add ledger backup safety workflow 
confirm dcy-002 and add REQ/BAT evidence

add ledger backup/status metadata workflow

document restore as runbook/script-only guarded operation

add synthetic DB backup/restore smoke tests
2026-06-27 10:40:06 +09:00

18 KiB
Raw Blame History

0. 문서 상태

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

  • 상태: approved
  • 문서 ID: dcy-001_20260626_streamlit-ux-e2e-categorization-refund-workflows
  • 이슈명: Streamlit 운영 UX/E2E 검증 및 분류·환급 워크플로우 안정화
  • 작성 시각(KST): 2026-06-26 22:38
  • 마지막 갱신 시각(KST): 2026-06-26 23:31
  • 대체됨: 없음
  • 후속 Discovery 참조: docs/discovery/dcy-002_20260627_operational-safety-backup-restore-validation-db.md
  • 생성된 REQ 참조: REQ-001 (docs/srs/Interface/req-001_category-rule-ops.md)

1. 계획 상태 요약

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

  • 연계 문서 현황:
    • 관련 점수 파일: 미생성
    • 관련 TODO/메모: 없음
  • 해석:
    • StagePilot baseline 초기화 이후 첫 real Discovery로, 현재 저장소에는 Discovery/REQ/Batch/Release 이력이 없고 baseline 문서만 존재한다.
    • 이번 Discovery는 Jarca Ledger MCP의 핵심 운영 화면인 Streamlit 대시보드에서 분류, 확인필요 큐, 취소/환급 원거래 연결, import/rollback 흐름을 실제 사용 가능한 수준으로 검증·안정화하는 범위를 정의한다.

2. 요구사항 판정 결과

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

  • 판정: 신규
  • 근거
    • docs/discovery/에는 현재 index.md만 존재하며, 기존 Discovery 문서가 없어 중복 또는 갱신 대상이 없다.
    • baseline 문서들이 공통적으로 Streamlit UX/E2E 검증, 분류 규칙 삭제, 취소/환급 원거래 연결, import E2E를 gap으로 기록하고 있어 독립 Discovery로 추적할 필요가 있다.

3. 문제점의 요약

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

  • 현재 상태
    • dashboard/app.py에는 미분류 거래 수정, 연결거래찾기, 원거래 후보 dialog, 분류 규칙 생성/수정, Import 관련 UI가 구현되어 있고, service.py에는 find_cancel_original_candidates, find_self_transfer_candidates, import batch, categorization, cashflow_kind 관련 서비스 로직이 구현되어 있다.
    • 그러나 baseline 문서 기준으로 브라우저 레벨 UX 검증, 실제 row 기반 import preview/import/rollback, 분류 규칙 삭제 및 취소/환급 원거래 연결 흐름에 대한 명시적 acceptance criteria와 E2E 검증 증거가 아직 없다.
  • 기대 상태
    • 운영자가 Streamlit 대시보드에서 실제 가계부 DB를 대상으로 거래 분류, 규칙 생성/수정/삭제, 확인필요 큐 처리, 취소/환급 원거래 연결, import batch 조회/rollback을 끊김 없이 수행할 수 있다.
    • cashflow_kind가 실제 수입/지출과 계좌이동·투자이동·분석제외를 올바르게 구분하며, UI 조작 후 월간 현금흐름/카테고리 지출/고정비 등 보고서가 일관된 결과를 보여준다.
  • 이해관계자
    • Jarca Ledger 운영자: 실제 가계부 데이터를 검토하고 분류·정정·import를 수행하는 사용자
    • Jarca/Hermes Agent: MCP 도구와 서비스 레이어를 통해 거래 조회, 분류, 보고, 검증을 보조하는 자동화 주체
    • 프로젝트 유지보수자: Streamlit UI, service layer, parser, SQLite schema, 테스트/문서를 유지하는 개발 주체
  • 제약사항
    • 금융/가계부 데이터와 PDF/XLSX 원본은 민감정보이므로 테스트·문서·커밋에 실제 원본 데이터나 비밀번호를 남기지 않는다.
    • 기존 MCP tool 성공 응답 shape와 cashflow_kind 의미론은 호환성을 우선하며, 파괴적 DB migration 없이 검증 가능한 개선부터 진행한다.

주요 사용자 시나리오

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

  • 운영자가 새로 import한 거래 중 미분류/확인필요 항목을 Streamlit에서 확인하고, 개별 거래를 분류한 뒤 같은 merchant에 대한 규칙을 저장한다.
  • 운영자가 카드 취소/환급 입금 거래를 선택하고 원거래 후보 dialog에서 실제 원거래를 연결한 뒤, 지출/환급 보고서가 중복 없이 반영되는지 확인한다.
  • 운영자가 KB Bank, Toss Bank, Toss Securities, SeoulPay 자료를 preview/import하고, 잘못 들어온 batch를 rollback하여 DB와 UI 상태가 일관되게 복구되는지 확인한다.

4. 이번에 정의할 변경

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

  • Streamlit 대시보드의 분류·규칙·확인필요 큐 UX를 운영 시나리오 단위로 검증하고, 발견된 결함을 REQ 후보로 분리한다.
  • 취소/환급 원거래 후보 탐색과 수동 연결 workflow를 실제 데이터 샘플 또는 안전한 fixture로 검증하고, 보고서 반영 기준을 정의한다.
  • import preview/import/rollback E2E와 cashflow_kind 기반 보고서 일관성 검증 범위를 정의하고, 필요한 테스트/문서 갱신 항목을 도출한다.

영향 범위

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

  • 코드 영향:
    • dashboard/app.py: 분류 규칙 UI, 미분류/확인필요 큐, 연결거래/원거래 후보 dialog, import/rollback 화면.
    • jarca_ledger_mcp/service.py: category rule CRUD/apply, cancel-original candidate/linking, self-transfer matching, import batch rollback, report aggregation.
    • tests/: service regression과 필요 시 dashboard smoke/E2E 또는 fixture 기반 검증 추가.
  • 문서 영향:
    • docs/discovery/index.md: 이번 Discovery 항목 추가.
    • 후속 REQ/SRS 문서: UI acceptance criteria, E2E 검증 조건, 보고서 일관성 조건을 기능/비기능 요구로 분리.
    • 필요 시 docs/runtime-flows.md와 docs/interface-contract.md: 검증 완료 후 확정된 Streamlit 운영 flow와 UI contract 갱신.
  • 운영 영향:
    • 실제 DB를 직접 건드리는 검증은 backup 또는 fixture DB에서 먼저 수행해야 한다.
    • 사용자 운영 DB에 적용하는 변경은 import rollback과 category/report 결과를 재확인한 뒤 진행해야 한다.

5. 요구사항 목록

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

기능 요구사항

  • FR-1: Streamlit 분류 규칙 화면은 규칙 목록, 생성, 수정, 삭제, preview/apply 진입을 제공하고, 규칙 조건(match_field, pattern, transaction_type, amount_min, amount_max, day_of_month, is_fixed)이 운영자가 이해 가능한 순서로 표시되어야 한다.
  • FR-2: 미분류/확인필요 큐 화면은 개별 거래 분류, 규칙 저장, 연결거래찾기, 원거래찾기 동작을 제공하고, 성공/실패 후 화면 상태가 최신 DB 상태와 일치해야 한다.
  • FR-3: 취소/환급 거래는 후보 탐색, 후보 비교, 수동 연결, memo/tag evidence 기록, 보고서 반영까지 하나의 검증 가능한 workflow로 정의되어야 한다.
  • FR-4: import preview/import/rollback 화면은 KB Bank PDF, Toss Bank PDF, Toss Securities PDF, SeoulPay XLSX의 preview-first 흐름과 batch rollback 결과를 사용자가 확인할 수 있어야 한다.
  • FR-5: cashflow_kind가 실제 수입/지출·이체·투자이동·부채상환·분석제외를 구분하는 방식이 UI와 report 결과에서 일관되게 확인되어야 한다.

비기능 요구사항

성능, 운영성, 일관성, 자동화 안정성 등 기능 외 요구사항을 적는다.

  • NFR-1: 실제 금융 데이터 검증은 민감정보를 노출하지 않는 fixture, masked sample, 또는 로컬 전용 DB 복사본을 사용해야 한다.
  • NFR-2: 기존 MCP tool의 성공 응답 shape와 DB schema는 후속 REQ에서 명시적으로 승인하지 않는 한 깨지지 않아야 한다.
  • NFR-3: 브라우저 레벨 검증은 재현 가능한 체크리스트 또는 자동화 가능한 smoke/E2E 절차로 남아야 한다.

범위 경계

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

  • In Scope
    • Streamlit 대시보드의 분류 규칙, 미분류/확인필요 큐, 취소/환급 원거래 연결, import/rollback, report 반영 검증.
    • service layer와 UI 간 contract mismatch, stale cache/rerun 문제, success/error 표시 문제, cashflow_kind 표시/집계 오류의 발견과 REQ화.
    • 안전한 fixture 또는 로컬 DB 복사본 기반의 E2E 검증 절차 수립.
  • Out of Scope
    • 신규 금융기관 parser 추가.
    • 파괴적 SQLite schema migration 또는 자동 backup framework 구현.
    • CI/CD 전체 구축과 배포 서비스화.
    • Jarca Ledger 외 Jarca 본체 MCP 기능 변경.

6. 리스크/가정 목록

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

리스크

  • R-1 (High): 실제 운영 DB에서 잘못된 import, rollback, category update를 실행하면 금융 데이터가 왜곡될 수 있다.
    • 완화 방안: fixture DB 또는 운영 DB 복사본에서 먼저 재현하고, 실제 DB 검증 전 backup/rollback 절차를 확인한다.
  • R-2 (Medium): Streamlit dialog/rerun/cache 동작이 서비스 성공 결과와 화면 표시를 불일치하게 만들 수 있다.
    • 완화 방안: 각 UI action 후 DB 조회와 화면 refresh 결과를 함께 검증하는 acceptance criteria를 REQ에 포함한다.
  • R-3 (Medium): 취소/환급 후보 탐색이 merchant/amount/date만으로 과도하게 매칭되어 잘못된 원거래를 추천할 수 있다.
    • 완화 방안: 후보 점수, 동일 계좌/결제수단/텍스트 근거, 수동 확인 evidence를 UI에 노출하는 기준을 정의한다.

가정

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

  • A-1: 현재 우선 목표는 기능 추가보다 이미 구현된 Streamlit 운영 workflow를 실제 사용 가능한 수준으로 검증·정리하는 것이다.
  • A-2: 테스트와 문서에는 실제 금융 원본 파일, 비밀번호, 계좌 식별정보 전체를 포함하지 않는다.
  • A-3: 후속 구현은 작은 REQ와 batch로 나누며, 기존 service success response shape와 cashflow_kind 의미론을 보존한다.

오픈 질문

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

  • OQ-1: 브라우저 레벨 검증을 수동 체크리스트 중심으로 둘지, Playwright/Selenium 같은 자동화 smoke 테스트까지 포함할지 결정해야 한다.
    • 상태: Answered
    • 결정: semi-automated. 서비스/DB 레벨 회귀 테스트를 기본 증거로 삼고, Streamlit 핵심 흐름은 브라우저 또는 스크린샷 기반 smoke 검증을 병행한다.
    • 반영 위치: NFR-3, S-1~S-3, 후속 REQ acceptance criteria 및 batch verification 계획.
  • OQ-2: 실제 운영 DB 복사본을 사용한 검증을 허용할지, 완전 synthetic fixture DB만 사용할지 결정해야 한다.
    • 상태: Answered
    • 결정: synthetic fixture 우선. 실제 재현성이 필요한 경우에만 운영 DB 복사본을 사용하되, 원본 DB 직접 mutation은 금지하고 민감정보는 보고서/문서에 노출하지 않는다.
    • 반영 위치: NFR-1, R-1 완화 방안, 후속 REQ 테스트 데이터 조건.

오픈 질문 처리 기준

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

7. 초기 성공 기준

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

  • S-1: 분류 규칙 생성/수정/삭제와 preview/apply 흐름이 fixture 또는 검증 DB에서 오류 없이 수행되고, 처리 후 rule list와 transaction category 상태가 DB와 UI에서 일치한다.
  • S-2: 취소/환급 원거래 연결 workflow가 후보 탐색, 수동 선택, memo/tag evidence 기록, 월간 cashflow/report 반영까지 재현 가능하게 검증된다.
  • S-3: 각 import source의 preview/import/rollback 핵심 경로가 중복 처리, batch 기록, rollback 후 상태를 포함해 검증되고, 실패 시 사용자에게 원인을 표시한다.
  • S-4: 후속 REQ 초안 작성에 필요한 acceptance criteria와 검증 데이터 정책이 확정되거나 명시적으로 Deferred 처리된다.

측정 방식 및 데이터 출처

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

  • S-1 측정 방식: UI action 후 service 조회와 SQLite row 상태 비교 / 데이터 출처: fixture DB, category_rules, transactions, Streamlit 화면 캡처 또는 체크리스트
  • S-2 측정 방식: 연결 전후 transaction memo/category/type/report aggregate 비교 / 데이터 출처: fixture DB, find_cancel_original_candidates, link_cancel_to_original, monthly/category report output
  • S-3 측정 방식: import batch 생성/row count/rollback status/duplicate skip count 확인 / 데이터 출처: masked sample files 또는 synthetic parser fixtures, import_batches, transactions
  • S-4 측정 방식: Discovery review 결과와 후속 REQ register 확인 / 데이터 출처: docs/discovery/, docs/srs/index.md, 후속 REQ 문서

8. REQ로 넘기기 전 확인 체크

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

  • 범위(In Scope/Out of Scope) 확정
    • 기준: Streamlit UX/E2E 검증이 이번 반복의 주 범위이고, 신규 parser/CI/DB migration은 제외 또는 후속 Discovery로 분리되는지 확인한다.
  • 성공 지표의 측정 방식/데이터 출처 확정
    • 기준: fixture DB, 운영 DB 복사본, masked sample 중 어떤 데이터를 사용할지 결정하고 각 성공 기준의 관찰 방법을 확정한다.
  • High 영향 리스크 우선순위 및 해소 책임자 지정
    • 기준: 실제 DB mutation 리스크에 대해 backup/fixture 우선 원칙과 검증 책임자를 지정한다.
  • 모든 오픈 질문(OQ) Open 상태 없음 확인
    • 기준: OQ 목록에 Open 상태 항목이 0개이거나, 잔여 항목 전부 Deferred 처리 완료
  • Freeze 확정 담당자(CONFIRMED_BY) 지정
    • 기준: 사용자가 Discovery 내용을 확인하고 REQ draft 진행 가능 여부를 명시한다.

9. 파일 처리 결과

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

  • 처리 결과: 생성
  • 생성 경로: docs/discovery/dcy-001_20260626_streamlit-ux-e2e-categorization-refund-workflows.md
  • 참조 문서:
    • docs/project-structure.md
    • docs/runtime-flows.md
    • docs/interface-contract.md
    • docs/data-model.md

10. 사용자 결정 필요 항목 요약

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

DECIDE

  • 결정 완료: 브라우저 검증 수준은 semi-automated로 한다. 서비스/DB 회귀 테스트를 기본 증거로 삼고, Streamlit 핵심 흐름은 브라우저 또는 스크린샷 기반 smoke 검증을 병행한다.
  • 결정 완료: 검증 데이터 정책은 synthetic fixture 우선 + 필요 시 운영 DB 복사본 허용으로 한다. 원본 운영 DB 직접 mutation은 금지한다.

CONFIRM

  • 확인 완료: 이번 Discovery 범위는 Streamlit UX/E2E 안정화, 분류 규칙, 확인필요 큐, 취소/환급 연결, import/rollback 검증으로 한정한다. 신규 parser/CI/파괴적 DB migration은 제외한다.
  • 확인 완료: REQ draft 및 구현 batch 진행 가능. 사용자의 명시 승인이 꼭 필요한 고위험 DB/범위 변경만 사용자에게 재확인한다. 그 외 세부 승인과 구현 진행은 자르카가 대리 승인한다.

DATA

  • 후속 작업 원칙: 민감정보를 제거한 synthetic fixture를 우선 사용하고, 실제 재현성이 필요한 경우 운영 DB 복사본에서만 검증한다.

11. Discovery Freeze

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

섹션 참조

Freeze 플래그

  • Handoff Decision: 승인
  • Handoff Rationale: 사용자 승인에 따라 자르카 추천안(semi-automated 검증, synthetic fixture 우선 + 필요 시 운영 DB 복사본, Streamlit UX/E2E 안정화 범위)을 확정했다. 후속 REQ 초안, batch 구현, 검수관 verification gate를 거쳐 confirm-req-implemented 단계까지 진행한다.
  • Ready for REQ Drafting: true
  • Confirmed By: 진환 고 / 자르카
  • Confirmed At (KST): 2026-06-26 23:27
View Git Blame Copy Permalink