146 lines
14 KiB
Markdown
146 lines
14 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-06-30
|
|
- Source Discovery / Batch: bootstrap-baseline, BAT-006, BAT-007
|
|
- 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, and reconciliation 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` as the central domain/service layer.
|
|
- Parser modules for KB/Toss/SeoulPay sources.
|
|
- Category and `cashflow_kind` semantics shared by reports and UI.
|
|
|
|
## Flow: `MCP server tool call`
|
|
1. Hermes MCP client invokes a tool exposed by `jarca_ledger_mcp.server`.
|
|
2. `server.py` forwards arguments to the matching `service.py` function.
|
|
3. `service.py` opens the SQLite database path from env/default, validates inputs, and performs the operation.
|
|
4. Service returns a dictionary payload with success data or error information.
|
|
5. 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 service functions for reads, updates, imports, categorization, and manual linking.
|
|
5. UI displays success/error status and refreshes visible tables.
|
|
|
|
## Flow: `Dashboard operations hub overview`
|
|
1. Operator opens the `요약` page.
|
|
2. Dashboard resolves the KST current month and calls `get_monthly_cashflow_report(month)` using `transactions.transaction_date` and `ledger_categories.cashflow_kind` semantics.
|
|
3. Dashboard calls `get_asset_liquidity_report`, which groups active accounts by `accounts.liquidity_bucket` and uses only `accounts.last_balance` for asset/liability values.
|
|
4. Dashboard renders sections in REQ-005 priority order: this-month actual income/expense/net/savings rate, asset liquidity, asset composition, budget/spend, operational warnings.
|
|
5. Missing `last_balance` account rows are excluded from asset totals and surfaced as warnings; transaction sums are not used to estimate non-transaction assets.
|
|
|
|
## Flow: `CI validation gates`
|
|
1. GitHub Actions starts `.github/workflows/ci.yml` on `pull_request`, `push` to `main`, or `workflow_dispatch`.
|
|
2. `lint` installs dev dependencies and runs `ruff check .` with the conservative BAT-007 required rule set.
|
|
3. `contract-regression` installs dev dependencies and runs `pytest tests/test_contract_regression.py`; the test uses synthetic pytest temp DBs and `tests/contract_snapshots/response_contract_v1_0.json` metadata for health/status, list, report, and mutation success envelope scopes.
|
|
4. `pytest-regression` installs the project with dev/dashboard extras and runs `pytest --ignore=tests/test_dashboard_app.py` so service/parser/regression failures fail the workflow.
|
|
5. `dashboard-app-test` runs `pytest tests/test_dashboard_app.py`; the AppTest test creates a synthetic fixture DB through `scripts/ci_fixture_db.py`, sets `JARCA_LEDGER_DB_PATH`, and asserts core dashboard pages render without Streamlit exceptions.
|
|
6. `dashboard-http-smoke` runs `scripts/ci_dashboard_http_smoke.py`; the wrapper creates a temp fixture DB, starts Streamlit on loopback, polls for HTTP 200, then terminates the process.
|
|
7. `db-safety-smoke` runs `scripts/ci_db_safety_smoke.py`; the wrapper creates temp source/backup/target DB files and invokes `scripts/ledger_restore_smoke.py` without touching the operating DB path.
|
|
8. Any required job failure fails the workflow. Stable required-check job names are `pytest-regression`, `dashboard-app-test`, `dashboard-http-smoke`, `db-safety-smoke`, `contract-regression`, and `lint`; actual branch protection toggle enforcement is configured outside the repository.
|
|
9. CI logs are status-oriented and synthetic-data-only; they must not contain real account identifiers, raw payloads, statement filenames, balances from the operating DB, or passwords.
|
|
|
|
## Flow: `Import preview and import`
|
|
1. Operator chooses or supplies 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, service creates/fetches the target account, inserts non-duplicate transactions, writes raw provenance, and records an import batch.
|
|
4. Reports and dashboard views read the inserted rows using category and 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 functions 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.
|
|
6. Verification evidence must not include full transaction dumps, full merchant/counterparty dumps, account identifiers, raw_payload, original financial file contents, or passwords.
|
|
|
|
## Flow: `Statement-unavailable manual balance reconciliation`
|
|
1. Operator follows the dcy-002 safety standard first: capture DB status, create or confirm a recent backup, and run preview/reconcile on a validation DB before operating on the production DB.
|
|
2. Operator marks accounts with `statement_status`: `manual_only` for statement-unavailable accounts, `partial_import` for accounts that require manual supplementation, or `import_supported` where normal statement import is sufficient.
|
|
3. Operator records manual evidence transactions with `source='manual'`, positive amount, date, account, and non-sensitive memo/source context.
|
|
4. Operator runs `get_balance_reconciliation_report` from MCP/service or the dashboard account page. If `baseline_at` is `YYYY-MM`, the snapshot time is that month end at 23:59 KST; ad-hoc reconciliation uses the user-supplied snapshot timestamp.
|
|
5. The report compares `baseline_balance`/`last_balance` with the latest `balance_after` if available, otherwise with net signed account transactions. Absolute tolerance is 1,000 KRW; 0.1% of baseline is reference-only.
|
|
6. `OK` rows need no immediate triage. `REVIEW_NEEDED` rows present manual decision candidates: `계좌이동`, `실지출`, `실수입`, `투자이동`, `분석제외`, `확인필요`.
|
|
7. This flow does not run automatic scheduling, notifications, restore, or auto-confirming mutation.
|
|
|
|
## Flow: `Streamlit browser evidence capture`
|
|
1. Operator runs `scripts/streamlit_browser_evidence.py` from the repository root.
|
|
2. The script creates a synthetic fixture DB under the evidence output directory and refuses to use the default operating DB path.
|
|
3. Streamlit starts with `JARCA_LEDGER_DB_PATH=<fixture.sqlite3>` on a local loopback port.
|
|
4. `/usr/bin/google-chrome-stable` runs in headless mode through Chrome DevTools Protocol and opens target dashboard pages such as `분류 규칙`, `확인필요 큐`, and `Import`.
|
|
5. After page title text is rendered, the script stores PNG screenshots, DOM snapshots, and `manifest.json` in the evidence directory.
|
|
6. UI/dashboard-impacting batches must attach browser screenshot/snapshot evidence. Non-UI batches may treat it as optional, and docs-only batches do not require browser evidence.
|
|
7. If Chrome/browser capture is unavailable, AppTest + HTTP 200 fallback evidence is allowed only as `PASS_WITH_NOTES` with the environment failure and remaining browser-evidence item recorded.
|
|
8. Browser screenshot/DOM evidence is not a required GitHub Actions gate in BAT-006. Run it locally for visual/layout-sensitive dashboard changes, while non-visual backend/CI changes can rely on pytest/AppTest/HTTP/DB safety gates.
|
|
|
|
## 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.
|
|
- Manual balance reconciliation must remain preview/report-first unless a future REQ approves persistent review routing and confirmation mutation.
|
|
- Streamlit browser evidence must use synthetic/validation DBs only and must not screenshot/log real account numbers, balances, source financial filenames, passwords, full merchant/counterparty dumps, or raw payloads.
|
|
- CI gates must use synthetic/temp DBs only. The default operating DB path (`~/.local/share/jarca/ledger.sqlite3`) is forbidden for AppTest, HTTP smoke, and DB safety smoke wrappers.
|
|
- Contract regression must use synthetic/temp DBs only and must not expose runtime contract-version fields in MCP success payloads unless a future approved REQ changes the policy.
|
|
- Branch protection required-check drift should be audited against the six stable workflow job names documented in `docs/interface-contract.md`; changing a job name requires an explicit REQ/BAT note because it can break external repository settings.
|
|
- Dashboard asset liquidity calculations must use `accounts.liquidity_bucket` and `accounts.last_balance`; `loan` is excluded from the asset composition denominator and reflected as debt/net-worth only.
|
|
- Sensitive passwords are runtime inputs and must not be committed.
|
|
|
|
## Current Gaps / Planned Changes
|
|
- Browser-level evidence is available locally through `scripts/streamlit_browser_evidence.py`; it remains outside required CI gates by design.
|
|
- Contract-regression and lint gates are now part of the required-check contract for CI; full MCP tool-surface snapshot coverage remains deferred beyond the representative health/status/list/report/mutation scope.
|
|
- Dedicated reconciliation workbench and persistent review-decision queue are deferred beyond REQ-003.
|
|
- Separate asset snapshot/manual asset tables and automatic market/real-estate valuation are deferred beyond REQ-005.
|
|
|
|
## 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, local browser evidence boundary 추가.
|
|
- 2026-06-30 KST: REQ-007/REQ-008/BAT-007 기준으로 `contract-regression`/`lint` CI required-check flow, contract snapshot scope, branch protection drift boundary 추가.
|