gitea-impl-agent/jarca-ledger-mcp
1
0
Fork 0
forked from jsfamily/jarca-ledger-mcp
Code Pull Requests Activity
Files
0f881b245fecdeb01ecb3bed8fc474b5894e862e
jarca-ledger-mcp/docs/discovery/dcy-001_20260626_streamlit-ux-e2e-categorization-refund-workflows.md
T
Jarca 0f881b245f feat: stabilize category rule operations 
approve dcy-001 and add REQ/BAT evidence

pass selected DB path through Streamlit rule actions

expose delete_category_rule MCP tool

add category rule deletion regression
2026-06-27 00:02:06 +09:00

217 lines
18 KiB
Markdown
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 참조: 없음
- 생성된 REQ 참조: REQ-001 ([docs/srs/Interface/req-001_category-rule-ops.md](../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 초안 작성 단계로 넘기기 전에 무엇이 확정되어야 하는지 확인한다. 미완료 항목은 후속 결정이 필요함을 뜻한다.
- [x] 범위(In Scope/Out of Scope) 확정
- 기준: Streamlit UX/E2E 검증이 이번 반복의 주 범위이고, 신규 parser/CI/DB migration은 제외 또는 후속 Discovery로 분리되는지 확인한다.
- [x] 성공 지표의 측정 방식/데이터 출처 확정
- 기준: fixture DB, 운영 DB 복사본, masked sample 중 어떤 데이터를 사용할지 결정하고 각 성공 기준의 관찰 방법을 확정한다.
- [x] High 영향 리스크 우선순위 및 해소 책임자 지정
- 기준: 실제 DB mutation 리스크에 대해 backup/fixture 우선 원칙과 검증 책임자를 지정한다.
- [x] 모든 오픈 질문(OQ) `Open` 상태 없음 확인
- 기준: OQ 목록에 `Open` 상태 항목이 0개이거나, 잔여 항목 전부 `Deferred` 처리 완료
- [x] 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 초안 작성 인계 시점의 확정 플래그와 섹션 참조만 기록한다. 내용 재작성 없이 원본 섹션을 링크로 대신한다.
## 섹션 참조
- 범위: [# 5. 요구사항 목록 > 범위 경계](#5-요구사항-목록)
- 리스크/오픈 질문: [# 6. 리스크/가정 목록](#6-리스크가정-목록)
- 성공 기준: [# 7. 초기 성공 기준](#7-초기-성공-기준)
- 인계 전 확인: [# 8. REQ로 넘기기 전 확인 체크](#8-req로-넘기기-전-확인-체크)
- 사용자 결정 필요: [# 10. 사용자 결정 필요 항목 요약](#10-사용자-결정-필요-항목-요약)
## 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