# 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-014_20260703_adapter-surface-narrowing-baseline-refresh/evidence/run-YYYYMMDD-HHMMSS/
├── fixture.sqlite3
├── manifest.json
├── overview.png
├── overview.dom.html
├── 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 후보이며 현재 표준 경로가 아니다.