Refactor import and workflow services plus adapter seams

This commit is contained in:
Jarca
2026-07-03 08:25:01 +09:00
parent ac78e94571
commit f42bc4aa7d
53 changed files with 3420 additions and 2497 deletions
@@ -0,0 +1,13 @@
# BAT-013 Design
## Architecture summary
- `cross_transfer_service.py` owns matching helpers and review queue APIs.
- `reconciliation_service.py` owns manual/partial-import balance reconciliation preview.
- `assets_service.py` owns manual asset CRUD, snapshot close/read, liquidity/net-worth reporting, and valuation helpers.
- `uncategorized_workbench_service.py` owns uncategorized list/summary/workbench/recommendation apply flows.
- Existing broad modules become thin compatibility layers or keep only their non-moved responsibilities.
## Verification focus
- workflow-specific regression for cross-transfer/assets/reconciliation/workbench
- full pytest and MCP discovery
- provenance checks that public exports resolve to the new owning modules
@@ -0,0 +1,48 @@
# BAT-013 Implementation
## Plan summary
BAT-013 implements dcy-011 Phase 6 by extracting advanced finance workflows into dedicated owning application services: `cross_transfer_service.py`, `reconciliation_service.py`, `assets_service.py`, and `uncategorized_workbench_service.py`. Existing broad modules remain as compatibility layers so MCP/service/dashboard callers keep their contracts.
## Changed files
- `jarca_ledger_mcp/application/assets_service.py`
- `jarca_ledger_mcp/application/asset_account_services.py`
- `jarca_ledger_mcp/application/cross_transfer_service.py`
- `jarca_ledger_mcp/application/import_transfer_services.py`
- `jarca_ledger_mcp/application/reconciliation_service.py`
- `jarca_ledger_mcp/application/transaction_report_services.py`
- `jarca_ledger_mcp/application/uncategorized_workbench_service.py`
- `jarca_ledger_mcp/application/categorization_services.py`
- `jarca_ledger_mcp/application/__init__.py`
- `jarca_ledger_mcp/service.py`
- `docs/srs/index.md`
- `docs/srs/Non-Functional/req-017_advanced-finance-workflow-service-split.md`
- `docs/batches/index.md`
- `docs/batches/bat-013_20260703_advanced-workflow-service-split/*`
- `docs/discovery/dcy-011_20260703_backend-refactor-phase4-write-import-workflow-adapter-narrowing.md`
## Execution log
- 2026-07-03 07:55 KST: dcy-011 Phase 6 범위로 `REQ-017`/`BAT-013`를 생성하고 Approved 상태를 확정했다.
- 2026-07-03 07:57~07:59 KST: AST-extracted function ranges를 기준으로 assets / cross-transfer / reconciliation / uncategorized workbench 흐름을 새 owning services로 이동했다.
- 2026-07-03 07:59 KST: `asset_account_services.py`, `import_transfer_services.py`, `transaction_report_services.py`, `categorization_services.py`를 compatibility delegation 레이어로 축소했다.
- 2026-07-03 08:00 KST: `application/__init__.py`와 `service.py` export/proxy surface를 새 owning modules까지 확장했다.
- 2026-07-03 08:00~08:01 KST: targeted workflow regression, full pytest, MCP discovery, provenance checks를 실행했고 모두 PASS했다.
## Validation
- `python3 -m py_compile jarca_ledger_mcp/application/*.py jarca_ledger_mcp/service.py` → PASS
- `pytest -q tests/test_cross_account_transfer_matching.py tests/test_asset_snapshots.py tests/test_categorization.py tests/test_contract_regression.py tests/test_service.py` → PASS (`24 passed`)
- `pytest -q` → PASS (`42 passed, 4 skipped`)
- `hermes mcp test jarca-ledger` → PASS (`Connected`, `Tools discovered: 56`)
- `python3` provenance check → PASS
- cross-transfer APIs → `jarca_ledger_mcp.application.cross_transfer_service`
- reconciliation API → `jarca_ledger_mcp.application.reconciliation_service`
- asset workflows → `jarca_ledger_mcp.application.assets_service`
- uncategorized workbench APIs → `jarca_ledger_mcp.application.uncategorized_workbench_service`
## Remaining risks / follow-up notes
- broad compatibility layers still exist by design; final dcy-011 batch should narrow MCP/Streamlit adapter imports and refresh baseline docs.
- top-level module names remain public to avoid breaking monkeypatch/tests; final cleanup should preserve this constraint.
@@ -0,0 +1,21 @@
# BAT-013 Advanced workflow service split
- Profile: standard
- Status: release-candidate
- Included REQ: REQ-017
- Discovery: dcy-011
- Owner: 렛저장인
- Date (KST): 2026-07-03
## 목표
REQ-017에 따라 cross-transfer, reconciliation, assets, uncategorized workbench를 owning application services로 분리하고 broad modules는 compatibility delegation으로 축소한다.
## Delivery checklist
- [ ] planning complete
- [ ] design complete
- [ ] implementation complete
- [ ] verification complete
- [ ] release-candidate promoted
- [ ] REQ sync complete
@@ -0,0 +1,28 @@
# BAT-013 Planning
## Scope
- Implement REQ-017 advanced workflow service split.
- Preserve public API and workflow response contracts while relocating owning helpers with their workflows.
- Leave adapter narrowing/baseline docs for the final dcy-011 batch.
## Dependencies
- dcy-011 confirmed Discovery.
- REQ-017 Approved.
- BAT-011/BAT-012 compatibility seams.
- Existing workflow regression tests.
## Work plan
1. Extract cross-transfer workflow from `import_transfer_services.py` into `cross_transfer_service.py`.
2. Extract reconciliation preview from `transaction_report_services.py` into `reconciliation_service.py`.
3. Extract manual asset/snapshot/liquidity workflows from `asset_account_services.py` into `assets_service.py`.
4. Extract uncategorized list/summary/workbench/recommendation flows from `categorization_services.py` into `uncategorized_workbench_service.py`.
5. Update application/service export surfaces, run focused workflow regression + full pytest, then record evidence.
## Design Gate
- Result: standard batch 유지.
- Reason: multiple domain modules and compatibility layers change together; broad-module decomposition needs explicit verification.
## Risks and mitigations
- Shared helper drift across moved workflows: move helper with first owner and verify with focused tests.
- Contract regressions in dashboard/MCP callers: preserve public names and run full pytest + MCP discovery.
- Partial extraction leaving dead imports: run py_compile and provenance check after relocation.
@@ -0,0 +1,36 @@
# BAT-013 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-017
- AC-1: PASS — `cross_transfer_service.py`, `reconciliation_service.py`, `assets_service.py`, `uncategorized_workbench_service.py` were created and now own their workflows.
- AC-2: PASS — service/MCP/dashboard contract remained stable; MCP discovery still reports 56 tools.
- AC-3: PASS — workflow-focused regression and full pytest both passed.
- AC-4: PASS — BAT-013 implementation/verification docs record the actual changed files, commands, and outcomes.
## Requirement state decision
- REQ-017: Implemented.
## Validation evidence
- `python3 -m py_compile jarca_ledger_mcp/application/*.py jarca_ledger_mcp/service.py` → PASS
- `pytest -q tests/test_cross_account_transfer_matching.py tests/test_asset_snapshots.py tests/test_categorization.py tests/test_contract_regression.py tests/test_service.py` → PASS (`24 passed`)
- `pytest -q` → PASS (`42 passed, 4 skipped`)
- `hermes mcp test jarca-ledger` → PASS (`Connected`, `Tools discovered: 56`)
- Python provenance check on advanced workflow exports → PASS
## Remaining issues
### Hard blockers
- None.
### Non-blocking follow-up
- MCP/Streamlit adapter surface narrowing
- dcy-011 baseline/final status refresh and QC evidence sync