140 lines
11 KiB
Markdown
140 lines
11 KiB
Markdown
# Jarca Ledger MCP Runtime Flows
|
|
|
|
- Baseline Mode: observed
|
|
- Baseline Seed: `.stage-pilot/bootstrap/baseline.yaml`
|
|
- Status: draft
|
|
- Owner: Jarca / project maintainer
|
|
- Last Updated (KST): 2026-07-03
|
|
- Source Discovery / Batch: bootstrap-baseline, BAT-006, BAT-007, BAT-008, BAT-010
|
|
- Primary Runtime: mixed
|
|
|
|
## Project Summary
|
|
- Jarca 가계부 전용 MCP 서버와 Streamlit 대시보드로 계좌/카드 거래, 예산, 분류 규칙, import, 현금흐름 분석, 자산/스냅샷 운영을 SQLite에 저장하고 제공한다.
|
|
|
|
## Purpose
|
|
- This document is the current execution-flow baseline for the project.
|
|
- It is a cross-cutting reference document for Discovery, REQ, Batch Design, Batch Verification, and implementation updates.
|
|
|
|
## Scope
|
|
- Covers representative command, MCP, dashboard, import, reconciliation, snapshot, and verification flows.
|
|
- Does not duplicate full acceptance criteria or low-level implementation details.
|
|
|
|
## Covered Entry Points
|
|
- `jarca-ledger-mcp` :: MCP stdio server for Hermes tool calls.
|
|
- `dashboard/app.py` :: Streamlit local dashboard.
|
|
- `pytest` :: regression test runner.
|
|
- `.github/workflows/ci.yml` :: GitHub Actions CI gate runner for PR/push/manual checks.
|
|
|
|
## Shared Components
|
|
- SQLite database at `~/.local/share/jarca/ledger.sqlite3` by default.
|
|
- `jarca_ledger_mcp/service.py` compatibility facade over application modules.
|
|
- `jarca_ledger_mcp/infrastructure/sqlite/*` for DB path resolution, schema, migration, and connection lifecycle.
|
|
- `jarca_ledger_mcp/adapters/mcp/server.py` for MCP registration.
|
|
- `jarca_ledger_mcp/adapters/streamlit/service_gateway.py` for dashboard-facing service calls.
|
|
- Parser modules for KB/Toss/SeoulPay sources.
|
|
|
|
## Flow: `MCP server tool call`
|
|
1. Hermes MCP client invokes a tool exposed by `jarca_ledger_mcp.server` / `jarca_ledger_mcp.adapters.mcp.server`.
|
|
2. MCP adapter forwards arguments to the matching `jarca_ledger_mcp.service` facade function.
|
|
3. Service facade routes into the relevant application module.
|
|
4. Application code opens SQLite through `infrastructure/sqlite` helpers, validates inputs, and performs the operation.
|
|
5. Application returns a dictionary payload with success data or error information.
|
|
6. Hermes surfaces the tool result to the user or uses it in a follow-up workflow.
|
|
|
|
## Flow: `Streamlit dashboard operation`
|
|
1. Operator starts `streamlit run dashboard/app.py --server.address 0.0.0.0 --server.port 8501`.
|
|
2. Dashboard reads the configured/default SQLite database.
|
|
3. User navigates to 요약, 자산/마감, 거래내역, 확인필요 큐, 미분류, 분류 규칙, 카테고리, 계좌, or Import pages.
|
|
4. UI calls `jarca_ledger_mcp.adapters.streamlit.service_gateway` rather than giant implementation modules directly.
|
|
5. Gateway delegates to the service facade/application modules and returns data to the page.
|
|
6. UI displays success/error status and refreshes visible tables.
|
|
|
|
## Flow: `Dashboard operations hub overview`
|
|
1. Operator opens the `요약` page.
|
|
2. Dashboard calls `get_monthly_cashflow_report(month)` using `transactions.transaction_date` and `ledger_categories.cashflow_kind` semantics.
|
|
3. Dashboard calls `get_asset_liquidity_report`, which uses the shared valuation helper: account-backed assets from `accounts.last_balance` plus active `manual_assets` rows when present.
|
|
4. If `manual_assets` and `asset_snapshots` are empty, the report keeps the REQ-005 account-only fallback and preserves existing totals/keys.
|
|
5. Dashboard renders sections in REQ-005 priority order: this-month actual income/expense/net/savings rate, asset liquidity, asset composition, budget/spend, operational warnings.
|
|
6. Missing `last_balance` or `manual_assets.valuation_amount` values are excluded from asset totals and surfaced as warnings.
|
|
|
|
## Flow: `Asset snapshot and net-worth workflow`
|
|
1. Operator can open `자산/마감` in Streamlit or call snapshot tools through MCP.
|
|
2. `preview_asset_snapshot_close(basis_date)` computes authority-source items from `accounts.last_balance` + active `manual_assets` without DB side effects.
|
|
3. `close_asset_snapshot(basis_date, source_note, memo, correction_reason)` writes append-only snapshot rows with correction metadata when re-closing the same basis date.
|
|
4. `get_asset_snapshot_report(basis_date)` first checks stored snapshot rows; if none exist, it falls back to live authority sources and marks `source='live_authority'`.
|
|
5. `get_net_worth_timeseries(start_date, end_date, months)` reads stored snapshot basis dates and applies the same asset-buckets-minus-loan formula to every point.
|
|
|
|
## Flow: `Import preview and import`
|
|
1. Operator chooses a supported source file: KB Bank PDF, Toss Bank PDF, Toss Securities PDF, SeoulPay XLSX, or CSV.
|
|
2. Preview function parses the file and reports counts, sample rows, duplicate status, and classification preview.
|
|
3. On explicit import, application code creates/fetches the target account, inserts non-duplicate transactions, writes provenance, and records an import batch.
|
|
4. Reports and dashboard views read the inserted rows using shared category/cashflow semantics.
|
|
5. If an import is wrong, rollback uses import batch data and soft-deletes by default.
|
|
|
|
## Flow: `Categorization rule lifecycle`
|
|
1. Operator creates or edits a category rule with match field, pattern, target category/subcategory, priority, and optional amount/day constraints.
|
|
2. Preview categorization shows candidate matches without mutating rows.
|
|
3. Apply categorization updates matching transactions and preserves audit information.
|
|
4. Category `cashflow_kind` controls actual cashflow/report inclusion.
|
|
|
|
## Flow: `Cross-account and cancel/original reconciliation`
|
|
1. Preview helpers search candidate pairs by amount, date, direction, account/source compatibility, and text similarity.
|
|
2. Operator reviews candidates in the dashboard or runs the automatic matcher where confidence rules are satisfied.
|
|
3. Matched self-transfers become `이체 / 본인계좌이동`; investment movements become `이체 / 투자이동`; ambiguous rows remain `확인필요`.
|
|
4. Cancel/refund rows can be linked to original expense rows; memo tags preserve manual link evidence.
|
|
|
|
## Flow: `Operational backup, validation DB, and restore smoke`
|
|
1. Operator captures non-sensitive DB status evidence with `get_ledger_db_status`: path, size, mtime, sha256, integrity check, major table row counts, and aggregate totals.
|
|
2. Operator creates a timestamped backup in `/root/.local/share/jarca/backups/ledger/` with `create_ledger_backup`; retention keeps the most recent 30 days or newest 20 files.
|
|
3. Risky import, rollback, categorization apply, reconciliation, or migration work is tested first against a synthetic fixture DB or repo-external validation DB copy selected through `JARCA_LEDGER_DB_PATH`.
|
|
4. Backup list/status/hash checks use `list_ledger_backups` and `get_ledger_backup_status`.
|
|
5. Restore execution is not an MCP flow. Restore smoke uses `scripts/ledger_restore_smoke.py` or the runbook and requires explicit approval before overwriting an existing target DB.
|
|
|
|
## Flow: `CI validation gates`
|
|
1. GitHub Actions starts `.github/workflows/ci.yml` on `pull_request`, `push` to `main`, or `workflow_dispatch`.
|
|
2. `lint` runs `ruff check .` with the conservative required rule set.
|
|
3. `contract-regression` runs `pytest tests/test_contract_regression.py` with synthetic pytest temp DBs and committed contract snapshots.
|
|
4. `pytest-regression` runs the non-dashboard regression suite.
|
|
5. `dashboard-app-test` runs `pytest tests/test_dashboard_app.py` using `scripts/ci_fixture_db.py` synthetic DB setup.
|
|
6. `dashboard-http-smoke` starts Streamlit against a synthetic DB and polls readiness.
|
|
7. `db-safety-smoke` runs restore smoke through temp source/backup/target DB paths only.
|
|
8. Any required job failure fails the workflow. Stable required-check job names remain `pytest-regression`, `dashboard-app-test`, `dashboard-http-smoke`, `db-safety-smoke`, `contract-regression`, and `lint`.
|
|
|
|
## Flow: `Streamlit browser evidence capture`
|
|
1. Operator runs `scripts/streamlit_browser_evidence.py` or starts Streamlit against a synthetic fixture DB.
|
|
2. The script/flow refuses to use the default operating DB path for evidence capture.
|
|
3. Browser smoke opens key pages such as `요약`, `자산/마감`, `분류 규칙`, `확인필요 큐`, and `Import`.
|
|
4. Verification records rendered headings/content and browser console JS error absence.
|
|
5. UI/dashboard-impacting batches must attach browser screenshot/DOM evidence or equivalent browser smoke notes.
|
|
|
|
## Flow Constraints
|
|
- Preview before broad import or categorization mutation where supported.
|
|
- Do not include `transfer`, `investment`, `exclude`, or unresolved rows in actual household spending totals unless a report explicitly asks for account movement.
|
|
- Preserve raw import evidence for audit and future reclassification.
|
|
- Avoid destructive migrations without a backup/approval plan.
|
|
- Before broad DB mutation, capture DB status evidence and create or confirm a recent backup.
|
|
- Restore execution is script/runbook only and must not be exposed as an MCP tool.
|
|
- Streamlit browser evidence must use synthetic/validation DBs only and must not screenshot/log real account numbers, source financial filenames, passwords, full merchant/counterparty dumps, or raw payloads.
|
|
- CI gates must use synthetic/temp DBs only. The default operating DB path is forbidden for AppTest, HTTP smoke, and DB safety smoke wrappers.
|
|
- Top-level `service.py`, `db.py`, and `server.py` import paths remain compatibility surfaces until a future approved REQ retires them.
|
|
|
|
## Current Gaps / Planned Changes
|
|
- Browser-level evidence exists locally and remains outside required CI gates by design.
|
|
- Phase 4+ write/import/advanced workflow service thinning and narrower adapters are deferred to GitHub Project TODO items.
|
|
- HTTP adapter and remote ops re-architecture remain deferred.
|
|
|
|
## Update Triggers
|
|
- Update this document when a command entry point changes.
|
|
- Update this document when a runtime orchestration path changes.
|
|
- Update this document when a batch changes the approved flow baseline.
|
|
|
|
## Change Log
|
|
- 2026-06-26 22:24 KST: Created by `bootstrap-baseline` from repository observation.
|
|
- 2026-06-27 10:17 KST: BAT-002/REQ-002 기준으로 운영 backup/status/list/hash 및 restore 제한 flow 추가.
|
|
- 2026-06-29 KST: REQ-003/BAT-003 기준으로 statement-unavailable 수동 잔액대조 flow 추가.
|
|
- 2026-06-29 KST: REQ-004/BAT-004 기준으로 Streamlit browser evidence capture flow 및 UI evidence gate 기준 추가.
|
|
- 2026-06-29 KST: REQ-005/BAT-005 기준으로 dashboard operations hub 및 `liquidity_bucket`/`last_balance` 자산 유동성 flow 추가.
|
|
- 2026-06-30 KST: REQ-006/BAT-006 기준으로 GitHub Actions CI validation gates, synthetic fixture DB boundary, AppTest/HTTP/DB safety smoke flow 추가.
|
|
- 2026-06-30 KST: REQ-007/REQ-008/BAT-007 기준으로 contract-regression/lint CI required-check flow 추가.
|
|
- 2026-07-03 KST: REQ-013/REQ-014/BAT-010 기준으로 service facade → application, db shim → infrastructure/sqlite, MCP/Streamlit adapter seam flow를 반영했다.
|