# REQ-004 Browser/Streamlit E2E evidence 환경 복구

- Status: Implemented
- Type: Testing
- Priority: High
- Owner: 렛저장인
- Source Discovery: `docs/discovery/dcy-004_20260629_browser-streamlit-e2e-evidence-recovery.md`
- Batch: `docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/`
- Created At (KST): 2026-06-29
- Implemented At (KST): 2026-06-29

## 1. 배경

Streamlit UI batch는 실제 브라우저 렌더링 증거가 필요하지만, 기존 검증에서는 chromium snap 부재 때문에 AppTest와 HTTP 200 smoke가 반복적으로 대체 증거로 사용되었다. dcy-004 confirmed Discovery에 따라 `/usr/bin/google-chrome-stable` 기반 로컬 headless browser evidence 절차를 1차 표준으로 복구하고, fallback evidence의 허용 조건을 명확히 한다.

## 2. 범위

### In Scope
- synthetic/validation DB를 생성해 `dashboard/app.py`를 로컬 Streamlit 서버로 기동하는 절차.
- `/usr/bin/google-chrome-stable` headless Chrome DevTools Protocol 기반 screenshot 및 DOM snapshot evidence 수집.
- 최소 evidence 페이지: `분류 규칙`, `확인필요 큐`, `Import`.
- evidence 산출물: PNG screenshot, DOM snapshot HTML, manifest JSON, synthetic fixture DB.
- Streamlit UI 또는 `dashboard/app.py` 영향 batch의 QC evidence gate 규칙 문서화.
- 운영 DB, 원본 금융 파일, 비밀번호, full raw_payload를 사용하지 않는 안전장치.

### Out of Scope
- CI 통합 및 GitHub Actions 자동화.
- Playwright/Selenium 표준화. Playwright Python은 후속 CI 후보로만 둔다.
- pixel-diff 기반 visual regression.
- Streamlit 화면 기능/UX 신규 개발.

## 3. 기능 요구사항

### FR-1. Chrome 기반 브라우저 evidence 실행
- 표준 실행 경로는 `/usr/bin/google-chrome-stable`을 사용해야 한다.
- snap 기반 `chromium-browser`가 없어도 실행 가능해야 한다.
- Chrome이 없거나 Streamlit이 기동하지 않으면 명확한 실패 메시지를 반환해야 한다.

### FR-2. Synthetic DB 전용 Streamlit 기동
- evidence 절차는 `JARCA_LEDGER_DB_PATH`를 synthetic fixture DB로 지정해야 한다.
- fixture DB는 가짜 계좌/거래/분류 규칙만 포함해야 하며 운영 DB 기본 경로를 거부해야 한다.
- screenshot/log에는 실제 계좌번호, 실제 거래처, raw_payload, 원본 금융 파일명, 비밀번호를 남기지 않아야 한다.

### FR-3. Screenshot 및 snapshot 산출물
- 실행 결과는 페이지별 PNG screenshot과 DOM snapshot HTML을 저장해야 한다.
- manifest JSON은 base URL, fixture DB 경로, Chrome/Streamlit 실행 경로, 캡처한 page/url/path/byte size를 기록해야 한다.
- 최소 1개 이상이 아니라 기본 3개 페이지(`분류 규칙`, `확인필요 큐`, `Import`)를 캡처해야 한다.

### FR-4. QC evidence gate 정책
- Streamlit UI 또는 `dashboard/app.py`에 영향을 주는 batch는 browser screenshot/snapshot evidence를 필수로 한다.
- 비-UI batch는 browser evidence를 선택으로 두고, docs-only batch는 불필요로 한다.
- Chrome/브라우저 환경 장애가 명확히 입증된 경우에만 AppTest + HTTP 200 fallback evidence로 `PASS_WITH_NOTES`를 허용하고, 실패 사유와 잔여 항목을 verification 문서에 기록해야 한다.

### FR-5. 문서화 및 로컬 재현성
- runbook은 로컬 재현 명령, 산출물 위치, 민감정보 금지 목록, fallback 조건을 포함해야 한다.
- `docs/runtime-flows.md`, `docs/project-structure.md`, `docs/interface-contract.md`는 browser evidence 흐름과 기준을 반영해야 한다.

## 4. Acceptance Criteria

- AC-1: `scripts/streamlit_browser_evidence.py`가 synthetic fixture DB를 생성하고 운영 DB 기본 경로 사용을 거부한다.
- AC-2: `python3 -m py_compile scripts/streamlit_browser_evidence.py dashboard/app.py`가 통과한다.
- AC-3: `pytest -q`가 통과한다.
- AC-4: `.venv/bin/python scripts/streamlit_browser_evidence.py` 실행으로 `분류 규칙`, `확인필요 큐`, `Import` 페이지의 PNG screenshot과 DOM snapshot, manifest JSON이 생성된다.
- AC-5: manifest의 모든 page entry는 `screenshot_bytes > 0`, `snapshot_bytes > 0`이며 DOM snapshot에 해당 page 제목이 포함된다.
- AC-6: dashboard Import page의 import history/rollback 조회는 evidence fixture DB의 `db_path`를 사용하며 운영 DB로 누수되지 않는다.
- AC-7: runtime/interface/project-structure/runbook 문서가 evidence 등급과 UI/non-UI/docs-only gate 규칙을 설명한다.

## 5. 구현 메모

- 현재 1차 구현은 Chrome DevTools Protocol을 직접 사용한다. Streamlit dashboard extra에 포함된 `websockets` 패키지를 사용하며 별도 browser automation dependency를 추가하지 않는다.
- Playwright Python은 후속 CI 통합 후보로 남긴다.
- evidence 파일은 기본적으로 `docs/batches/bat-004_20260629_browser-streamlit-e2e-evidence/evidence/run-YYYYMMDD-HHMMSS/`에 생성된다.