docs: confirm import provenance req and batch

2026-07-08 11:34:37 +09:00
parent 7c50298c4e
commit c9231c2685
10 changed files with 421 additions and 25 deletions
@@ -1,14 +1,14 @@
 # 0. 문서 상태
 이 문서의 현재 상태와 식별 정보를 기록한다. 문서 추적과 승인 흐름에 필요한 최소 메타데이터를 적는다.

- 상태: draft
+- 상태: confirmed
 - 문서 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
+- 마지막 갱신 시각(KST): 2026-07-08 11:26 KST
 - 대체됨: 없음
 - 후속 Discovery 참조: 없음
- 생성된 REQ 참조: 없음
+- 생성된 REQ 참조: `REQ-021`

 # 1. 계획 상태 요약

@@ -92,6 +92,64 @@
 - 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
@@ -126,13 +184,13 @@

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

 # 7. 초기 성공 기준

@@ -152,10 +210,10 @@

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

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

@@ -179,17 +237,13 @@
 # 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는 별도 사용자 승인 없이는 금지한다.
+- 없음 — finance agent privacy boundary 및 destructive migration 금지 원칙 확인 완료.

 ## DATA
- `{{DATA_IMPORT_SOURCE_MATRIX}}`: 현재 지원 source별로 저장 중인 raw evidence, metadata, parser output 목록을 REQ 작성 시 코드 기준으로 확정한다.
+- 없음 — import source matrix를 코드 기준으로 작성 완료.

 # 11. Discovery Freeze

@@ -199,8 +253,8 @@
 - 성공 기준: [# 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): 없음
+- 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
@@ -19,4 +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 |
+| dcy-014_20260708_import-provenance-sensitive-data-policy | 20260708 | Import provenance 및 민감자료 저장 정책 정리 | [Discovery](./dcy-014_20260708_import-provenance-sensitive-data-policy.md) | confirmed |