81 lines
4.5 KiB
Markdown
81 lines
4.5 KiB
Markdown
# 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로 전환했다.
|