Refactor import and workflow services plus adapter seams

docs/srs/Interface/req-018_adapter-surface-narrowing-baseline-refresh.md

@@ -0,0 +1,63 @@
+# REQ-018 MCP/Streamlit adapter surface narrowing and baseline refresh for dcy-011 completion
+
+- Status: Implemented
+- Type: Interface
+- Priority: High
+- Owner: 렛저장인
+- Source Discovery: `docs/discovery/dcy-011_20260703_backend-refactor-phase4-write-import-workflow-adapter-narrowing.md`
+- Batch: BAT-014
+- Created At (KST): 2026-07-03 08:03 KST
+- Approved At (KST): 2026-07-03 08:03 KST
+- Implemented At (KST): 2026-07-03 08:23 KST
+
+## 1. 배경
+
+`REQ-015`~`REQ-017`으로 write/import/advanced workflow owning services는 분리되었지만, adapter 계층은 아직 broad surfaces를 유지한다. `adapters/mcp/server.py`는 모든 tool wrapper가 직접 `service.py`에 의존하고, `dashboard/app.py`는 flat `service_gateway` namespace에 넓게 결합되어 있다. dcy-011의 마지막 단계는 이 adapter surfaces를 더 좁히고 baseline 문서를 실제 구조에 맞춰 갱신하는 것이다.
+
+## 2. Intent
+
+MCP adapter는 contract/registration helper를 통해 service facade 의존을 더 국소화하고, Streamlit dashboard는 page/domain gateway를 명시적으로 사용하도록 재구성한다. 동시에 `docs/project-structure.md`와 `docs/runtime-flows.md`를 Phase 4~7 완료 상태에 맞게 refresh 해 dcy-011을 완결한다.
+
+## 3. 범위
+
+### In Scope
+- `adapters/mcp/tool_contracts.py` 또는 동등 helper를 도입해 MCP tool wrappers의 broad service dependency를 줄임
+- `adapters/streamlit/*_gateway.py` page/domain gateways를 도입/확장해 `dashboard/app.py`의 flat gateway 결합을 줄임
+- `adapters/streamlit/service_gateway.py`는 compatibility aggregator로 유지 가능
+- `docs/project-structure.md`, `docs/runtime-flows.md`, dcy-011 metadata/status 갱신
+
+### Out of Scope
+- MCP tool 이름/응답 shape 변경
+- Streamlit UX redesign
+- HTTP adapter 구현
+
+## 4. Requirement
+
+### FR-1. MCP contract helper narrowing
+- `adapters/mcp/server.py`는 직접 `service`에 광범위하게 결합하지 않고 helper/contract layer를 통해 tool contract를 호출해야 한다.
+
+### FR-2. Streamlit page/domain gateways
+- `dashboard/app.py`는 flat broad gateway 대신 overview/assets/transfers/categories/import/accounts 등 page/domain gateway를 사용해야 한다.
+- hot-reload fallback은 유지하되, broad implementation module 직접 import로 되돌아가면 안 된다.
+
+### FR-3. Baseline refresh
+- `docs/project-structure.md`와 `docs/runtime-flows.md`는 Phase 4~7 완료 후 구조/흐름을 반영해야 한다.
+
+## 5. Acceptance Criteria
+- AC-1: MCP adapter helper/contract seam과 Streamlit page/domain gateway modules가 존재한다.
+- AC-2: `dashboard/app.py`가 flat broad gateway 의존을 줄이고 page/domain gateway 호출로 동작한다.
+- AC-3: `pytest tests/test_dashboard_app.py`, full pytest, MCP discovery, 필요 시 browser/HTTP smoke가 PASS 한다.
+- AC-4: baseline docs와 dcy-011 status/links가 완료 상태를 반영한다.
+
+## 6. Impacted Area
+- `jarca_ledger_mcp/adapters/mcp/server.py`
+- `jarca_ledger_mcp/adapters/mcp/tool_contracts.py`
+- `jarca_ledger_mcp/adapters/streamlit/*.py`
+- `dashboard/app.py`
+- `docs/project-structure.md`
+- `docs/runtime-flows.md`
+- `docs/discovery/dcy-011_20260703_backend-refactor-phase4-write-import-workflow-adapter-narrowing.md`
+
+## 7. Change Log
+- 2026-07-03 08:03 KST: dcy-011 Phase 7 adapter narrowing + baseline refresh 범위를 바탕으로 REQ-018을 생성하고 BAT-014 입력으로 즉시 승인했다.
+- 2026-07-03 08:23 KST: MCP tool_contracts, Streamlit page/domain gateways, baseline 문서 refresh, AppTest/full pytest/MCP discovery evidence를 근거로 REQ-018을 Implemented로 전환했다.

