diff --git a/docs/discovery/dcy-014_20260708_import-provenance-sensitive-data-policy.md b/docs/discovery/dcy-014_20260708_import-provenance-sensitive-data-policy.md new file mode 100644 index 0000000..576db1f --- /dev/null +++ b/docs/discovery/dcy-014_20260708_import-provenance-sensitive-data-policy.md @@ -0,0 +1,206 @@ +# 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): 없음 diff --git a/docs/discovery/index.md b/docs/discovery/index.md index 29101bf..ccef415 100644 --- a/docs/discovery/index.md +++ b/docs/discovery/index.md @@ -19,3 +19,4 @@ | dcy-011_20260703_backend-refactor-phase4-write-import-workflow-adapter-narrowing | 20260703 | Jarca Ledger 백엔드 리팩터링 Phase 4+ 후속 주기 (write service 분리 → import pipeline 분리 → advanced finance workflow 분리 → MCP/Streamlit adapter 표면 축소) | [Discovery](./dcy-011_20260703_backend-refactor-phase4-write-import-workflow-adapter-narrowing.md) | confirmed | | dcy-012_20260703_review-queue-reconciliation-workbench-persistence | 20260703 | 확인필요 큐 / 잔액대조 워크벤치 영속화 및 운영 모델 정립 | [Discovery](./dcy-012_20260703_review-queue-reconciliation-workbench-persistence.md) | confirmed | | dcy-013_20260707_docker-network-mcp-deployment | 20260707 | Jarca Ledger 독립 Docker 배포 및 network MCP endpoint 제공 | [Discovery](./dcy-013_20260707_docker-network-mcp-deployment.md) | confirmed | +| dcy-014_20260708_import-provenance-sensitive-data-policy | 20260708 | Import provenance 및 민감자료 저장 정책 정리 | [Discovery](./dcy-014_20260708_import-provenance-sensitive-data-policy.md) | draft |