REQ-015 Transactional write service split and compatibility-preserving domain extraction

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-011
Created At (KST): 2026-07-03 07:29 KST
Approved At (KST): 2026-07-03 07:30 KST
Implemented At (KST): 2026-07-03 07:39 KST

1. 배경

dcy-011 confirmed Discovery는 BAT-010 이후 top-level facade/shim과 read-only seam은 이미 도입됐지만, transaction/account/budget mutation과 일부 write-oriented orchestration이 여전히 broad application module에 섞여 있다고 판단했다. 특히 transaction_report_services.py, system_services.py, asset_account_services.py, categorization_services.py에 흩어진 write 경로는 이후 import/advanced workflow 분리의 선행 기반이므로, contract를 유지한 채 domain-oriented write service로 먼저 좁혀야 한다.

2. Intent

이 REQ의 목적은 기능 계약을 바꾸지 않고 transactional write 경로를 accounts, transactions, budgets, category rules/categories 성격의 전용 application service로 분리해 write 책임을 더 국소화하는 것이다. 결과적으로 기존 MCP/Streamlit/service facade 호출은 그대로 유지하면서도 이후 import/advanced workflow 분리가 더 좁은 변경 단위로 이어질 수 있어야 한다.

3. 범위

In Scope

account write 경로(create_ledger_account, update_ledger_account)를 전용 write service/module로 정리한다.
transaction write 경로(create_ledger_transaction, update_ledger_transaction, delete_ledger_transaction)를 전용 write service/module로 정리한다.
budget write 경로(create_ledger_budget)를 전용 write service/module로 정리한다.
category rule/category mutation 경로(create/update/delete_category_rule, create/delete_ledger_category)를 전용 write service/module로 정리한다.
기존 service.py, MCP adapter, Streamlit gateway, dashboard call sites는 기존 함수명과 envelope contract를 유지한 채 새 write service를 재노출한다.
관련 테스트와 batch evidence를 통해 contract preservation과 regression safety를 검증한다.

Out of Scope

import preview/import/rollback parser/application split.
cross-transfer, reconciliation, asset/net worth, uncategorized workbench의 전용 service 분리.
HTTP adapter 추가.
response schema, tool names, dashboard IA 변경.
destructive migration.

4. Requirement

FR-1. Domain-oriented transactional write service extraction

account, transaction, budget, category rule/category mutation 구현은 기존 broad application module에서 더 좁은 write-oriented application module로 이동해야 한다.
분리 후에도 top-level service.py public API와 adapter 호출 signature는 유지돼야 한다.
새 module 경계는 최소한 accounts / transactions / budgets / category-rules 성격을 드러내야 한다.

FR-2. Compatibility-preserving delegation

기존 jarca_ledger_mcp/application/* 모듈이 직접 구현을 계속 품지 않더라도, 기존 import surface와 테스트/monkeypatch 관성은 유지돼야 한다.
jarca_ledger_mcp/service.py, jarca_ledger_mcp/adapters/mcp/server.py, jarca_ledger_mcp/adapters/streamlit/service_gateway.py, dashboard/app.py는 호출부 변경 없이 동작해야 한다.
성공/실패 envelope(success, error_code, transaction, account, budget, rule, category, deleted 등)는 의도적으로 변경되지 않아야 한다.

FR-3. Regression-safe write boundary proof

기존 pytest 회귀와 contract regression은 write service 이동 후에도 PASS 해야 한다.
write path가 분리된 뒤에도 ledger category/category rule/account/transaction 관련 mutation smoke가 유지돼야 한다.
batch implementation/verification 문서는 변경 파일, 검증 명령, 잔여 리스크를 실제 실행 결과로 남겨야 한다.

5. Acceptance Criteria

AC-1: jarca_ledger_mcp/application/ 아래에 transactional write 경로를 담당하는 신규 module이 생성되고, account/transaction/budget/category rule/category mutation 구현이 그쪽으로 이동한다.
AC-2: 기존 service.py public API, MCP tools, Streamlit gateway, dashboard 호출부는 signature와 envelope contract를 유지한다.
AC-3: full pytest 또는 해당 회귀 subset, contract-sensitive tests가 PASS 한다.
AC-4: batch implementation/verification 문서가 실제 변경 파일과 검증 결과를 반영한다.

6. Impacted Area

jarca_ledger_mcp/application/__init__.py
jarca_ledger_mcp/application/system_services.py
jarca_ledger_mcp/application/asset_account_services.py
jarca_ledger_mcp/application/transaction_report_services.py
jarca_ledger_mcp/application/categorization_services.py
jarca_ledger_mcp/service.py
jarca_ledger_mcp/adapters/mcp/server.py
jarca_ledger_mcp/adapters/streamlit/service_gateway.py
tests/test_service.py
tests/test_category_rule_filters.py
tests/test_contract_regression.py

7. Notes

이 REQ는 behavior change보다 package boundary와 maintainability 향상을 다루므로 Non-Functional로 관리한다.
dcy-011 전체는 multi-batch 후속 주기이므로, 이번 REQ는 Phase 4 첫 구현 슬라이스로 다룬다.
import/advanced workflow 분리는 후속 REQ/BAT에서 계속 진행한다.

8. Change Log

2026-07-03 07:29 KST: dcy-011 confirmed 범위를 바탕으로 Phase 4 첫 구현 슬라이스용 Proposed 초안을 생성.
2026-07-03 07:30 KST: 사용자 요청에 따라 dcy-011의 첫 delivery 입력으로 승인하고 BAT-011 구현 대상으로 확정.
2026-07-03 07:39 KST: write-oriented application modules 분리, full pytest PASS, MCP tool discovery 56, service export provenance 검증을 근거로 Implemented로 전환.

5.9 KiB Raw Blame History