# 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에 포함할지 결정
- [x] 관련 현재 코드와 baseline 문서 확인
- [x] 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

## 섹션 참조
- 범위: [# 5. 요구사항 목록 > 범위 경계](#5-요구사항-목록)
- 리스크/오픈 질문: [# 6. 리스크/가정 목록](#6-리스크가정-목록)
- 성공 기준: [# 7. 초기 성공 기준](#7-초기-성공-기준)

## 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): 없음