docs: initialize StagePilot baseline

2026-06-26 22:34:16 +09:00
parent d8e36f6aa8
commit 97115f6acf
9 changed files with 698 additions and 0 deletions
@@ -0,0 +1,123 @@
+# Jarca Ledger MCP Project Structure
+
+- 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
+
+## Project Summary
+- Jarca 가계부 전용 MCP 서버와 Streamlit 대시보드로 계좌/카드 거래, 예산, 분류 규칙, import, 현금흐름 분석을 SQLite에 저장하고 운영한다.
+
+## Primary Domain
+- Korean household finance ledger and transaction reconciliation
+
+## Tech Stack
+- Python >=3.11
+- FastMCP / MCP server
+- SQLite
+- Streamlit dashboard
+- pandas / plotly dashboard dependencies
+- PyMuPDF, openpyxl, msoffcrypto-tool
+- pytest
+
+## Primary Runtime
+- Type: mixed
+- Planned Entry Points:
+  - `jarca-ledger-mcp` :: MCP stdio server for Hermes Agent tools.
+  - `dashboard/app.py` :: Streamlit dashboard for local ledger operations.
+  - `pytest` :: Regression test entry point.
+
+## Purpose
+- This document is the current repository and package structure baseline.
+- It is a cross-cutting reference document for Discovery, REQ, Batch Design, Batch Verification, and implementation updates.
+
+## Scope
+- Covers top-level repository layout and package/module boundaries.
+- Does not duplicate detailed business rules, acceptance criteria, or implementation-only function signatures.
+
+## Top-Level Structure
+
+```text
+jarca-ledger-mcp/
+├── README.md
+├── pyproject.toml
+├── uv.lock
+├── .env.example
+├── dashboard/
+│   └── app.py
+├── jarca_ledger_mcp/
+│   ├── __init__.py
+│   ├── db.py
+│   ├── service.py
+│   ├── server.py
+│   ├── kb_bank_pdf.py
+│   ├── toss_bank_pdf.py
+│   ├── toss_securities_pdf.py
+│   └── seoulpay_xlsx.py
+├── tests/
+│   ├── test_service.py
+│   ├── test_categorization.py
+│   ├── test_category_rule_filters.py
+│   ├── test_cross_account_transfer_matching.py
+│   ├── test_kb_bank_pdf.py
+│   ├── test_toss_securities_pdf.py
+│   ├── test_seoulpay_xlsx.py
+│   └── test_ledger_categories.py
+├── docs/
+│   ├── discovery/
+│   ├── srs/
+│   ├── batches/
+│   ├── releases/
+│   ├── project-structure.md
+│   ├── runtime-flows.md
+│   ├── interface-contract.md
+│   └── data-model.md
+└── .stage-pilot/
+    └── bootstrap/baseline.yaml
+```
+
+## Package / Module Responsibilities
+- `jarca_ledger_mcp/db.py`
+  - SQLite connection, schema initialization, migrations, row conversion, and database path resolution.
+- `jarca_ledger_mcp/service.py`
+  - Domain service layer for accounts, transactions, categories, category rules, imports, reports, transfer matching, and manual link operations.
+- `jarca_ledger_mcp/server.py`
+  - FastMCP tool registration layer that exposes service functions to Hermes/MCP clients.
+- `jarca_ledger_mcp/kb_bank_pdf.py`
+  - KB 국민은행 encrypted PDF transaction parsing.
+- `jarca_ledger_mcp/toss_bank_pdf.py`
+  - Toss Bank transaction-history PDF parsing.
+- `jarca_ledger_mcp/toss_securities_pdf.py`
+  - Toss Securities transaction-history PDF parsing and transaction preview conversion.
+- `jarca_ledger_mcp/seoulpay_xlsx.py`
+  - SeoulPay encrypted XLSX parsing and preview conversion.
+- `dashboard/app.py`
+  - Streamlit operator UI for summaries, transaction filtering, uncategorized triage, rule management, review queues, categories, accounts, and import operations.
+- `tests/`
+  - Regression tests for service behavior, parser behavior, categorization, category rules, cross-account transfer matching, and ledger category semantics.
+
+## Dependency Rules
+- `server.py` should remain a thin tool adapter and delegate business logic to `service.py`.
+- Parser modules should parse source documents into structured records and avoid direct UI responsibilities.
+- `dashboard/app.py` may call service functions but should not duplicate core classification/report semantics.
+- DB schema migrations should be additive and idempotent by default.
+
+## Shared Boundaries
+- `cashflow_kind` is the boundary between actual household income/expense and account movement/exclusion semantics.
+- Import evidence fields (`source`, `external_id`, `raw_summary`, `raw_payload`, `counterparty`, `import_batch_id`) are audit boundaries and should be preserved.
+- Manual reconciliation is represented through memo tags and narrow transaction updates, not broad rewrites.
+
+## Current Gaps / Planned Changes
+- Final UX verification is still needed for 분류 규칙 삭제, 취소/환급 원거래 연결, and import E2E flows.
+- CI workflow and deployment/service management are not yet defined.
+- Long-term policy for accounts without downloadable statements remains partially operational/documentation work.
+
+## Update Triggers
+- Update this document when package boundaries change.
+- Update this document when new top-level runtime or domain modules are added.
+- Update this document when a batch changes the approved structure baseline.
+
+## Change Log
+- 2026-06-26 22:24 KST: Created by `bootstrap-baseline` from repository observation.