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-014_20260708_import-provenance-sensitive-data-policy.md
T

20 KiB
Raw Blame History

0. 문서 상태

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

  • 상태: confirmed
  • 문서 ID: dcy-014_20260708_import-provenance-sensitive-data-policy
  • 이슈명: Import provenance 및 민감자료 저장 정책 정리
  • 작성 시각(KST): 2026-07-08 10:48 KST
  • 마지막 갱신 시각(KST): 2026-07-08 11:26 KST
  • 대체됨: 없음
  • 후속 Discovery 참조: 없음
  • 생성된 REQ 참조: REQ-021

1. 계획 상태 요약

  • 연계 문서 현황:
    • GitHub Project 4 Jarca Todo: Import provenance 및 민감자료 저장 정책 정리
    • 선행 Discovery: dcy-002 운영 안전 백업/복구/검증 DB 정책, dcy-006 CI fixture 안전 정책, dcy-011 import pipeline 분리, dcy-012 review decision payload 최소화, dcy-013 Docker network MCP 배포
    • 관련 baseline 문서: docs/data-model.md, docs/project-structure.md, docs/runtime-flows.md
    • 다음 REQ 번호: REQ-021
  • 해석:
    • Jarca Ledger는 PDF/XLSX/CSV import와 rollback/audit을 이미 제공하지만, source file path, raw payload, parser metadata, row-level provenance, 민감자료 최소보관 정책이 하나의 표준으로 정리되어 있지 않다.
    • finance agent와 network MCP 소비자가 늘어나는 상태에서 import lineage와 민감정보 경계를 명확히 정의하지 않으면 운영 DB, test fixture, logs, Streamlit/MCP 응답에 원본 금융 증빙이 과다 노출될 위험이 있다.

2. 요구사항 판정 결과

  • 판정: 신규 후속 주기
  • 근거
    • 기존 dcy-011/REQ-016은 import pipeline의 application/infrastructure layering을 다뤘고, provenance schema·민감자료 저장 정책 자체를 요구사항으로 확정하지 않았다.
    • dcy-012/REQ-020은 review decision target_payload에서 raw payload/password/token/secret/file path를 제거하는 국소 정책을 추가했지만, import 전반의 provenance·retention·MCP 노출 정책은 별도 Discovery로 다루는 것이 책임 경계가 명확하다.

3. 문제점의 요약

  • 현재 상태
    • transactions에는 source, import_batch_id, external_id, dedupe_key, raw_summary, raw_payload, counterparty, branch 등 import evidence 성격의 필드가 존재한다.
    • import_batches는 source, filename, imported_at, row_count, status, memo를 저장하며, 일부 import path는 memo JSON 안에 source_hash, parser metadata, validation, parsed row count를 저장한다.
    • imports_service.py는 KB Bank PDF, Toss Bank PDF, Toss Securities PDF, SeoulPay XLSX, CSV import에서 source hash, parser preview, validation, duplicate check, rollback을 처리한다.
    • docs/data-model.md는 import evidence field 보존과 raw payload의 민감성, password runtime-only 원칙을 언급하지만, row-level provenance 최소 필드·filename masking/hash·retention·MCP/Streamlit 노출 정책은 아직 확정되지 않았다.
    • docs/runtime-flows.md는 import preview/import flow를 설명하지만, source file 처리·row index 추적·raw evidence storage boundary·agent-facing response boundary는 구체화되어 있지 않다.
  • 기대 상태
    • import provenance는 rollback/audit/dedupe/reconciliation에 필요한 최소 필드로 표준화된다.
    • 원본 파일명, 전체 파일 경로, PDF text, raw payload, 계좌/카드 식별자, 비밀번호, token/secret류는 DB/repo/log/MCP 응답에서 최소보관·마스킹·해시화 원칙을 따른다.
    • 운영 DB와 synthetic/validation fixture의 민감자료 경계가 명확해지고, CI/AppTest/HTTP smoke가 실데이터를 참조하지 않는다는 기존 dcy-006 원칙과 연결된다.
    • finance agent가 MCP를 통해 provenance를 읽을 때 필요한 audit metadata만 받고 원본 금융 증빙은 받지 않는다.
  • 이해관계자
    • 주인님/운영자 — 실제 가계 금융 원본자료와 운영 DB의 소유자
    • finance agent — Jarca Ledger MCP를 소비하는 agent, raw evidence 대신 안전한 lineage metadata가 필요하다.
    • 가웨인/dev-butler — 데이터 모델, import interface, MCP/Streamlit 노출 경계를 설계·검증하는 기술 책임자
    • 향후 QC/감사 작업자 — rollback/audit/reconciliation 근거를 검증하되 원본 민감자료에 과도하게 접근하지 않아야 한다.
  • 주요 사용자 시나리오
    • 운영자가 KB/Toss/SeoulPay/CSV 파일을 preview/import할 때, 시스템은 거래 row가 어느 source/parser/batch에서 왔는지 추적 가능한 metadata를 남긴다.
    • 운영자가 duplicate, rollback, reconciliation 문제를 조사할 때, 원본 파일 전체나 raw payload 없이도 batch/source hash/row reference로 원인을 좁힐 수 있다.
    • finance agent가 MCP로 거래·import 상태를 조회할 때, 민감한 file path/password/raw text는 응답에 포함되지 않는다.
    • 개발자가 test fixture/CI를 만들 때, 실제 금융 원본이나 raw payload를 repo에 커밋하지 않는 기준을 따른다.

