87 lines
5.9 KiB
Markdown
87 lines
5.9 KiB
Markdown
# 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로 전환.
|