docs/srs/Non-Functional/req-016_import-pipeline-application-infrastructure-split.md

@@ -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로 전환했다.

docs/srs/Non-Functional/req-017_advanced-finance-workflow-service-split.md

@@ -0,0 +1,70 @@
+# REQ-017 Advanced finance workflow service split and compatibility-preserving domain isolation
+
+- 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-013
+- Created At (KST): 2026-07-03 07:55 KST
+- Approved At (KST): 2026-07-03 07:55 KST
+- Implemented At (KST): 2026-07-03 08:01 KST
+
+## 1. 배경
+
+`REQ-015`와 `REQ-016`으로 transactional write path와 import pipeline seam은 좁아졌지만, cross-transfer matching/review, balance reconciliation, manual asset/snapshot/net-worth workflows, uncategorized workbench는 여전히 broad application modules(`import_transfer_services.py`, `transaction_report_services.py`, `asset_account_services.py`, `categorization_services.py`)에 흩어져 있다.
+
+## 2. Intent
+
+이 REQ의 목적은 advanced finance workflows를 domain-oriented application modules로 추가 분리해 import/write/read service와 책임이 겹치지 않게 하는 것이다. public API, MCP contracts, dashboard behavior는 유지해야 하며, domain-heavy helpers는 owning workflow service로 이동해야 한다.
+
+## 3. 범위
+
+### In Scope
+- cross-transfer matching/review queue를 `application/cross_transfer_service.py`로 이동
+- balance reconciliation을 `application/reconciliation_service.py`로 이동
+- manual asset CRUD / snapshot / liquidity / net-worth workflows를 `application/assets_service.py`로 이동
+- uncategorized list/summary/workbench/recommendation apply 흐름을 `application/uncategorized_workbench_service.py`로 이동
+- 기존 broad modules는 compatibility delegation을 유지
+
+### Out of Scope
+- MCP/Streamlit adapter surface narrowing
+- baseline docs final update
+- tool contract rename or semantic changes
+- destructive migration
+
+## 4. Requirement
+
+### FR-1. Advanced workflow ownership split
+- cross-transfer, reconciliation, assets, uncategorized workbench는 각각 owning application module로 이동해야 한다.
+- helper 함수도 첫 소비자와 함께 이동해 broad module 내부 숨은 결합을 줄여야 한다.
+
+### FR-2. Compatibility-preserving delegation
+- `service.py`, MCP tool names, dashboard call signatures, response envelope은 유지해야 한다.
+- 기존 broad modules는 필요 시 thin delegation/re-export layer로 남을 수 있다.
+
+### FR-3. Regression-safe domain isolation
+- cross-transfer tests, asset snapshot/manual asset tests, reconciliation tests, uncategorized workflow tests, full pytest가 PASS 해야 한다.
+
+## 5. Acceptance Criteria
+- AC-1: `cross_transfer_service.py`, `reconciliation_service.py`, `assets_service.py`, `uncategorized_workbench_service.py`가 생성되고 owning workflow 구현이 이동한다.
+- AC-2: public API/MCP/dashboard contract가 유지된다.
+- AC-3: workflow-focused regression과 full pytest가 PASS 한다.
+- AC-4: BAT-013 implementation/verification 문서가 실제 변경 파일과 검증 결과를 반영한다.
+
+## 6. Impacted Area
+- `jarca_ledger_mcp/application/import_transfer_services.py`
+- `jarca_ledger_mcp/application/transaction_report_services.py`
+- `jarca_ledger_mcp/application/asset_account_services.py`
+- `jarca_ledger_mcp/application/categorization_services.py`
+- `jarca_ledger_mcp/application/{cross_transfer,reconciliation,assets,uncategorized_workbench}_service.py`
+- `jarca_ledger_mcp/service.py`
+- `tests/test_cross_account_transfer_matching.py`
+- `tests/test_asset_snapshots.py`
+- `tests/test_contract_regression.py`
+- `tests/test_categorization.py`
+- `tests/test_service.py`
+
+## 7. Change Log
+- 2026-07-03 07:55 KST: dcy-011 Phase 6 advanced workflow split 범위를 바탕으로 REQ-017을 생성하고 BAT-013 입력으로 즉시 승인했다.
+- 2026-07-03 08:01 KST: advanced workflow service extraction, full pytest, MCP discovery evidence를 근거로 Implemented로 전환했다.

