Refactor import and workflow services plus adapter seams

2026-07-03 08:25:01 +09:00
parent ac78e94571
commit f42bc4aa7d
53 changed files with 3420 additions and 2497 deletions
@@ -0,0 +1,80 @@
+# 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로 전환했다.