REQ-016 Import pipeline application/infrastructure split and evidence-preserving parser relocation

Status: Implemented
Type: Non-Functional
Priority: High
Owner: 렛저장인
Source Discovery: docs/discovery/dcy-011_20260703_backend-refactor-phase4-write-import-workflow-adapter-narrowing.md
Batch: BAT-012
Created At (KST): 2026-07-03 07:49 KST
Approved At (KST): 2026-07-03 07:49 KST
Implemented At (KST): 2026-07-03 07:53 KST

1. 배경

REQ-015/BAT-011로 transactional write path는 좁은 write-oriented application module로 분리됐지만, import preview/import/rollback과 account auto-linking/classification/orchestration은 여전히 application/import_transfer_services.py에 크게 남아 있다. 또한 parser entrypoint는 top-level kb_bank_pdf.py, toss_bank_pdf.py, toss_securities_pdf.py, seoulpay_xlsx.py에 흩어져 있어 application layer가 parser 구현 위치를 직접 아는 구조다.

2. Intent

이 REQ의 목적은 import preview/import/rollback을 전용 imports_service로 분리하고, parser access path를 infrastructure/parsers/*로 정리해 parser(파싱/정규화)와 application import orchestration(dedupe/account auto-link/import_batch persistence/classification/post-import bookkeeping)을 구분하는 것이다. 기존 MCP tool 이름, response envelope, import evidence fields는 유지해야 한다.

3. 범위

In Scope

preview_ledger_csv_import
preview/import_kb_bank_pdf
preview/import_seoulpay_xlsx
preview/import_toss_bank_pdf
preview/import_toss_securities_pdf
list_ledger_import_batches
rollback_ledger_import_batch
import용 account auto-linking/classification/helper를 imports_service 경계로 이동
parser import 경로를 jarca_ledger_mcp/infrastructure/parsers/*로 정리
기존 application/import_transfer_services.py는 advanced workflow 중심으로 남기고 import-facing 함수는 compatibility delegation으로 유지

Out of Scope

cross-transfer/reconciliation split
asset/net worth/workbench split
MCP/Streamlit adapter surface narrowing
parser 알고리즘/분류 semantics 변경
destructive migration

4. Requirement

FR-1. Import orchestration service extraction

import preview/import/rollback과 account auto-linking/classification helper는 application/imports_service.py로 이동해야 한다.
service.py, MCP adapter, 기존 호출 surface는 함수명/인자/응답 envelope을 유지해야 한다.

FR-2. Parser relocation by infrastructure seam

application layer는 parser 구현을 top-level 모듈에서 직접 끌어오지 않고 infrastructure/parsers/* 경로를 통해 접근해야 한다.
parser는 parsing/normalization/preview helper를 제공하고, persistence/import_batch 생성/transaction insert는 application service에 남아야 한다.

FR-3. Evidence-preserving contract safety

raw_summary, counterparty, raw_payload, external_id, import_batch_id, duplicate counting, validation payload 등 import evidence 필드는 의도적으로 변경되지 않아야 한다.
import regression tests, rollback behavior, MCP discovery가 PASS 해야 한다.

5. Acceptance Criteria

AC-1: application/imports_service.py와 infrastructure/parsers/*가 생성되고 import preview/import/rollback 구현이 그쪽으로 이동한다.
AC-2: 기존 public API/MCP tools/import response envelope과 evidence fields가 유지된다.
AC-3: import-related regression과 full pytest가 PASS 한다.
AC-4: BAT-012 implementation/verification 문서가 실제 changed files, commands, outcomes를 기록한다.

6. Impacted Area

jarca_ledger_mcp/application/import_transfer_services.py
jarca_ledger_mcp/application/imports_service.py
jarca_ledger_mcp/application/shared.py
jarca_ledger_mcp/infrastructure/parsers/*
jarca_ledger_mcp/service.py
jarca_ledger_mcp/adapters/mcp/server.py
tests/test_kb_bank_pdf.py
tests/test_seoulpay_xlsx.py
tests/test_toss_securities_pdf.py
tests/test_service.py

7. Notes

이 REQ는 package boundary와 maintainability 중심의 refactor이므로 Non-Functional로 관리한다.
advanced workflow split은 후속 REQ/BAT로 이어진다.

8. Change Log

2026-07-03 07:49 KST: dcy-011 Phase 5 import pipeline split 범위를 바탕으로 REQ-016을 생성하고 BAT-012 입력으로 즉시 승인했다.
2026-07-03 07:53 KST: imports_service/parsers seam 분리, import-focused regression, full pytest, MCP discovery evidence를 근거로 Implemented로 전환했다.

4.5 KiB Raw Blame History