docs/srs/index.md

@@ -33,7 +33,7 @@
 
 ## Next Requirement ID
 
-- Current: `REQ-016`
+- Current: `REQ-019`
 - Rule: `Requirement Register`에 있는 가장 큰 REQ 번호보다 정확히 1 커야 한다.
 
 ## Requirement Register
@@ -55,6 +55,9 @@
 | REQ-013 | Backend core layering / SQLite infrastructure split and service facade compatibility | Non-Functional | Implemented | High | 렛저장인 | [req-013_backend-core-layering-sqlite-infrastructure-service-facade-compatibility.md](Non-Functional/req-013_backend-core-layering-sqlite-infrastructure-service-facade-compatibility.md) |
 | REQ-014 | MCP/Streamlit adapter seam realignment and contract-preserving gateway | Interface | Implemented | High | 렛저장인 | [req-014_mcp-streamlit-adapter-seam-realignment-contract-preserving-gateway.md](Interface/req-014_mcp-streamlit-adapter-seam-realignment-contract-preserving-gateway.md) |
 | REQ-015 | Transactional write service split and compatibility-preserving domain extraction | Non-Functional | Implemented | High | 렛저장인 | [req-015_transactional-write-service-split-compatibility.md](Non-Functional/req-015_transactional-write-service-split-compatibility.md) |
+| REQ-016 | Import pipeline application/infrastructure split and evidence-preserving parser relocation | Non-Functional | Implemented | High | 렛저장인 | [req-016_import-pipeline-application-infrastructure-split.md](Non-Functional/req-016_import-pipeline-application-infrastructure-split.md) |
+| REQ-017 | Advanced finance workflow service split and compatibility-preserving domain isolation | Non-Functional | Implemented | High | 렛저장인 | [req-017_advanced-finance-workflow-service-split.md](Non-Functional/req-017_advanced-finance-workflow-service-split.md) |
+| REQ-018 | MCP/Streamlit adapter surface narrowing and baseline refresh for dcy-011 completion | Interface | Implemented | High | 렛저장인 | [req-018_adapter-surface-narrowing-baseline-refresh.md](Interface/req-018_adapter-surface-narrowing-baseline-refresh.md) |
 
 ## Recent Change Log Summary
 
@@ -83,3 +86,9 @@
 - 2026-07-03 00:18 KST: BAT-010 구현·검증 evidence, full pytest PASS, MCP tool discovery, browser smoke를 근거로 `REQ-013`, `REQ-014`를 Implemented로 전환했다.
 - 2026-07-03 07:30 KST: dcy-011 confirmed 범위를 `REQ-015` Proposed로 생성하고 첫 delivery 입력으로 Approved 상태로 전환했다.
 - 2026-07-03 07:39 KST: BAT-011 write-service split 구현과 full pytest/MCP discovery evidence를 근거로 `REQ-015`를 Implemented로 전환했다.
+- 2026-07-03 07:49 KST: dcy-011 Phase 5 import pipeline split 범위를 `REQ-016`으로 생성하고 BAT-012 입력으로 Approved 상태를 확정했다.
+- 2026-07-03 07:53 KST: BAT-012 import pipeline split 구현과 full pytest/MCP discovery evidence를 근거로 `REQ-016`을 Implemented로 전환했다.
+- 2026-07-03 07:55 KST: dcy-011 Phase 6 advanced workflow split 범위를 `REQ-017`로 생성하고 BAT-013 입력으로 Approved 상태를 확정했다.
+- 2026-07-03 08:01 KST: BAT-013 advanced workflow split 구현과 full pytest/MCP discovery evidence를 근거로 `REQ-017`을 Implemented로 전환했다.
+- 2026-07-03 08:03 KST: dcy-011 Phase 7 adapter narrowing + baseline refresh 범위를 `REQ-018`로 생성하고 BAT-014 입력으로 Approved 상태를 확정했다.
+- 2026-07-03 08:23 KST: BAT-014 adapter narrowing + baseline refresh 구현과 AppTest/full pytest/MCP discovery evidence를 근거로 `REQ-018`을 Implemented로 전환했다.