Refactor import and workflow services plus adapter seams

2026-07-03 08:25:01 +09:00
parent ac78e94571
commit f42bc4aa7d
53 changed files with 3420 additions and 2497 deletions
@@ -5,7 +5,7 @@
 - Status: draft
 - Owner: Jarca / project maintainer
 - Last Updated (KST): 2026-07-03
- Source Discovery / Batch: bootstrap-baseline, BAT-006, BAT-007, BAT-010
+- Source Discovery / Batch: bootstrap-baseline, BAT-006, BAT-007, BAT-010, BAT-012, BAT-013, BAT-014

 ## Project Summary
 - Jarca 가계부 전용 MCP 서버와 Streamlit 대시보드로 계좌/카드 거래, 예산, 분류 규칙, import, 자산/스냅샷, 현금흐름 분석을 SQLite에 저장하고 운영한다.
@@ -61,10 +61,21 @@ jarca-ledger-mcp/
 │   │   ├── shared.py
 │   │   ├── system_services.py
 │   │   ├── asset_account_services.py
+│   │   ├── assets_service.py
 │   │   ├── transaction_report_services.py
 │   │   ├── import_transfer_services.py
-│   │   └── categorization_services.py
+│   │   ├── imports_service.py
+│   │   ├── cross_transfer_service.py
+│   │   ├── reconciliation_service.py
+│   │   ├── categorization_services.py
+│   │   └── uncategorized_workbench_service.py
 │   ├── infrastructure/
+│   │   ├── parsers/
+│   │   │   ├── __init__.py
+│   │   │   ├── kb_bank_pdf.py
+│   │   │   ├── toss_bank_pdf.py
+│   │   │   ├── toss_securities_pdf.py
+│   │   │   └── seoulpay_xlsx.py
 │   │   └── sqlite/
 │   │       ├── __init__.py
 │   │       ├── connection.py
@@ -72,8 +83,18 @@ jarca-ledger-mcp/
 │   │       └── migrations.py
 │   ├── adapters/
 │   │   ├── mcp/
+│   │   │   ├── tool_contracts.py
 │   │   │   └── server.py
 │   │   └── streamlit/
+│   │       ├── __init__.py
+│   │       ├── overview_gateway.py
+│   │       ├── assets_gateway.py
+│   │       ├── transactions_gateway.py
+│   │       ├── categorization_gateway.py
+│   │       ├── transfers_gateway.py
+│   │       ├── imports_gateway.py
+│   │       ├── accounts_gateway.py
+│   │       ├── reconciliation_gateway.py
 │   │       └── service_gateway.py
 │   ├── kb_bank_pdf.py
 │   ├── toss_bank_pdf.py
@@ -121,31 +142,47 @@ jarca-ledger-mcp/
 - `jarca_ledger_mcp/server.py`
  - Legacy-compatible MCP entrypoint shim that delegates to `adapters.mcp.server`.
 - `jarca_ledger_mcp/application/shared.py`
-  - Shared helpers, validation, KST clock, dedupe policy, parser imports, and cross-domain constants.
+  - Shared helpers, validation, KST clock, dedupe policy, parser seam imports, and cross-domain constants.
 - `jarca_ledger_mcp/application/system_services.py`
  - Health/status/backup/account create-list/update and persistence-adjacent service behavior.
 - `jarca_ledger_mcp/application/asset_account_services.py`
-  - Account mutation, manual asset, asset snapshot, liquidity/net-worth logic.
+  - Legacy-compatible asset/account facade that preserves older import paths while delegating asset ownership to `assets_service.py` and account mutation to write services.
+- `jarca_ledger_mcp/application/assets_service.py`
+  - Manual asset CRUD, snapshot close/report, liquidity, and net-worth workflow ownership.
 - `jarca_ledger_mcp/application/transaction_report_services.py`
-  - Transaction CRUD, budgets, monthly/category/fixed-cost/investable cashflow reports.
+  - Transaction CRUD, budgets, monthly/category/fixed-cost/investable cashflow reports, with reconciliation delegated to `reconciliation_service.py`.
 - `jarca_ledger_mcp/application/import_transfer_services.py`
-  - Import preview/import, self-transfer/cancel matching, cross-account transfer workflow.
+  - Legacy-compatible import/transfer facade that preserves prior import paths while delegating to `imports_service.py` and `cross_transfer_service.py`.
+- `jarca_ledger_mcp/application/imports_service.py`
+  - Import preview/import/rollback orchestration and import batch workflow ownership.
+- `jarca_ledger_mcp/application/cross_transfer_service.py`
+  - Cross-account/self-transfer/cancel-original matching workflow ownership.
+- `jarca_ledger_mcp/application/reconciliation_service.py`
+  - Manual/partial-import balance reconciliation preview ownership.
 - `jarca_ledger_mcp/application/categorization_services.py`
