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,69 @@
+# CI Smoke Gates Runbook
+
+- Scope: BAT-006 / REQ-006 pytest, Streamlit AppTest, dashboard HTTP smoke, and DB safety smoke gates.
+- Safety rule: every command below creates or uses a synthetic fixture/temporary validation DB only. Do not set `JARCA_LEDGER_DB_PATH` to the operating ledger DB for CI reproduction.
+
+## GitHub Actions gates
+
+The workflow is `.github/workflows/ci.yml` and runs on:
+
+- `pull_request`
+- `push` to `main`
+- `workflow_dispatch`
+
+Stable job/check names:
+
+- `pytest-regression`
+- `dashboard-app-test`
+- `dashboard-http-smoke`
+- `db-safety-smoke`
+
+## Local reproduction
+
+From repository root:
+
+```bash
+source .venv/bin/activate
+pytest --ignore=tests/test_dashboard_app.py
+pytest tests/test_dashboard_app.py
+python scripts/ci_dashboard_http_smoke.py --host 127.0.0.1 --port 18501 --timeout 45
+python scripts/ci_db_safety_smoke.py --timeout 45
+```
+
+With uv, equivalent CI-style commands are:
+
+```bash
+uv sync --extra dev --extra dashboard
+uv run pytest --ignore=tests/test_dashboard_app.py
+uv run pytest tests/test_dashboard_app.py
+uv run python scripts/ci_dashboard_http_smoke.py --host 127.0.0.1 --port 18501 --timeout 45
+uv run python scripts/ci_db_safety_smoke.py --timeout 45
+```
+
+## Wrapper responsibilities
+
+- `scripts/ci_fixture_db.py`
+  - Creates a deterministic synthetic fixture DB named `fixture.sqlite3`, `ci-ledger-fixture.sqlite3`, or `ledger-fixture.sqlite3`.
+  - Refuses the default operating DB path.
+  - Seeds only synthetic accounts, categories, budgets, and transactions.
+- `scripts/ci_dashboard_http_smoke.py`
+  - Creates a temp synthetic fixture DB.
+  - Starts Streamlit with `JARCA_LEDGER_DB_PATH` pointed at that fixture.
+  - Polls a loopback URL until HTTP 200 or timeout.
+  - Terminates/kills the Streamlit process during cleanup.
+  - Emits status-only JSON.
+- `scripts/ci_db_safety_smoke.py`
+  - Creates a temp synthetic fixture DB and backup copy.
+  - Runs `scripts/ledger_restore_smoke.py` against temp source/backup/target paths only.
+  - Emits status-only JSON and never requires restore approval because the target is newly created under temp space.
+
+## Browser evidence boundary
+
+Browser screenshot/DOM evidence remains local evidence from `scripts/streamlit_browser_evidence.py`. It is not a required GitHub Actions gate. Use it in addition to the CI gates when a change materially affects visual layout or browser-only behavior.
+
+## Failure triage
+
+- `pytest-regression` failure: reproduce with `pytest --ignore=tests/test_dashboard_app.py` and fix the failing unit/service/parser test.
+- `dashboard-app-test` failure: reproduce with `pytest tests/test_dashboard_app.py`; inspect Streamlit AppTest exceptions first.
+- `dashboard-http-smoke` failure: check whether port 18501 is already in use locally, then rerun with a different port if needed. In CI the job uses a fresh runner.
+- `db-safety-smoke` failure: inspect the wrapper JSON fields `restore_smoke_exit_code`, `restored_integrity`, and `health_success`. Do not retry against the operating DB.
@@ -0,0 +1,57 @@
+# 수동 증빙 및 잔액대조 Runbook
+
+- Source: REQ-003 / BAT-003 / dcy-003
+- Last Updated (KST): 2026-06-29
+- Owner: 렛저장인
+
+## 목적
+
+거래내역 파일이 없거나 일부만 import 가능한 계좌(`manual_only`, `partial_import`)를 대상으로 수동 증빙 거래를 입력하고 기준 잔액과 계산 잔액을 대조한다.
+
+## 안전 원칙
+
+1. 운영 DB 변경 전 dcy-002 절차에 따라 DB 상태 evidence를 확인하고 백업을 생성한다.
+2. 검증 DB에서 먼저 preview/reconcile을 수행한다.
+3. restore는 사용자 명시 승인 없이는 실행하지 않는다.
+4. 원문 증빙, 평문 계좌번호, 비밀번호, 민감 counterparty 원문은 문서/로그/커밋에 남기지 않는다.
+
+## 계좌 상태 정의
+
+- `unknown`: 아직 statement 지원 여부가 정리되지 않음.
+- `import_supported`: 기존 statement import 흐름으로 처리 가능.
+- `manual_only`: statement-unavailable 계좌. 수동 증빙 및 잔액대조 대상.
+- `partial_import`: 일부 statement import 가능하지만 누락 구간 수동 보완 및 잔액대조 대상.
+
+## 입력 포맷
+
+잔액대조 report 입력:
+
+- `account_id`: 특정 계좌만 대조할 때 사용. 비우면 활성 `manual_only`, `partial_import` 계좌 전체.
+- `baseline_balance`: 기준 잔액. 없으면 계좌 `last_balance` 사용.
+- `baseline_at`: 기준 시각. `YYYY-MM`은 해당 월 말일 `23:59:00+09:00`, `YYYY-MM-DD`는 해당일 `23:59:00+09:00`, ISO datetime은 수시 스냅샷 시각.
+- `source_note`: 예: 월말 앱 잔액, 통장 화면 메모 등 비민감 출처 설명.
+- `memo`: 운영자 메모.
+
+## 절차
+
+1. 계좌 화면 또는 MCP/service로 `statement_status`를 설정한다.
+2. 수동 증빙 거래는 `source='manual'`, 양수 금액, 거래일, 계좌, 비민감 메모를 갖추어 입력한다.
+3. `get_balance_reconciliation_report`를 실행한다.
+4. 결과를 확인한다.
+   - `OK`: 차액 절대값이 1,000원 이하.
+   - `REVIEW_NEEDED`: 차액 절대값이 1,000원 초과. 후보 판정값 중 하나로 수동 검토한다.
+   - `BASELINE_REQUIRED`: 기준 잔액이 없어 판정 불가.
+5. `REVIEW_NEEDED`는 `계좌이동`, `실지출`, `실수입`, `투자이동`, `분석제외`, `확인필요` 중 하나로 수동 확정할 근거를 모은다.
+
+## 판정 기준
+
+- 계좌이동: 같은 소유자의 다른 계좌 입출금과 금액/일자/상대방 근거가 맞음.
+- 실지출: 외부로 자금이 나갔고 household expense로 보아야 함.
+- 실수입: 외부에서 들어온 실제 수입.
+- 투자이동: 증권/투자 계좌 매수·매도·입출금 등 투자 포지션 이동.
+- 분석제외: 금융 내부 조정, 오류 정정, 분석에 넣으면 왜곡되는 항목.
+- 확인필요: 근거 부족으로 확정 보류.
+
+## 제외
+
+자동 스케줄링/알림, 전용 워크벤치, 자동 확정 mutation은 이번 runbook 범위가 아니다.
@@ -0,0 +1,90 @@
+# Streamlit Browser Evidence Runbook
+
+## 목적
+
+Streamlit dashboard 변경을 QC할 때 synthetic DB와 local Chrome으로 browser-level screenshot/snapshot evidence를 수집한다. 운영 DB, 실제 금융 파일, 비밀번호, raw_payload는 사용하지 않는다.
+
+## 표준 명령
+
+```bash
+cd /root/projects/jarca-ledger-mcp
+.venv/bin/python scripts/streamlit_browser_evidence.py
+```
+
+기본 산출물 위치:
+
+```text
+docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/evidence/run-YYYYMMDD-HHMMSS/
+├── fixture.sqlite3
+├── manifest.json
+├── rules.png
+├── rules.dom.html
+├── transfer-review.png
+├── transfer-review.dom.html
+├── import.png
+└── import.dom.html
+```
+
+## 전제 조건
+
+- Chrome: `/usr/bin/google-chrome-stable`
+- Streamlit: `.venv/bin/streamlit`
+- Dashboard dependencies installed in `.venv`
+- 실행 DB는 script가 생성하는 `fixture.sqlite3`만 사용
+
+## 실행 흐름
+
+1. script가 output directory를 만들고 synthetic fixture DB를 생성한다.
+2. `JARCA_LEDGER_DB_PATH=<output>/fixture.sqlite3`로 Streamlit을 `127.0.0.1:18501`에 기동한다.
+3. Chrome DevTools Protocol로 page를 열고 page 제목 텍스트가 렌더링될 때까지 대기한다.
+4. 각 page의 PNG screenshot과 DOM snapshot을 저장한다.
+5. `manifest.json`에 page/url/path/byte size와 fixture DB 정보를 남긴다.
+6. script 종료 시 Streamlit과 Chrome process를 종료한다.
+
+## 대상 페이지
+
+기본 대상:
+
+- `분류 규칙`
+- `확인필요 큐`
+- `Import`
+
+추가 page를 지정하려면 `--page`를 반복한다.
+
+```bash
+.venv/bin/python scripts/streamlit_browser_evidence.py --page 계좌 --page 미분류
+```
+
+## QC evidence gate
+
+| Batch 유형 | 최소 evidence | 판정 기준 |
+| --- | --- | --- |
+| Streamlit UI 또는 `dashboard/app.py` 영향 | Browser screenshot + DOM snapshot + manifest | 누락 시 QC BLOCK 또는 재실행 |
+| 비-UI service/MCP/parser 변경 | pytest/py_compile 중심, browser evidence 선택 | browser 누락 비차단 |
+| docs-only 변경 | 문서 diff/review | browser evidence 불필요 |
+| Chrome 환경 장애가 입증된 UI 변경 | AppTest + HTTP 200 + 실패 로그 | `PASS_WITH_NOTES`만 허용 |
+
+## 민감정보 금지
+
+다음은 screenshot, snapshot, manifest, test log, docs에 남기지 않는다.
+
+- 운영 DB 기본 경로의 실제 row dump
+- 실제 계좌번호/카드번호/잔액 화면
+- 실제 거래처/상대방 full dump
+- 원본 금융 파일명 또는 파일 내용
+- 비밀번호, PDF/XLSX password
+- `raw_payload` 원문
+
+## 실패 시 fallback
+
+Chrome 또는 browser capture가 실패한 경우:
+
+1. 실패 명령, Chrome 경로, stderr/오류 메시지를 verification 문서에 기록한다.
+2. `.venv/bin/python -m py_compile dashboard/app.py`를 실행한다.
+3. `streamlit.testing.v1.AppTest` 또는 HTTP 200 smoke를 실행한다.
+4. UI 영향 batch라면 fallback evidence만으로는 `PASS_WITH_NOTES`까지만 허용하고 browser evidence 복구 잔여 항목을 남긴다.
+
+## 주의
+
+- 이 runbook은 로컬 재현 절차다. CI 통합은 후속 Project #4 항목에서 별도 다룬다.
+- Playwright Python은 후속 CI 후보이며 현재 표준 경로가 아니다.