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
@@ -0,0 +1,49 @@
+# BAT-017 Design: Import provenance and sensitive-data policy
+
+- Status: draft
+- Created At (KST): 2026-07-08 11:33 KST
+- Included REQ: REQ-021
+
+## Design Direction
+
+Introduce a narrow provenance/sanitization layer used by import services and response adapters rather than scattering per-source masking rules across UI/MCP code.
+
+## Proposed Components
+
+- `provenance` helper functions under application/import boundary or a small shared module:
+  - `mask_source_filename(path_or_name)`
+  - `build_source_identity(source, file_path, source_hash, parser_name, parser_version)`
+  - `minimize_raw_payload(source, payload)`
+  - `sanitize_provenance_for_exposure(payload, level)`
+- Source-specific allowlists:
+  - KB Bank PDF: date/time, amount, direction, masked account hint, page/row reference, validation keys.
+  - Toss Bank PDF: action category, normalized counterparty, masked account hint, page/row reference, validation keys.
+  - Toss Securities PDF: section/action/code, normalized security/counterparty summary, numeric audit fields when required.
+  - SeoulPay XLSX: sheet name, row reference, payment kind/category summary, minimized merchant/transaction reference.
+  - CSV: explicit preview/import allowlist and sensitive-column suppression.
+
+## Storage Policy
+
+- Do not persist full local source paths.
+- Store masked basename and source hash for operator correlation.
+- Keep `source_hash` stable for dedupe/audit.
+- `raw_payload` stores only minimized allowlisted fields; forbidden fields are removed/masked.
+- Existing rows are not destructively rewritten by this batch.
+
+## Interface Policy
+
+- Default MCP responses use `minimal` exposure.
+- Operator summary may include masked filename, parser identity, row/page/sheet reference, validation summary.
+- Debug diagnostics require explicit gate and still exclude passwords/tokens/secrets/full path/raw document dump.
+
+## Test Strategy
+
+- Use synthetic fixtures only.
+- Include negative assertions for forbidden keys and full path patterns.
+- Verify duplicate/rollback metadata remains usable after minimization.
+
+## Open Design Checks Before Implementation
+
+- Decide whether provenance helpers live in `application/imports_service.py` initially or a new module.
+- Confirm whether schema version bump is required or policy can be implemented through current columns plus memo JSON shape.
+- Confirm MCP contract change is additive and does not break existing consumers.