chore(jarca-ledger): finalize approved batch docs, dashboard, and CI smoke updates

2026-06-30 16:06:47 +09:00
parent 67d8d4871b
commit 4929e52189
75 changed files with 8367 additions and 252 deletions
@@ -0,0 +1,44 @@
+{
+  "success": true,
+  "base_url": "http://127.0.0.1:18501",
+  "output_dir": "/root/projects/jarca-ledger-mcp/docs/batches/bat-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow/evidence/run-20260629-2111",
+  "fixture": {
+    "account_id": "acct_6cf9a9db8669",
+    "transaction_ids": [
+      "tx_f60380340545",
+      "tx_8c16f1387fb1",
+      "tx_445884ce8638",
+      "tx_ead36edf0c7e",
+      "tx_dc27408a7e81"
+    ],
+    "db_path": "docs/batches/bat-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow/evidence/run-20260629-2111/fixture.sqlite3"
+  },
+  "chrome": "/usr/bin/google-chrome-stable",
+  "streamlit": ".venv/bin/streamlit",
+  "pages": [
+    {
+      "page": "요약",
+      "url": "http://127.0.0.1:18501/?page=%EC%9A%94%EC%95%BD",
+      "screenshot": "docs/batches/bat-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow/evidence/run-20260629-2111/overview.png",
+      "screenshot_bytes": 303341,
+      "snapshot": "docs/batches/bat-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow/evidence/run-20260629-2111/overview.dom.html",
+      "snapshot_bytes": 30757,
+      "devtools_port": 19222,
+      "inner_text_head": "💰 Jarca Ledger\n\n가계부 · 분류 · Import 운영 콘솔\n\n메뉴\n요약\n거래내역\n확인필요 큐\n미분류\n분류 규칙\n카테고리\n계좌\nImport\nStop\nDeploy\n📊 요약\n가계부 운영 대시보드\n\n이번 달 실제 현금흐름, 자산 유동성, 운영 경고를 우선순위대로 확인합니다.\n\nschema v8\nKST 이번 달\nlast_balance 기준 자산\n\nDB: /root/projects/jarca-ledger-mcp/docs/batches/bat-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow/evidence/run-20260629-2111/fixture.sqlite3\n\n💎\n이번 달 수입/지출 현황\n\n기준: KST 현재 월 2026-06, transactions.transaction_date, ledger_categories.cashflow_kind 실제 현금흐름\n\n🏦\n자산 유동성 현황\n\n기준: accounts.liqu"
+    }
+  ],
+  "server_command": [
+    ".venv/bin/streamlit",
+    "run",
+    "dashboard/app.py",
+    "--server.address",
+    "127.0.0.1",
+    "--server.port",
+    "18501",
+    "--server.headless",
+    "true",
+    "--browser.gatherUsageStats",
+    "false"
+  ],
+  "server_log_tail": ""
+}
@@ -0,0 +1,44 @@
+{
+  "success": true,
+  "base_url": "http://127.0.0.1:18503",
+  "output_dir": "/root/projects/jarca-ledger-mcp/docs/batches/bat-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow/evidence/run-check-20260630-073738",
+  "fixture": {
+    "account_id": "acct_d3b8cccfccb4",
+    "transaction_ids": [
+      "tx_4b8447f7aa07",
+      "tx_b2ca8a05ac82",
+      "tx_8c989e7c3b15",
+      "tx_f48e63972a9e",
+      "tx_4e20d08f8df3"
+    ],
+    "db_path": "docs/batches/bat-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow/evidence/run-check-20260630-073738/fixture.sqlite3"
+  },
+  "chrome": "/usr/bin/google-chrome-stable",
+  "streamlit": ".venv/bin/streamlit",
+  "pages": [
+    {
+      "page": "요약",
+      "url": "http://127.0.0.1:18503/?page=%EC%9A%94%EC%95%BD",
+      "screenshot": "docs/batches/bat-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow/evidence/run-check-20260630-073738/overview.png",
+      "screenshot_bytes": 301342,
+      "snapshot": "docs/batches/bat-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow/evidence/run-check-20260630-073738/overview.dom.html",
+      "snapshot_bytes": 29881,
+      "devtools_port": 19222,
+      "inner_text_head": "💰 Jarca Ledger\n\n가계부 · 분류 · Import 운영 콘솔\n\n메뉴\n요약\n거래내역\n확인필요 큐\n미분류\n분류 규칙\n카테고리\n계좌\nImport\nStop\nDeploy\n📊 요약\n가계부 운영 대시보드\n\n이번 달 실제 현금흐름, 자산 유동성, 운영 경고를 우선순위대로 확인합니다.\n\nschema v8\nKST 이번 달\nlast_balance 기준 자산\n\nDB: /root/projects/jarca-ledger-mcp/docs/batches/bat-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow/evidence/run-check-20260630-073738/fixture.sqlite3\n\n💎\n이번 달 수입/지출 현황\n\n기준: KST 현재 월 2026-06, transactions.transaction_date, ledger_categories.cashflow_kind 실제 현금흐름\n\n🏦\n자산 유동성 현황\n\n기준: accou"
+    }
+  ],
+  "server_command": [
+    ".venv/bin/streamlit",
+    "run",
+    "dashboard/app.py",
+    "--server.address",
+    "127.0.0.1",
+    "--server.port",
+    "18503",
+    "--server.headless",
+    "true",
+    "--browser.gatherUsageStats",
+    "false"
+  ],
+  "server_log_tail": ""
+}
@@ -0,0 +1,44 @@
+{
+  "success": true,
+  "base_url": "http://127.0.0.1:18501",
+  "output_dir": "/root/projects/jarca-ledger-mcp/docs/batches/bat-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow/evidence/run-verify-20260629-215958",
+  "fixture": {
+    "account_id": "acct_86182dd8b283",
+    "transaction_ids": [
+      "tx_6e7d47621557",
+      "tx_546ed7a78004",
+      "tx_f40ec3aa2df0",
+      "tx_3207e5cdde0d",
+      "tx_fa79d639eda4"
+    ],
+    "db_path": "docs/batches/bat-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow/evidence/run-verify-20260629-215958/fixture.sqlite3"
+  },
+  "chrome": "/usr/bin/google-chrome-stable",
+  "streamlit": ".venv/bin/streamlit",
+  "pages": [
+    {
+      "page": "요약",
+      "url": "http://127.0.0.1:18501/?page=%EC%9A%94%EC%95%BD",
+      "screenshot": "docs/batches/bat-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow/evidence/run-verify-20260629-215958/overview.png",
+      "screenshot_bytes": 303039,
+      "snapshot": "docs/batches/bat-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow/evidence/run-verify-20260629-215958/overview.dom.html",
+      "snapshot_bytes": 32797,
+      "devtools_port": 19222,
+      "inner_text_head": "💰 Jarca Ledger\n\n가계부 · 분류 · Import 운영 콘솔\n\n메뉴\n요약\n거래내역\n확인필요 큐\n미분류\n분류 규칙\n카테고리\n계좌\nImport\n\n새로고침\n\nStop\nDeploy\n📊 요약\n가계부 운영 대시보드\n\n이번 달 실제 현금흐름, 자산 유동성, 운영 경고를 우선순위대로 확인합니다.\n\nschema v8\nKST 이번 달\nlast_balance 기준 자산\n\nDB: /root/projects/jarca-ledger-mcp/docs/batches/bat-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow/evidence/run-verify-20260629-215958/fixture.sqlite3\n\n💎\n이번 달 수입/지출 현황\n\n기준: KST 현재 월 2026-06, transactions.transaction_date, ledger_categories.cashflow_kind 실제 현금흐름\n\n🏦\n자산 유동성 현황\n\n기"
+    }
+  ],
+  "server_command": [
+    ".venv/bin/streamlit",
+    "run",
+    "dashboard/app.py",
+    "--server.address",
+    "127.0.0.1",
+    "--server.port",
+    "18501",
+    "--server.headless",
+    "true",
+    "--browser.gatherUsageStats",
+    "false"
+  ],
+  "server_log_tail": ""
+}
@@ -0,0 +1,37 @@
+# BAT-005 Implementation
+
+## 코드 변경
+
+- `jarca_ledger_mcp/db.py`
+  - schema version을 `8`로 올리고 `accounts.liquidity_bucket TEXT NOT NULL DEFAULT 'other'`를 schema 및 additive migration 목록에 추가한다.
+- `jarca_ledger_mcp/service.py`
+  - `VALID_LIQUIDITY_BUCKETS`와 `normalize_liquidity_bucket` 검증을 추가한다.
+  - `create_ledger_account`/`update_ledger_account`에서 `liquidity_bucket`을 저장·수정한다.
+  - `get_asset_liquidity_report`를 추가해 `accounts.last_balance` 기반 버킷 합계, 총자산, 총부채, 순자산, 미입력 계좌를 반환한다.
+- `jarca_ledger_mcp/server.py`
+  - MCP account create/update tool signature에 `liquidity_bucket`을 추가하고 `get_asset_liquidity_report` tool을 노출한다.
+- `dashboard/app.py`
+  - 요약 화면을 REQ-005 운영 허브 순서로 재구성한다.
+  - KST 현재 월 기준 월간 실제 수입/지출/순현금흐름/저축률을 최상단에 표시한다.
+  - 자산 유동성, 자산 구성, 예산/지출, 운영 경고 섹션을 추가한다.
+  - 계좌 화면에 `liquidity_bucket` 표시/수정 control을 추가한다.
+- `scripts/streamlit_browser_evidence.py`
+  - synthetic fixture에 `cash`, `investment`, `loan`, `real_estate` bucket 계좌와 월간 수입/지출/예산 데이터를 추가한다.
+- `tests/test_service.py`
+  - schema version, liquidity bucket 검증, account flow, asset liquidity report regression을 추가한다.
+
+## 문서 변경
+
+- `docs/batches/bat-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow/`
+- `docs/batches/index.md`
+- `docs/srs/Interface/req-005_dashboard-operations-hub-liquidity-monthly-cashflow.md`
+- `docs/data-model.md`
+- `docs/project-structure.md`
+- `docs/runtime-flows.md`
+- `docs/interface-contract.md`
+
+## 운영 안전
+
+- 운영 DB와 실제 금융 원본 파일은 사용하지 않는다.
+- browser evidence는 synthetic fixture DB로만 생성한다.
+- migration은 additive/idempotent이며 기존 계좌의 bucket은 `other` 기본값으로 안전하게 채워진다.
@@ -0,0 +1,25 @@
+# BAT-005 Dashboard operations hub/liquidity/monthly cashflow
+
+- Profile: standard
+- Status: release-candidate
+- Included REQ: REQ-005
+- Discovery: dcy-005
+- Owner: 렛저장인
+- Date (KST): 2026-06-29
+
+## 목표
+
+REQ-005에 따라 Streamlit 요약 화면을 월중 운영 허브로 재구성하고, 계좌 단위 `liquidity_bucket`과 `last_balance`를 권위 소스로 하는 자산 유동성/구성/부채/순자산 뷰를 제공한다.
+
+## 산출물
+
+- `accounts.liquidity_bucket` additive/idempotent schema migration
+- 계좌 create/list/update 및 MCP tool signature의 `liquidity_bucket` 지원
+- `service.get_asset_liquidity_report` 자산 유동성/순자산 report
+- `dashboard/app.py` 요약 운영 허브 및 계좌 liquidity bucket 편집 UI
+- BAT-005 planning/implementation/verification 문서와 baseline 문서 갱신
+- synthetic/validation DB 기반 Streamlit browser evidence
+
+## 범위 제한
+
+실시간 금융 연동, 자동 시세 평가, 별도 `asset_snapshots`/`manual_assets` 테이블, 거래/카테고리 단위 liquidity override, dcy-006 범위는 포함하지 않는다.
@@ -0,0 +1,30 @@
+# BAT-005 Planning
+
+## 구현 전략
+
+1. REQ-005의 승인 상태를 입력 gate로 확인하고 BAT-005 batch 문서를 생성한다.
+2. `accounts.liquidity_bucket`을 additive/idempotent column으로 추가한다. 허용값은 `cash`, `investment`, `deposit`, `real_estate`, `loan`, `other`이며 기존/미지정 계좌는 `other`로 폴백한다.
+3. 서비스 계층에서 create/list/update 계좌 흐름에 `liquidity_bucket`을 노출하고 허용값 검증을 추가한다.
+4. 자산 유동성 report는 `accounts.last_balance`만 사용한다. `last_balance`가 없는 비거래 자산/부채는 임의 추정하지 않고 missing warning으로 남긴다.
+5. `page_overview`는 다음 순서로 재구성한다: 이번 달 수입/지출 현황 → 자산 유동성 현황 → 자산 구성 → 지출 구조/예산 → 운영 경고.
+6. `scripts/streamlit_browser_evidence.py` synthetic fixture에 overview 검증용 자산/부채/예산/월간 현금흐름 데이터를 추가하고, BAT-005 evidence output directory로 실행한다.
+
+## Design Gate
+
+- Profile: `standard`
+- 판단 근거: DB schema, service/MCP contract, Streamlit UI, tests, baseline docs가 함께 변하는 기능 batch다.
+- 별도 `design.md`: planning에 설계 결정을 포함하고, 구현 상세는 `implementation.md`에서 추적한다.
+
+## 핵심 설계 결정
+
+- 유동성 권위 소스는 계좌 단위 `accounts.liquidity_bucket`으로 고정한다.
+- 자산 평가는 `accounts.last_balance`를 사용하며, 거래 합계로 부동산/예적금/대출 현재가를 추정하지 않는다.
+- `loan` 버킷은 자산 구성 비율 분모에서 제외하고 총부채/순자산 계산에만 반영한다.
+- `last_balance`가 없는 계좌는 계산에서 제외하되 운영 경고에 표시한다.
+
+## 검증 계획
+
+- `py_compile` for changed Python files
+- `pytest tests/test_service.py -q`
+- full `pytest -q`
+- `scripts/streamlit_browser_evidence.py --page 요약 --output-dir docs/batches/bat-005_.../evidence/run-...` with synthetic DB
@@ -0,0 +1,44 @@
+# BAT-005 Verification
+
+## 검증 계획
+
+1. Python 문법 검증
+   - `.venv/bin/python -m py_compile jarca_ledger_mcp/db.py jarca_ledger_mcp/service.py jarca_ledger_mcp/server.py dashboard/app.py scripts/streamlit_browser_evidence.py tests/test_service.py`
+2. 대상 service regression
+   - `.venv/bin/python -m pytest tests/test_service.py -q`
+3. 전체 테스트
+   - `.venv/bin/python -m pytest -q`
+4. Streamlit browser evidence
+   - `.venv/bin/python scripts/streamlit_browser_evidence.py --page 요약 --output-dir docs/batches/bat-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow/evidence/run-<timestamp>`
+5. 민감정보 검토
+   - evidence fixture는 synthetic 데이터만 포함한다.
+   - 운영 DB 기본 경로, 실제 금융 원본 파일명, 비밀번호, raw_payload는 포함하지 않는다.
+
+## Acceptance Mapping
+
+- AC-1: `db.py` schema/migration 및 schema version 8.
+- AC-2: `normalize_liquidity_bucket`, create/update validation tests.
+- AC-3: account create/list/update regression tests 및 MCP signature.
+- AC-4: `dashboard/app.py` top section 월간 cashflow metrics.
+- AC-5/6/7: `get_asset_liquidity_report` regression 및 overview asset/liability/missing balance sections.
+- AC-8: overview operational warning metrics/caption.
+- AC-9: pytest 및 browser evidence result.
+- AC-10: baseline docs updated.
+
+## 결과
+
+최종 검증 결과(2026-06-29 KST):
+
+- `source .venv/bin/activate && python -m py_compile jarca_ledger_mcp/db.py jarca_ledger_mcp/service.py jarca_ledger_mcp/server.py dashboard/app.py scripts/streamlit_browser_evidence.py tests/test_service.py tests/test_ledger_categories.py` — PASS.
+- `source .venv/bin/activate && pytest tests/test_service.py -q` — PASS (`9 passed`).
+- `source .venv/bin/activate && pytest -q` — PASS (`31 passed, 4 skipped`).
+- `source .venv/bin/activate && python scripts/streamlit_browser_evidence.py --page 요약 --output-dir docs/batches/bat-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow/evidence/run-20260629-2111` — PASS.
+  - Evidence directory: `docs/batches/bat-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow/evidence/run-20260629-2111/`
+  - Manifest: `manifest.json` (`success: true`).
+  - Captured page: `요약` / `overview.png` 303,341 bytes / `overview.dom.html` 30,757 bytes.
+  - DOM evidence includes `schema v8`, `KST 이번 달`, `이번 달 수입/지출 현황`, and `자산 유동성 현황` from a synthetic fixture DB.
+
+## Sensitive Evidence Review
+
+- Evidence DB path is the generated fixture path under BAT-005 evidence, not the operating DB default path.
+- Fixture rows use `Synthetic`/`SYNTHETIC_*` labels and do not include real account numbers, real financial source filenames, passwords, or raw payloads.