91 lines
3.2 KiB
Markdown
91 lines
3.2 KiB
Markdown
# 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 후보이며 현재 표준 경로가 아니다.
|