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
@@ -0,0 +1,7 @@
+# BAT-014 Design
+
+## Architecture summary
+- `adapters/mcp/tool_contracts.py` becomes the MCP adapter’s narrow contract dependency surface.
+- `adapters/streamlit/{overview,assets,transactions,categorization,imports,accounts,transfers,reconciliation}_gateway.py` expose page/domain-sized call sets.
+- `adapters/streamlit/service_gateway.py` remains a compatibility aggregator while `dashboard/app.py` shifts to page/domain gateway aliases.
+- Baseline docs record the post-Phase-7 structure and runtime flow.
@@ -0,0 +1,43 @@
+# BAT-014 Implementation
+
+## Plan summary
+
+BAT-014 implements dcy-011 Phase 7 by narrowing the remaining adapter surfaces without changing public MCP tool names or dashboard behavior. The MCP server now depends on `adapters/mcp/tool_contracts.py` instead of a broad direct `service` import, and the Streamlit dashboard now calls page/domain gateways under `adapters/streamlit/*_gateway.py` rather than a flat broad `service_gateway` namespace. `service_gateway.py` remains as a compatibility aggregator.
+
+## Delivered changes
+
+1. Added `jarca_ledger_mcp/adapters/mcp/tool_contracts.py` as the MCP adapter contract surface and repointed `adapters/mcp/server.py` wrappers to `contracts.*` callables.
+2. Added page/domain Streamlit gateways:
+   - `overview_gateway.py`
+   - `assets_gateway.py`
+   - `transactions_gateway.py`
+   - `categorization_gateway.py`
+   - `transfers_gateway.py`
+   - `imports_gateway.py`
+   - `accounts_gateway.py`
+   - `reconciliation_gateway.py`
+3. Reworked `adapters/streamlit/service_gateway.py` into a compatibility aggregator over the new gateway modules.
+4. Repointed `dashboard/app.py` static call sites away from `service.*` to the owning page/domain gateway modules.
+5. Preserved hot-reload fallback by changing `get_service_callable()` to reload the passed gateway module rather than a broad flat service namespace.
+6. Refreshed `docs/project-structure.md` and `docs/runtime-flows.md` so the baseline reflects post-Phase-7 ownership and adapter seams.
+
+## Compatibility notes
+
+- MCP tool names, argument shapes, and response contracts were intentionally preserved.
+- `adapters/streamlit/service_gateway.py` still exists as a compatibility surface for any legacy dashboard-side imports.
+- No SQL/UI business-rule ownership was moved into the dashboard; the app still goes through adapter gateways.
+
+## Files changed
+
+- `jarca_ledger_mcp/adapters/mcp/tool_contracts.py`
+- `jarca_ledger_mcp/adapters/mcp/server.py`
+- `jarca_ledger_mcp/adapters/streamlit/__init__.py`
+- `jarca_ledger_mcp/adapters/streamlit/service_gateway.py`
+- `jarca_ledger_mcp/adapters/streamlit/*_gateway.py`
+- `dashboard/app.py`
+- `docs/project-structure.md`
+- `docs/runtime-flows.md`
+
+## Outcome
+
+The repository now has explicit MCP contract and Streamlit page/domain gateway seams, satisfying the final dcy-011 narrowing target while preserving all public compatibility surfaces.
@@ -0,0 +1,12 @@
+# BAT-014 Adapter narrowing and baseline refresh
+
+- Profile: standard
+- Status: release-candidate
+- Included REQ: REQ-018
+- Discovery: dcy-011
+- Owner: 렛저장인
+- Date (KST): 2026-07-03
+
+## 목표
+
+REQ-018에 따라 MCP/Streamlit adapter surfaces를 더 좁히고 baseline 문서를 갱신해 dcy-011을 완료한다.
@@ -0,0 +1,12 @@
+# BAT-014 Planning
+
+## Scope
+- Implement REQ-018 adapter narrowing.
+- Preserve MCP/tool/dashboard contracts while shifting adapter imports to helper/page gateways.
+- Refresh structure/runtime baselines and finalize dcy-011 metadata.
+
+## Work plan
+1. Add MCP contract helper module and repoint `adapters/mcp/server.py` to it.
+2. Add Streamlit page/domain gateway modules and repoint `dashboard/app.py` away from a flat broad gateway dependency.
+3. Run AppTest/UI-adjacent regression, full pytest, MCP discovery, and one browser/HTTP smoke if needed.
+4. Refresh `docs/project-structure.md`, `docs/runtime-flows.md`, and dcy-011 status.
@@ -0,0 +1,43 @@
+# BAT-014 Verification
+
+## Verification summary
+
+Status: PASS
+
+All required code-path checks for BAT-014 passed. A manual local browser-evidence launch was attempted but blocked by the runtime’s consent guard for long-running local server startup, so the close-out evidence uses AppTest + full pytest + MCP discovery + structural call-site verification. No production ledger DB or real financial files were used.
+
+## Acceptance criteria evidence
+
+### AC-1. MCP contract/helper seam and Streamlit page/domain gateways exist
+- Evidence:
+  - `jarca_ledger_mcp/adapters/mcp/tool_contracts.py` added and `adapters/mcp/server.py` now calls `contracts.*`.
+  - `search_files('*_gateway.py')` under `adapters/streamlit` returned 9 gateway/aggregator files.
+
+### AC-2. `dashboard/app.py` no longer uses a flat broad gateway surface
+- Evidence:
+  - `search_files(pattern='service\\.', path='dashboard', file_glob='app.py')` returned 0 matches after rewiring.
+  - Dynamic hot-reload lookup now targets passed gateway modules (`categorization_gateway`, `transfers_gateway`) instead of a flat `service` binding.
+
+### AC-3. Regression and adapter verification pass
+- `python3 -m py_compile jarca_ledger_mcp/adapters/mcp/*.py jarca_ledger_mcp/adapters/streamlit/*.py dashboard/app.py` → PASS
+- `pytest -q tests/test_dashboard_app.py` → PASS (`....`)
+- `pytest -q` → PASS (`........................ss...............ss...`)
+- `hermes mcp test jarca-ledger` → PASS, 56 tools discovered
+
+### AC-4. Baseline docs and discovery metadata reflect completion
+- Evidence:
+  - `docs/project-structure.md` updated with new owning services, parser seam, MCP contract helper, and Streamlit page/domain gateways.
+  - `docs/runtime-flows.md` updated with import/parser seam, MCP contract routing, and dashboard gateway flow.
+  - dcy-011 metadata and close-out notes updated to reference `REQ-015`~`REQ-018` / `BAT-011`~`BAT-014` completion.
+
+## Browser evidence note
+
+- Attempted: synthetic local dashboard browser/HTTP smoke.
+- Result: blocked by terminal consent guard for long-running local server startup in this session.
+- Impact: none on code correctness regression; AppTest remained green and no UI functional regression was detected in test coverage.
+
+## Safety boundary
+
+- Synthetic/temp DBs only.
+- No destructive migration.
+- No production ledger DB mutation.