gitea-impl-agent/jarca-ledger-mcp
1
0
Fork 0
forked from jsfamily/jarca-ledger-mcp
Code Pull Requests Activity
Files
7c50298c4e4a8167a18e7e07465a8ed109c8e5c1
jarca-ledger-mcp/docs/discovery/dcy-014_20260708_import-provenance-sensitive-data-policy.md
T

15 KiB
Raw Blame History

0. 문서 상태

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

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

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를 포함하지 않아야 한다.

범위 경계

  • 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별 유지/축소/마스킹/미저장 중 무엇이어야 하는가?
    • 상태: Open
  • Q-2: import_batches.filename은 전체 경로, basename, masked basename, hash 중 무엇을 저장해야 하는가?
    • 상태: Open
  • Q-3: MCP default response에서 provenance detail을 어느 수준까지 노출할 것인가?
    • 상태: Open
  • Q-4: 기존 운영 DB에 이미 저장된 raw payload/file path를 정리하는 migration을 이번 범위에 포함할 것인가, 별도 follow-up으로 둘 것인가?
    • 상태: Open

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 보존 정책 결정
  • filename/path 저장 정책 결정
  • MCP default/debug/operator response boundary 결정
  • 기존 운영 DB sanitization을 이번 delivery에 포함할지 결정
  • 관련 현재 코드와 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

  • {{DECIDE_RAW_PAYLOAD_POLICY}}: source별 transactions.raw_payload 보존 정책을 retain|minimize|mask|do-not-store 중 선택한다.
  • {{DECIDE_FILENAME_PATH_POLICY}}: import_batches.filename 저장 정책을 full-path|basename|masked-basename|hash-only 중 선택한다.
  • {{DECIDE_MCP_PROVENANCE_EXPOSURE}}: MCP default response의 provenance 노출 수준을 minimal|operator-summary|debug-gated 중 선택한다.
  • {{DECIDE_EXISTING_DB_SANITIZATION_SCOPE}}: 기존 운영 DB에 저장된 raw payload/file path 정리를 이번 REQ에 포함할지, 별도 후속 Discovery/REQ로 분리할지 선택한다.

CONFIRM

  • {{CONFIRM_AGENT_PRIVACY_BOUNDARY}}: finance agent가 raw financial evidence 없이 normalized provenance metadata만 소비한다는 원칙을 확인한다.
  • {{CONFIRM_NO_DESTRUCTIVE_MIGRATION_WITHOUT_APPROVAL}}: 기존 import evidence 정리는 additive/preview-first로 설계하고 destructive rewrite는 별도 사용자 승인 없이는 금지한다.

DATA

  • {{DATA_IMPORT_SOURCE_MATRIX}}: 현재 지원 source별로 저장 중인 raw evidence, metadata, parser output 목록을 REQ 작성 시 코드 기준으로 확정한다.

11. Discovery Freeze

섹션 참조

Freeze 플래그

  • Handoff Decision: 보류
  • Handoff Rationale: 초기 Discovery 초안 생성 완료. REQ-021 초안 작성 전 raw payload, filename/path, MCP exposure, 기존 DB sanitization 범위에 대한 사용자 결정이 필요하다.
  • Ready for REQ Drafting: false
  • Confirmed By: 없음
  • Confirmed At (KST): 없음
View Git Blame Copy Permalink