4. 이번에 정의할 변경

  • Import provenance 표준: source kind, parser name/version, source hash, masked filename, source row/page reference, import batch, dedupe key, validation summary 등 최소 audit metadata를 정의한다.
  • 민감자료 저장/노출 정책: raw payload, raw summary, source filename/path, account/card identifiers, passwords, tokens/secrets, PDF text/XLSX row 원문에 대한 DB/repo/log/MCP/Streamlit boundary를 정의한다.
  • 데이터 모델 및 runtime flow 반영 기준: docs/data-model.md, docs/project-structure.md, docs/runtime-flows.md에 import provenance와 sensitive-data policy가 traceable하게 반영되어야 한다.

영향 범위

  • 코드 영향:
    • jarca_ledger_mcp/application/imports_service.py
    • jarca_ledger_mcp/infrastructure/parsers/*
    • jarca_ledger_mcp/infrastructure/sqlite/schema.py, migrations.py
    • jarca_ledger_mcp/adapters/mcp/server.py, tool_contracts.py
    • Streamlit import/operations gateway가 provenance를 표시하는 경우 해당 gateway/page
  • 데이터 영향:
    • transactions.source, external_id, dedupe_key, raw_summary, raw_payload, import_batch_id
    • import_batches.filename, memo
    • 신규 또는 변경 가능성이 있는 provenance table/JSON schema
  • 문서 영향:
    • docs/data-model.md
    • docs/project-structure.md
    • docs/runtime-flows.md
    • import/backup/safety 관련 runbook 또는 StagePilot REQ/BAT 문서

5. 요구사항 목록

기능 요구사항

  • FR-1: 각 import source는 source kind, parser identity, source hash, import batch id, row/page reference, dedupe key, validation summary를 포함하는 표준 provenance envelope를 가져야 한다.
  • FR-2: DB에 저장되는 filename/path 정책은 원본 전체 경로 저장을 피하고, 필요 시 masked basename 또는 hash를 사용해야 한다.
  • FR-3: raw payload와 raw summary는 audit 필요성과 민감도에 따라 보존/축소/마스킹/미저장 중 하나로 분류되어야 하며, source별 기본값을 가져야 한다.
  • FR-4: MCP/Streamlit read surface는 agent/operator에게 필요한 provenance metadata를 제공하되 password, token/secret, 전체 파일 경로, 원본 PDF text, 불필요한 raw payload를 노출하지 않아야 한다.
  • FR-5: rollback/duplicate/reconciliation workflow는 새 provenance 정책으로도 기존 operational safety와 auditability를 잃지 않아야 한다.
  • FR-6: baseline docs는 import provenance와 sensitive-data policy를 데이터 모델, runtime flow, repository structure의 공통 기준으로 반영해야 한다.

비기능 요구사항

  • NFR-1 (privacy by minimization): 운영 DB·repo fixture·logs·MCP responses는 목적 달성에 필요한 최소 금융 증빙만 보존하거나 노출해야 한다.
  • NFR-2 (auditability): 민감자료를 줄이더라도 import batch, transaction, rollback, duplicate 판단의 재현 가능한 lineage는 유지되어야 한다.
  • NFR-3 (backward compatibility): 기존 운영 DB의 import rows는 additive migration 또는 compatibility adapter로 읽을 수 있어야 하며, destructive rewrite는 별도 승인 없이는 금지한다.
  • NFR-4 (test safety): CI/AppTest/HTTP smoke fixtures는 synthetic/temp DB만 사용하고 실제 원본 파일명·계좌 식별자·raw payload를 포함하지 않아야 한다.

정책 결정 결과

raw_payload minimize의 의미

minimize는 raw evidence를 전부 삭제한다는 뜻이 아니라, 원본 문서/row 덤프를 저장하지 않고 재현성에 필요한 정규화된 최소 provenance만 저장한다는 뜻이다.

  • 저장 허용:
    • source kind: kb_bank_pdf, toss_bank_pdf, toss_securities_pdf, seoulpay_xlsx, csv_generic
    • parser name/version 또는 parser identity
    • source_hash와 필요 시 짧은 prefix
    • import batch id
    • source row/page/sheet reference: page number, sheet name, row index, section/action code 등 원본 위치를 좁힐 수 있는 값
    • normalized transaction evidence: date/time, amount, direction/type, masked account hint, normalized merchant/counterparty, validation summary
    • duplicate/rollback에 필요한 external_id, dedupe_key, validation result, parsed row count
  • 저장 금지:
    • password, token, secret
    • 전체 파일 경로
    • 원본 PDF text 전체
    • XLSX/CSV row 전체 dump
    • 계좌번호/카드번호 원문
    • 불필요한 raw payload 전체 JSON
  • source별 예외:
    • source별 parser가 audit에 꼭 필요한 작은 필드를 갖는 경우 REQ-021에서 allowlist로 명시한다.
    • allowlist 밖 key는 기본 저장하지 않거나 masking한다.

filename/path 정책

  • import_batches.filename에는 전체 path를 저장하지 않는다.
  • 운영자 표시에는 masked-basename을 사용하고, 실제 동일성/추적성은 source_hash로 판정한다.
  • 예: /volume1/private/국민은행_고진환_2026년06월.pdf → 국민은행_***_2026년06월.pdf + source_hash.

MCP provenance 노출 정책

  • minimal: agent 기본값. source, import_batch_id, external_id, dedupe_key, source_hash_prefix 정도만 제공한다.
  • operator-summary: 운영자 화면/도구용. masked filename, parser identity, row/page/sheet reference, validation summary를 포함할 수 있다.
  • debug-gated: 명시 debug gate가 있을 때만 parser diagnostics를 제공한다. raw 원문·password·전체 path는 여전히 제외한다.

기존 운영 DB sanitization 분리

  • 기존 운영 DB의 raw payload/file path 정리는 REQ-021에 섞지 않는다.
  • 별도 GitHub Project Todo 기존 운영 DB import evidence sanitization preview 및 정리로 분리했다.
  • 해당 후속 작업은 scan → preview report → backup → explicit approval → narrow migration → verification 순서로만 진행한다.

finance agent privacy boundary 및 destructive migration 원칙

  • finance agent는 raw financial evidence를 소비하지 않고 normalized provenance metadata만 소비한다.
  • destructive migration은 preview/backup/명시 승인 없이는 금지한다.

코드 기준 import source matrix

Source 현재 코드 기준 저장/응답 항목 민감 위험 REQ-021 권고 저장/노출
KB Bank PDF source_hash, page_count, metadata, validation, parsed_row_count, parsed["file_path"], transactions.raw_payload, raw_summary, branch, balance_after, external_id, dedupe_key file path, holder/account metadata, PDF-derived raw payload, branch/balance detail masked filename + source_hash, page/row reference, parser identity, validation summary, minimized payload allowlist
Toss Bank PDF source_hash, page_count, metadata, validation, parsed_row_count, parsed["file_path"], action/counterparty/balance/raw_summary/raw_payload, external_id, dedupe_key file path, account masked metadata, counterparty/action raw text, balance detail masked filename + source_hash, action category, row/page reference, normalized counterparty, minimized payload allowlist
Toss Securities PDF source_hash, page_count, metadata, validation, parsed_row_count, parsed["file_path"], section/action/code/name/quantity/unit_price/fee/tax/balance/raw_payload securities detail and counterparty/security raw text, file path, account metadata masked filename + source_hash, section/action/code where needed, normalized security/counterparty summary, numeric details only when audit-required
SeoulPay XLSX source_hash, sheet_name, metadata, validation, parsed_row_count, parsed["file_path"], transaction kind/payment kind/no/merchant id/channel/raw_payload XLSX file path, merchant id, transaction no, raw row payload masked filename + source_hash, sheet name, row index/reference, payment kind/category summary, minimized merchant/transaction reference
CSV preview filename=str(path), raw preview rows from csv.DictReader arbitrary user columns may include sensitive data; preview currently can echo raw CSV rows preview output should mask/limit columns by allowlist; import policy should require source profile and sensitive-column filtering

범위 경계

  • In Scope
    • import provenance field policy와 민감자료 저장/노출 정책 정의
    • source별 provenance default와 raw evidence classification
    • additive schema 또는 JSON envelope 변경 필요성 판단
    • MCP/Streamlit response boundary 정의
    • baseline docs 갱신 요구 정의
  • Out of Scope
    • 외부 보안감사나 법무 검토 자체
    • 실운영 DB의 대량 destructive migration
    • 파일 암호화 vault 또는 장기 보존 시스템 구축
    • 외부 공개 API auth/TLS 설계 — dcy-013의 network MCP 내부망 전제와 별도

6. 리스크/가정 목록

리스크

  • R-1 (High): raw payload/file path를 계속 저장하면 운영 DB, backup, debug log, MCP response를 통해 실제 금융 원본자료가 과다 노출될 수 있다.
    • 완화 방안: source별 저장 허용 필드와 금지 필드를 명시하고, 민감 key filtering 및 fixture/log scan을 검증 기준에 포함한다.
  • R-2 (High): 민감자료를 과도하게 제거하면 duplicate 판단, rollback, reconciliation, audit 재현성이 약해질 수 있다.
    • 완화 방안: raw evidence 대신 source hash, row/page reference, parser version, normalized dedupe inputs를 provenance envelope에 남긴다.
  • R-3 (Medium): 기존 운영 DB에는 이미 raw_payload와 import_batches.filename/memo가 있어 새로운 정책과 충돌할 수 있다.
    • 완화 방안: backward-compatible read policy와 optional sanitization/migration plan을 REQ에서 분리해 정의한다.
  • R-4 (Medium): finance agent가 필요 이상 상세한 provenance를 MCP로 받으면 privacy boundary가 agent prompt/log로 확장된다.
    • 완화 방안: agent-facing default response와 operator/debug response를 분리한다.

가정

  • A-1: Jarca Ledger는 운영 DB를 source of truth로 유지하되, 원본 PDF/XLSX/CSV 파일 자체를 repo에 보관하지 않는다.
  • A-2: import source별 parser는 원본에서 normalized transaction rows와 validation summary를 만들 수 있다.
  • A-3: rollback과 duplicate check는 full raw document가 아니라 stable hash/dedupe/provenance metadata로 충분히 수행 가능하다.
  • A-4: 운영자가 정말 원본 증빙을 확인해야 할 때는 DB/MCP가 아니라 별도 로컬 파일 보관 위치에서 직접 확인한다.

오픈 질문

  • Q-1: transactions.raw_payload의 장기 정책은 source별 유지/축소/마스킹/미저장 중 무엇이어야 하는가?
    • 상태: Answered — 기본 정책은 minimize다. raw 원문 전체를 저장하지 않고, rollback/dedupe/audit에 필요한 normalized 최소 필드만 보존한다.
  • Q-2: import_batches.filename은 전체 경로, basename, masked basename, hash 중 무엇을 저장해야 하는가?
    • 상태: Answered — masked-basename + source_hash를 사용한다. 전체 경로는 저장하지 않는다.
  • Q-3: MCP default response에서 provenance detail을 어느 수준까지 노출할 것인가?
    • 상태: Answered — 기본은 minimal, 운영자용은 operator-summary, debug 상세는 별도 gate로 분리한다.
  • Q-4: 기존 운영 DB에 이미 저장된 raw payload/file path를 정리하는 migration을 이번 범위에 포함할 것인가, 별도 follow-up으로 둘 것인가?
    • 상태: Answered — 이번 REQ에서는 정책/신규 동작을 정의하고, 기존 운영 DB sanitization은 별도 GitHub Project Todo/후속 SDLC로 분리한다.

7. 초기 성공 기준

  • S-1: import provenance policy가 source별 최소 필드, 금지 필드, 저장 위치(DB/log/repo/MCP/Streamlit)를 표로 정의한다.
  • S-2: REQ-021은 기존 import 기능의 backward compatibility를 유지하면서 additive schema/API 변경 여부를 명확히 한다.
  • S-3: sensitive-data test 또는 static scan 기준이 정의되어 raw payload/password/token/secret/file path가 fixture/log/MCP response에 불필요하게 남지 않음을 검증할 수 있다.
  • S-4: rollback, duplicate check, audit investigation이 raw document 없이도 source hash/import batch/row reference/dedupe metadata로 설명 가능하다.
  • S-5: docs/data-model.md, docs/project-structure.md, docs/runtime-flows.md가 새로운 provenance/sensitive-data policy를 반영한다.

측정 방식 및 데이터 출처

  • S-1: Discovery/REQ policy table, source-by-source classification matrix
  • S-2: REQ acceptance criteria와 additive migration design
  • S-3: pytest/static scan/contract smoke evidence
  • S-4: synthetic import fixture를 사용한 duplicate/rollback/audit smoke
  • S-5: baseline docs diff와 StagePilot doctor traceability

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

  • source별 raw evidence 보존 정책 결정 — raw_payload=minimize
  • filename/path 저장 정책 결정 — masked-basename + source_hash
  • MCP default/debug/operator response boundary 결정 — minimal/operator-summary/debug-gated
  • 기존 운영 DB sanitization을 이번 delivery에 포함할지 결정 — 별도 GitHub Project Todo로 분리
  • 관련 현재 코드와 baseline 문서 확인
  • baseline 문서 갱신 필요성 식별

9. 파일 처리 결과

  • 처리 결과: 생성
  • 생성 경로: docs/discovery/dcy-014_20260708_import-provenance-sensitive-data-policy.md
  • 참조 문서:
    • docs/data-model.md
    • docs/project-structure.md
    • docs/runtime-flows.md
    • docs/discovery/dcy-002_20260627_operational-safety-backup-restore-validation-db.md
    • docs/discovery/dcy-006_20260630_pytest-apptest-smoke-ci-automation.md
    • docs/discovery/dcy-011_20260703_backend-refactor-phase4-write-import-workflow-adapter-narrowing.md
    • docs/discovery/dcy-012_20260703_review-queue-reconciliation-workbench-persistence.md
    • jarca_ledger_mcp/application/imports_service.py
    • jarca_ledger_mcp/infrastructure/sqlite/schema.py
    • stage-pilot/templates/project-structure.md
    • stage-pilot/templates/runtime-flows.md

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

DECIDE

  • 없음 — 사용자 결정 반영 완료.

CONFIRM

  • 없음 — finance agent privacy boundary 및 destructive migration 금지 원칙 확인 완료.

DATA

  • 없음 — import source matrix를 코드 기준으로 작성 완료.

11. Discovery Freeze

섹션 참조

Freeze 플래그

  • Handoff Decision: confirmed
  • Handoff Rationale: 사용자 결정으로 raw_payload minimize, masked-basename + source_hash, MCP minimal/operator-summary/debug-gated, 기존 DB sanitization 후속 분리, finance agent privacy boundary, destructive migration 금지 원칙이 확정되어 REQ-021 초안 작성으로 인계 가능하다.
  • Ready for REQ Drafting: true
  • Confirmed By: 고진환
  • Confirmed At (KST): 2026-07-08 10:58 KST
View Git Blame Copy Permalink