-  - Category rules, categorization preview/apply, uncategorized workbench, ledger categories.
+  - Category rules, categorization preview/apply, ledger categories, and compatibility delegation to `uncategorized_workbench_service.py`.
+- `jarca_ledger_mcp/application/uncategorized_workbench_service.py`
+  - Uncategorized inbox/workbench queries and recommendation-apply workflow ownership.
+- `jarca_ledger_mcp/infrastructure/parsers/*`
+  - Import parser seam that keeps file-source parsing under infrastructure while preserving legacy top-level parser modules.
 - `jarca_ledger_mcp/infrastructure/sqlite/connection.py`
  - DB path resolution, sqlite connection setup, context manager semantics.
 - `jarca_ledger_mcp/infrastructure/sqlite/schema.py`
  - Schema version, DDL, additive column definitions.
 - `jarca_ledger_mcp/infrastructure/sqlite/migrations.py`
  - Additive/idempotent migration routines and DB initialization.
+- `jarca_ledger_mcp/adapters/mcp/tool_contracts.py`
+  - Narrow MCP adapter contract surface that re-exports only the public tool callables consumed by the FastMCP server.
 - `jarca_ledger_mcp/adapters/mcp/server.py`
-  - FastMCP tool registration layer that exposes service functions to Hermes/MCP clients.
+  - FastMCP tool registration layer that depends on `tool_contracts.py` instead of broad direct service imports.
 - `jarca_ledger_mcp/adapters/streamlit/service_gateway.py`
-  - Narrow dashboard-facing service surface used by `dashboard/app.py`.
+  - Compatibility aggregator over page/domain gateway modules.
+- `jarca_ledger_mcp/adapters/streamlit/*_gateway.py`
+  - Page/domain-sized dashboard service surfaces (`overview`, `assets`, `transactions`, `categorization`, `transfers`, `imports`, `accounts`, `reconciliation`).
 - Parser modules (`kb_bank_pdf.py`, `toss_bank_pdf.py`, `toss_securities_pdf.py`, `seoulpay_xlsx.py`)
  - Source-file parsing and preview conversion only.
 - `dashboard/app.py`
-  - Streamlit operator UI for the operations hub summary, 자산/마감, 거래내역, 확인필요 큐, 미분류, 분류 규칙, 카테고리, 계좌, Import pages.
+  - Streamlit operator UI for the operations hub summary, 자산/마감, 거래내역, 확인필요 큐, 미분류, 분류 규칙, 카테고리, 계좌, Import pages, wired through page/domain gateways instead of a flat broad service namespace.
 - `tests/`
  - Regression tests for facade compatibility, service behavior, parser behavior, categorization, transfer matching, MCP contract compatibility, and Streamlit AppTest smoke.
 - `.github/workflows/ci.yml`
@@ -178,7 +215,7 @@ jarca-ledger-mcp/

 ## Current Gaps / Planned Changes
 - Application modules are now separated by phase-0~3 domain seams, but deeper repository/use-case split remains future Phase 4+ work.
- Streamlit gateway is intentionally narrow for current pages; further page/domain-specific gateways may follow in later phases.
+- Streamlit now uses page/domain gateways; deeper presenter/view-model extraction remains future work.
 - HTTP adapter and remote ops re-architecture remain out of scope.

 ## Update Triggers
@@ -193,3 +230,4 @@ jarca-ledger-mcp/
 - 2026-06-30 KST: REQ-006/BAT-006 기준으로 GitHub Actions CI workflow, synthetic fixture DB builder, AppTest/HTTP/DB safety smoke wrappers 추가.
 - 2026-06-30 KST: REQ-007/REQ-008/BAT-007 기준으로 MCP response contract snapshot/test 위치와 required-check job 계약 추가.
 - 2026-07-03 KST: REQ-013/REQ-014/BAT-010 기준으로 application / infrastructure / adapter layering, compatibility facade/shim, Streamlit gateway 구조를 반영했다.
+- 2026-07-03 KST: REQ-016/REQ-017/REQ-018 및 BAT-012/BAT-013/BAT-014 기준으로 import/advanced owning services, parser seam, MCP contract helper, page/domain Streamlit gateways를 반영했다.