85 lines
4.8 KiB
Markdown
85 lines
4.8 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-26 22:24
|
|
- Source Discovery / Batch: bootstrap-baseline
|
|
- 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.
|
|
|
|
## 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: `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 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.
|
|
- Sensitive passwords are runtime inputs and must not be committed.
|
|
|
|
## Current Gaps / Planned Changes
|
|
- Need final browser-level UX verification for rule delete and cancel/original linking dialogs.
|
|
- Need CI/deployment flow if this project will be maintained beyond local operation.
|
|
- Need a documented operational process for statement-unavailable accounts.
|
|
|
|
## 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.
|