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/에 생성된다.

4.9 KiB Raw Blame History