Implement BAT-011 transactional write service split

2026-07-03 07:42:16 +09:00
parent 7ac25a6cf7
commit ac78e94571
21 changed files with 844 additions and 228 deletions
@@ -0,0 +1,86 @@
+# 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로 전환.