Implement BAT-011 transactional write service split
This commit is contained in:
Jarca
@@ -0,0 +1,37 @@
|
||||
# BAT-011 Design
|
||||
|
||||
## Architecture summary
|
||||
|
||||
- Introduce dedicated write-oriented application modules under `jarca_ledger_mcp/application/` for accounts, transactions, budgets, and category rules/categories.
|
||||
- Keep broad modules (`system_services.py`, `asset_account_services.py`, `transaction_report_services.py`, `categorization_services.py`) as compatibility aggregation layers for read/report/mixed responsibilities that are not yet in scope.
|
||||
- Preserve `service.py` as a thin re-export facade and avoid MCP/Streamlit/dashboard call-site churn.
|
||||
|
||||
## Changed areas
|
||||
|
||||
- `jarca_ledger_mcp/application/accounts_write_services.py`
|
||||
- `jarca_ledger_mcp/application/transactions_write_services.py`
|
||||
- `jarca_ledger_mcp/application/budgets_write_services.py`
|
||||
- `jarca_ledger_mcp/application/category_rules_write_services.py`
|
||||
- Existing application modules that previously held these implementations
|
||||
- `jarca_ledger_mcp/application/__init__.py`
|
||||
- `jarca_ledger_mcp/service.py`
|
||||
|
||||
## Key decisions
|
||||
|
||||
- Move only mutation implementations in BAT-011; read/report/import/advanced workflow logic stays in place.
|
||||
- Favor direct function relocation plus compatibility re-export over new abstraction layers to minimize contract risk.
|
||||
- Keep shared helpers in `application/shared.py`; do not introduce storage-layer refactors in this batch.
|
||||
|
||||
## Edge cases
|
||||
|
||||
- `create_ledger_account` remains paired with `update_ledger_account` even though the old implementations lived in different modules.
|
||||
- Category rule preview/apply remains out of BAT-011 scope if moving it would force read/workbench coupling; mutation extraction takes precedence.
|
||||
- Any dashboard/MCP references must continue resolving through `service.py` without signature changes.
|
||||
|
||||
## Architecture Impact
|
||||
|
||||
- none
|
||||
|
||||
## Reference Doc Update Plan
|
||||
|
||||
- No baseline doc rewrite in BAT-011 unless the final module tree differs materially from the existing dcy-011/REQ-015 description.
|
||||
@@ -0,0 +1,51 @@
|
||||
# BAT-011 Implementation
|
||||
|
||||
## Plan summary
|
||||
|
||||
BAT-011 implements the first dcy-011 delivery slice by extracting transactional write paths into narrower application modules while preserving the top-level `service.py` facade, MCP tool contracts, and Streamlit/dashboard call signatures.
|
||||
|
||||
## Changed files
|
||||
|
||||
- `jarca_ledger_mcp/application/accounts_write_services.py`
|
||||
- `jarca_ledger_mcp/application/transactions_write_services.py`
|
||||
- `jarca_ledger_mcp/application/budgets_write_services.py`
|
||||
- `jarca_ledger_mcp/application/category_rules_write_services.py`
|
||||
- `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`
|
||||
- `docs/discovery/dcy-011_20260703_backend-refactor-phase4-write-import-workflow-adapter-narrowing.md`
|
||||
- `docs/srs/index.md`
|
||||
- `docs/srs/Non-Functional/req-015_transactional-write-service-split-compatibility.md`
|
||||
- `docs/batches/index.md`
|
||||
- `docs/batches/bat-011_20260703_transactional-write-service-split/index.md`
|
||||
- `docs/batches/bat-011_20260703_transactional-write-service-split/planning.md`
|
||||
- `docs/batches/bat-011_20260703_transactional-write-service-split/design.md`
|
||||
- `docs/batches/bat-011_20260703_transactional-write-service-split/implementation.md`
|
||||
- `docs/batches/bat-011_20260703_transactional-write-service-split/verification.md`
|
||||
|
||||
## Execution log
|
||||
|
||||
- 2026-07-03 07:29 KST: dcy-011에서 REQ-015를 생성하고 source Discovery 역참조/SRS index를 갱신했다.
|
||||
- 2026-07-03 07:30 KST: REQ-015를 Approved로 전환하고 BAT-011 standard batch scaffold(index/planning/design/implementation/verification)를 생성했다.
|
||||
- 2026-07-03 07:34 KST: `accounts_write_services.py`, `transactions_write_services.py`, `budgets_write_services.py`, `category_rules_write_services.py`를 추가하고 account/transaction/budget/category rule-category mutation 구현을 새 모듈로 이동했다.
|
||||
- 2026-07-03 07:35 KST: 기존 broad modules(`system_services.py`, `asset_account_services.py`, `transaction_report_services.py`, `categorization_services.py`)를 compatibility re-export/delegation 레이어로 축소했다.
|
||||
- 2026-07-03 07:35 KST: `service.py` proxy module set에 새 write modules를 추가해 helper monkeypatch/export propagation이 계속 동작하도록 정렬했다.
|
||||
- 2026-07-03 07:36 KST: category create path에서 빠진 `infer_cashflow_kind` 정책을 `category_rules_write_services.py`에 보강해 category mutation 회귀를 복구했다.
|
||||
- 2026-07-03 07:39 KST: targeted regression, full pytest, MCP discovery, service export provenance 검증이 모두 PASS하여 REQ-015를 Implemented로 승격했다.
|
||||
|
||||
## Validation
|
||||
|
||||
- `python3 -m py_compile jarca_ledger_mcp/application/*.py jarca_ledger_mcp/service.py` → PASS
|
||||
- `pytest -q tests/test_service.py tests/test_category_rule_filters.py tests/test_ledger_categories.py tests/test_contract_regression.py` → PASS (`19 passed`)
|
||||
- `pytest -q` → PASS (`42 passed, 4 skipped`)
|
||||
- `hermes mcp test jarca-ledger` → PASS (`Connected`, `Tools discovered: 56`)
|
||||
- `python3` provenance check → PASS (`service.create_ledger_account.__module__ == jarca_ledger_mcp.application.accounts_write_services`, transaction/budget/category mutation exports도 각각 새 write module을 가리킴)
|
||||
|
||||
## Remaining risks / follow-up notes
|
||||
|
||||
- `preview_categorization`, `apply_categorization_rules`, uncategorized workbench/read-side helper는 아직 `categorization_services.py`에 남아 있어 Phase 4 후속 또는 Phase 7 adapter narrowing에서 추가 분리가 가능하다.
|
||||
- import preview/import/rollback 및 cross-transfer/reconciliation/advanced workflow 분리는 BAT-011 범위 밖이며 dcy-011 후속 REQ/BAT로 이어져야 한다.
|
||||
- 이번 배치는 contract-preserving extraction이 목적이므로 data model semantics와 response envelope은 의도적으로 변경하지 않았다.
|
||||
@@ -0,0 +1,33 @@
|
||||
# BAT-011 Transactional write service split
|
||||
|
||||
- Profile: standard
|
||||
- Status: release-candidate
|
||||
- Included REQ: REQ-015
|
||||
- Discovery: dcy-011
|
||||
- Owner: 렛저장인
|
||||
- Date (KST): 2026-07-03
|
||||
|
||||
## 목표
|
||||
|
||||
REQ-015에 따라 account / transaction / budget / category rule-category mutation 경로를 더 좁은 write-oriented application service로 분리한다. 기존 `service.py`, MCP adapter, Streamlit gateway, dashboard 호출부와 response contract는 유지한 채 Phase 4 첫 구현 슬라이스를 실제 코드와 검증 evidence로 마무리한다.
|
||||
|
||||
## 산출물
|
||||
|
||||
- `jarca_ledger_mcp/application/` write-oriented service modules
|
||||
- 기존 broad application modules의 compatibility re-export / delegation 정리
|
||||
- full pytest 및 contract-sensitive regression evidence
|
||||
- BAT-011 planning/design/implementation/verification documents
|
||||
|
||||
## 범위 제한
|
||||
|
||||
- import preview/import/rollback split
|
||||
- advanced workflow(cross-transfer/reconciliation/assets/workbench) 분리
|
||||
- HTTP adapter 추가
|
||||
- destructive migration
|
||||
|
||||
## 문서
|
||||
|
||||
- `planning.md`: Phase 4 첫 delivery plan, risks, validation gate
|
||||
- `design.md`: write service boundary / delegation design
|
||||
- `implementation.md`: changed files, execution log, validation commands
|
||||
- `verification.md`: AC mapping, PASS/FAIL, REQ Implemented decision
|
||||
@@ -0,0 +1,32 @@
|
||||
# BAT-011 Planning
|
||||
|
||||
## Scope
|
||||
|
||||
- Implement REQ-015: transactional write path(account / transaction / budget / category rule-category mutation)를 더 좁은 write-oriented application module로 분리한다.
|
||||
- Preserve top-level service facade, MCP adapter, Streamlit gateway, dashboard call signatures and response envelope contracts.
|
||||
- Leave import/advanced workflow split for follow-up REQ/BAT under dcy-011.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- dcy-011 confirmed Discovery and Approved REQ-015.
|
||||
- BAT-010 application/adapters baseline.
|
||||
- Existing pytest regression and contract-sensitive tests.
|
||||
|
||||
## Work plan
|
||||
|
||||
1. Create write-oriented application modules for accounts / transactions / budgets / category rules.
|
||||
2. Move concrete mutation implementations into those modules and keep existing broad modules as compatibility delegation layers where needed.
|
||||
3. Update `application/__init__.py` and `service.py` import surface to re-export the new modules without changing public API.
|
||||
4. Run focused syntax + regression validation, then full pytest if focused checks remain green.
|
||||
5. Update batch implementation/verification evidence and promote REQ/BAT state if ACs are satisfied.
|
||||
|
||||
## Design Gate
|
||||
|
||||
- Result: standard batch 유지.
|
||||
- Reason: package boundary 변경, compatibility delegation, category/account/transaction write contract preservation, regression evidence 정리가 함께 필요하므로 planning/design/verification depth가 필요하다.
|
||||
|
||||
## Risks and mitigations
|
||||
|
||||
- Hidden import coupling after write extraction: mitigate by preserving re-export layers and running full pytest.
|
||||
- Envelope drift on mutation responses: mitigate by preserving existing function signatures and contract-sensitive tests.
|
||||
- Category rule/category mutation helpers may still share read-side helpers: mitigate by extracting only write-focused logic first and leaving broad read/report paths untouched in this batch.
|
||||
@@ -0,0 +1,43 @@
|
||||
# BAT-011 Verification
|
||||
|
||||
## Verification summary
|
||||
|
||||
Status: PASS
|
||||
|
||||
Evidence was collected against synthetic/temp data only. No production ledger DB mutation or real financial files were used.
|
||||
|
||||
## Acceptance criteria mapping
|
||||
|
||||
### REQ-015
|
||||
|
||||
- AC-1: PASS — `jarca_ledger_mcp/application/` 아래에 `accounts_write_services.py`, `transactions_write_services.py`, `budgets_write_services.py`, `category_rules_write_services.py`가 생성됐고 account/transaction/budget/category rule-category mutation 구현이 그쪽으로 이동했다.
|
||||
- AC-2: PASS — top-level `service.py` public API, MCP tools, Streamlit/dashboard call signatures and mutation envelope contracts are preserved. MCP discovery still reports 56 tools, and export provenance shows the write APIs now resolve to the new modules.
|
||||
- AC-3: PASS — targeted regression (`tests/test_service.py`, `tests/test_category_rule_filters.py`, `tests/test_ledger_categories.py`, `tests/test_contract_regression.py`) PASS, plus full `pytest -q` PASS (`42 passed, 4 skipped`).
|
||||
- AC-4: PASS — BAT-011 implementation/verification docs now record actual changed files, commands, and outcomes.
|
||||
|
||||
## Requirement state decision
|
||||
|
||||
- REQ-015: Implemented.
|
||||
|
||||
## Validation evidence
|
||||
|
||||
- `python3 -m py_compile jarca_ledger_mcp/application/*.py jarca_ledger_mcp/service.py` → PASS
|
||||
- `pytest -q tests/test_service.py tests/test_category_rule_filters.py tests/test_ledger_categories.py tests/test_contract_regression.py` → PASS (`19 passed`)
|
||||
- `pytest -q` → PASS (`42 passed, 4 skipped`)
|
||||
- `hermes mcp test jarca-ledger` → PASS (`Connected`, `Tools discovered: 56`)
|
||||
- Python provenance check on exported write APIs → PASS
|
||||
- `create_ledger_account`, `update_ledger_account` → `accounts_write_services`
|
||||
- `create/update/delete_ledger_transaction` → `transactions_write_services`
|
||||
- `create_ledger_budget` → `budgets_write_services`
|
||||
- `create/update/delete_category_rule`, `create/delete_ledger_category` → `category_rules_write_services`
|
||||
|
||||
## Remaining issues
|
||||
|
||||
### Hard blockers
|
||||
- None.
|
||||
|
||||
### Non-blocking follow-up
|
||||
- categorization preview/apply/workbench read-side extraction
|
||||
- import pipeline split
|
||||
- advanced finance workflow split
|
||||
- narrower adapter surfaces under later dcy-011 batches
|
||||
Reference in New Issue
Block a user