gitea-impl-agent/jarca-ledger-mcp
1
0
Fork 0
forked from jsfamily/jarca-ledger-mcp
Code Pull Requests Activity
Files
7c50298c4e4a8167a18e7e07465a8ed109c8e5c1
jarca-ledger-mcp/docs/discovery/dcy-004_20260629_browser-streamlit-e2e-evidence-recovery.md
T

21 KiB
Raw Blame History

0. 문서 상태

이 문서의 현재 상태와 식별 정보를 기록한다. 문서 추적과 승인 흐름에 필요한 최소 메타데이터를 적는다.

  • 상태: confirmed
  • 문서 ID: dcy-004_20260629_browser-streamlit-e2e-evidence-recovery
  • 이슈명: Browser/Streamlit E2E evidence 환경 복구 및 QC evidence 기준 강화
  • 작성 시각(KST): 2026-06-29 13:29
  • 마지막 갱신 시각(KST): 2026-06-30 13:32
  • 대체됨: 없음
  • 후속 Discovery 참조: docs/discovery/dcy-006_20260630_pytest-apptest-smoke-ci-automation.md
  • 생성된 REQ 참조: REQ-004 (docs/srs/Testing/req-004_browser-streamlit-e2e-evidence-recovery.md)

1. 계획 상태 요약

현재 Discovery가 어떤 배경에서 작성되고 있는지, 연계 문서가 있는지, 지금 시점의 해석이 무엇인지 짧게 요약한다.

  • 연계 문서 현황:
    • 관련 GitHub Project 항목: https://github.com/users/genichin/projects/4 DraftIssue (Browser/Streamlit E2E evidence 환경 복구)
    • 관련 TODO/메모: docs/batches/bat-001_20260626_category-rule-ops/verification.md의 "Future Streamlit UX/E2E batches should restore real browser/screenshot evidence" 메모
  • 해석:
    • dcy-001(Streamlit UX/E2E 안정화)부터 bat-001 검증까지, browser-level screenshot 증거는 로컬 Chromium snap 부재로 한 번도 확보되지 못했고 AppTest + HTTP 200 smoke가 대체 증거로 누적 사용되어 왔다.
    • 이번 Discovery는 특정 기능 추가가 아니라 검증 인프라 복구를 독립 주기로 다룬다. 즉 Chromium/screenshot 기반 browser-level Streamlit E2E 증거 수집 환경을 복구하고, 검수관 QC gate가 요구하는 evidence 기준을 강화하는 것을 목표로 한다.

2. 요구사항 판정 결과

이번 요청이 기존 요구사항과 비교해 신규인지, 유사한지, 중복인지 판단하고 그 근거를 남긴다.

  • 판정: 신규
  • 근거
    • dcy-001은 Streamlit UX/E2E 워크플로우 자체의 acceptance criteria 정의가 중심이며, "browser 증거를 어떻게 확보·표준화할지"라는 검증 환경/QC 기준 문제를 독립 성공 기준으로 다루지 않았다. 해당 Discovery에서 OQ-1(수동 체크리스트 vs Playwright/Selenium 자동화)도 미해결로 남아 있었다.
    • bat-001 verification과 req-001 QC note는 browser screenshot 부재를 반복적으로 PASS_WITH_NOTES의 잔여 항목으로 기록했을 뿐, 환경 복구를 후속 작업으로 정식 추적하지 않았다. 이를 독립 주기로 끌어올려 추적하는 것이 책임 경계상 명확하다.

3. 문제점의 요약

문제의 현재 상태, 기대 상태, 관련 이해관계자, 제약사항을 정리한다. Discovery의 핵심 맥락을 가장 먼저 이해할 수 있어야 한다.

  • 현재 상태
    • browser 증거 수집이 차단되어 있다: bat-001 구현/검증 기록에 따르면 /usr/bin/chromium-browser가 미설치 chromium snap을 요구해 Chrome exited early ... requires the chromium snap to be installed로 실패했고, browser tool은 페이지 로드 전에 종료되었다.
    • 대체 증거가 표준처럼 굳어졌다: streamlit.testing.v1.AppTest와 포트 8502 HTTP 200 smoke(synthetic fixture DB /tmp/jarca-ledger-bat-001-smoke.sqlite3)가 browser screenshot 대신 반복 사용되었다(bat-001/implementation.md, bat-001/verification.md).
    • QC gate가 이를 허용해 왔다: req-001의 QC note는 PASS_WITH_NOTES로 통과하되 "browser screenshot unavailable due Chromium snap absence; future batches should restore real browser/screenshot evidence"를 잔여 항목으로 남겼다. 즉 evidence 등급에 대한 명시적 기준·게이트 규칙이 문서화되어 있지 않다.
    • baseline 문서들도 이 gap을 인지하고 있다: docs/project-structure.md("Final UX verification is still needed ... import E2E flows"), docs/runtime-flows.md("Need final browser-level UX verification ..."), docs/interface-contract.md("Browser-level UI acceptance criteria for Streamlit flows are not yet captured as REQ documents")가 모두 browser-level 검증 미비를 기록한다.
  • 기대 상태
    • 운영자/검수관이 로컬 또는 CI 환경에서 Chromium을 재현 가능하게 기동하여 Streamlit 주요 화면(분류 규칙, 확인필요 큐, import preview, 잔액대조 결과 등)의 browser-level screenshot 증거를 안정적으로 수집할 수 있다.
    • evidence 등급(예: browser-screenshot E2E > AppTest semi-auto > HTTP 200 smoke)이 명시적으로 정의되고, 어떤 종류의 batch에 어떤 최소 증거가 필요한지 QC gate 규칙으로 문서화된다.
    • "Chromium 부재 → 대체 증거 허용"이 무기한 기본값이 아니라, 환경 복구 후에는 browser 증거가 1순위 기준이 되도록 QC evidence 기준이 강화된다.
  • 이해관계자
    • 렛저장인(운영자 겸 작성자) — Streamlit E2E 검증 실행 및 증거 수집 주체
    • 검수관/리뷰어 — QC gate에서 evidence 등급과 충족 여부를 판정하는 주체
    • StagePilot 후속 SDLC(REQ/Batch) 수행자 — 본 Discovery를 검증 환경 요구사항으로 정제
  • 제약사항
    • 실행 환경(snap 사용 가능 여부, 컨테이너/CI 권한, 헤드리스 가능 여부)이 고정적이지 않아 단일 설치 방식을 강제하기 어렵다.
    • 개인 금융정보를 다루므로 screenshot 증거에는 실계좌번호·잔액 등 민감정보가 노출되지 않도록 synthetic fixture 또는 마스킹을 전제로 한다.
    • 운영 DB 훼손을 피하기 위해 E2E는 fixture/복사본 DB에서 수행하며, dcy-002 백업·검증 DB 절차를 전제로 한다.

주요 사용자 시나리오

사용자 또는 운영자가 실제로 어떤 상황에서 이 변경을 필요로 하는지 대표 시나리오를 적는다.

  • 검수관이 새 Streamlit UX batch를 QC 검수할 때, AppTest 대체 증거가 아니라 실제 browser screenshot으로 화면 렌더링·버튼 동작을 확인하고 evidence를 첨부한다.
  • 운영자가 분류 규칙/확인필요 큐 화면 변경을 검증할 때, fixture DB로 Streamlit을 기동하고 headless Chromium으로 주요 플로우를 스크린샷 캡처하여 재현 가능한 증거 디렉터리에 저장한다.
  • 검수관이 browser 증거를 확보할 수 없는 환경에 한해, 정의된 evidence 등급 규칙에 따라 명시적으로 대체 증거(AppTest+HTTP 200)를 PASS_WITH_NOTES로만 허용하고 잔여 항목을 추적한다.

4. 이번에 정의할 변경

이번 Discovery에서 다루는 핵심 변경 항목을 목록으로 적는다. 기능, 구조, 규칙 변경을 함께 포함해도 된다.

  • Chromium/screenshot 기반 browser-level Streamlit E2E 증거 수집 환경을 복구한다. 즉 미설치 chromium snap에 의존하지 않고 재현 가능한 방식으로 headless Chromium을 기동하는 표준 절차를 정의한다.
  • browser E2E 증거 수집을 자동화 가능한 smoke/E2E 절차(예: fixture DB로 Streamlit 기동 → 주요 화면 스크린샷 캡처 → 증거 디렉터리 저장)로 표준화한다.
  • QC evidence 등급과 게이트 규칙을 강화한다: browser-screenshot E2E를 1순위 증거로 두고, AppTest/HTTP 200 대체 증거는 환경 제약이 입증된 경우에만 PASS_WITH_NOTES로 허용하는 기준을 문서화한다.
  • 검증 환경·증거 절차를 docs/runtime-flows.md(검증 흐름)와 docs/project-structure.md(테스트/증거 도구 구조), 그리고 검증 runbook 후보에 반영할 필요를 명시한다.

영향 범위

변경이 미칠 코드/문서/운영 범위를 명시해 REQ 정제와 batch planning에서 추정 누락을 줄인다.

  • 코드 영향:
    • tests/ — Streamlit E2E/browser smoke 스크립트(헤드리스 Chromium 기동, 스크린샷 캡처)와 fixture DB 준비 유틸리티 신설 가능성. 기존 streamlit.testing.v1.AppTest smoke는 보존하되 보조 증거로 재배치.
    • 검증 보조 스크립트/실행 래퍼 — Chromium 기동·screenshot 저장 경로·증거 수집을 재현 가능하게 묶는 진입점(코드 위치는 REQ/Batch에서 확정).
    • dashboard/app.py — 원칙적으로 기능 변경 없음. E2E 안정화를 위한 최소 테스트 훅(예: 결정적 렌더링)이 필요할 경우에 한해 후속 범위로 검토.
  • 문서 영향:
    • docs/runtime-flows.md — browser-level Streamlit E2E 검증 흐름과 증거 수집 단계 추가.
    • docs/project-structure.md — 테스트/증거 도구(헤드리스 Chromium, E2E 스크립트, 증거 디렉터리) 구조 반영 및 기존 "browser-level verification still needed" 항목 갱신.
    • docs/interface-contract.md — browser-level UI acceptance/evidence 기준의 REQ화 필요성 반영 검토.
    • docs/runbooks/ — Streamlit E2E 증거 수집 운영 runbook 신규 후보.
  • 운영 영향:
    • QC gate 운영 기준이 강화되어, browser 증거 가능 환경에서는 대체 증거만으로 PASS를 허용하지 않는 운영 규칙이 신설된다.
    • E2E는 synthetic fixture 또는 dcy-002 검증 DB 복사본에서 수행하는 운영 루틴이 추가된다.

5. 요구사항 목록

실제로 구현과 검증으로 이어질 요구사항을 기능/비기능으로 나누어 정리하고, 범위 경계를 명확히 적는다.

기능 요구사항

  • FR-1: 미설치 chromium snap에 의존하지 않고 재현 가능하게 headless Chromium을 기동할 수 있는 표준 실행 절차를 제공해야 한다. 실행 환경이 Chromium을 제공하지 못하는 경우 명확한 진단 메시지와 함께 대체 증거 경로로 안내해야 한다.
  • FR-2: fixture DB로 Streamlit을 기동하고 주요 화면(최소: 분류 규칙, 확인필요 큐, import preview)을 browser-level로 렌더링해 스크린샷 증거를 정해진 증거 디렉터리에 저장하는 E2E/smoke 절차를 제공해야 한다.
  • FR-3: QC evidence 등급을 정의하고(예: browser-screenshot E2E > AppTest semi-auto > HTTP 200/service smoke), 각 batch 유형에 필요한 최소 증거와 게이트 결과(PASS/PASS_WITH_NOTES) 규칙을 문서화해야 한다.
  • FR-4: browser 증거 수집이 환경적으로 불가능한 경우에만 대체 증거를 허용하며, 그 사유와 잔여 항목을 검증 문서에 명시적으로 기록하도록 강제해야 한다.
  • FR-5: 검증 환경·증거 절차를 docs/runtime-flows.md와 docs/project-structure.md에 반영하고, Streamlit E2E 증거 수집 runbook을 docs/runbooks/ 후보로 추가해야 한다.

비기능 요구사항

성능, 운영성, 일관성, 자동화 안정성 등 기능 외 요구사항을 적는다.

  • NFR-1: E2E 증거 수집은 재현 가능해야 하며, 동일 fixture·동일 절차에 대해 동일한 화면 증거를 산출할 수 있어야 한다(결정적 fixture, 고정 포트/경로 규칙).
  • NFR-2: 모든 E2E 검증은 synthetic fixture 또는 dcy-002 검증 DB 복사본에서 수행하여 원본 운영 DB를 훼손하지 않아야 하며, 스크린샷에 실계좌번호·잔액 등 민감정보가 평문으로 노출되지 않아야 한다.
  • NFR-3: 환경 의존성(Chromium 설치 방식)은 단일 물리 방식에 고정하지 않고 실행 환경별로 해석 가능한 절차로 문서화하여, snap 부재 같은 단일 실패 지점에 다시 갇히지 않아야 한다.

범위 경계

이번 반복에서 반드시 포함할 범위와 명시적으로 제외할 범위를 구분한다.

  • In Scope
    • headless Chromium 기동 표준 절차 복구와 browser-level Streamlit 스크린샷 증거 수집 절차 정의
    • QC evidence 등급·게이트 규칙 정의 및 문서화(강화된 evidence 기준)
    • 검증 흐름/도구 구조의 docs/runtime-flows.md·docs/project-structure.md 반영과 검증 runbook 후보 추가
  • Out of Scope
    • Streamlit 기능/화면 자체의 신규 기능 추가나 UX 재설계(기존 화면 검증이 목적이며 기능 변경 아님)
    • full CI/CD 파이프라인 신설 및 외부 호스팅 도입. CI 통합은 Project #4의 pytest/AppTest/Smoke CI 자동화 항목으로 분리하고, 이번 반복은 로컬 재현 절차까지만 포함
    • 시각 회귀(pixel-diff) 자동 비교 등 고도화된 visual regression. 이번 반복은 증거 캡처·저장·등급화까지로 한정

6. 리스크/가정 목록

불확실성과 전제 조건을 분리해서 적는다. 리스크는 영향과 완화 방안을, 가정은 현재 판단의 전제를 기록한다.

리스크

  • R-1 (High): 실행 환경이 여전히 Chromium 설치를 제약하면(snap 전용, 권한 부족 등) 환경 복구 자체가 차단되어 이번 반복 목표가 미달성될 수 있다.
    • 완화 방안: 현재 설치된 /usr/bin/google-chrome-stable 149.0.7827.200을 1차 runtime으로 사용하고, snap 기반 chromium-browser는 표준 경로에서 제외한다. 실패 시 진단·대체 증거 경로를 명확히 남긴다.
  • R-2 (Medium): Streamlit 화면이 비결정적으로 렌더링되면(비동기 로딩, 동적 데이터) 스크린샷 증거가 불안정해져 재현성이 깨진다.
    • 완화 방안: 결정적 fixture DB와 로드 완료 대기 조건을 표준화하고, 캡처 전 안정화 단계를 절차에 포함한다.
  • R-3 (Medium): evidence 기준을 과도하게 강화하면 Chromium 불가 환경에서 정당한 batch까지 게이트에 막힐 수 있다.
    • 완화 방안: "환경 제약이 입증된 경우 PASS_WITH_NOTES 허용 + 잔여 항목 추적"의 예외 경로를 규칙에 명시해 강화와 운영 현실성을 양립시킨다.

가정

아직 확정되지 않았지만 현재 문서 작성의 기반이 되는 전제를 적는다.

  • A-1: 실패 원인은 Streamlit/대시보드 코드 결함이 아니라 Chromium 실행 환경 부재이며, 환경 확보 시 기존 AppTest로 통과하던 화면은 browser-level로도 검증 가능하다.
  • A-2: 기존 streamlit.testing.v1.AppTest smoke와 포트 8502 HTTP 200 패턴, synthetic fixture DB 방식을 browser E2E의 보조 증거 및 기동 토대로 재사용할 수 있다.
  • A-3: E2E 검증은 dcy-002의 백업·검증 DB 절차가 운영 가능한 상태임을 전제로 fixture/복사본 DB에서 수행한다.

오픈 질문

답을 아직 모르는 항목을 적는다. 추정으로 덮지 말고 REQ 초안 작성 이전에 확인할 질문으로 남긴다.

  • OQ-1: browser 자동화 도구로 무엇을 표준화할 것인가(Playwright / Selenium / 번들 Chromium + CDP 등)? dcy-001 OQ-1의 미해결 결정을 이번 주기로 인계한다.
    • 상태: Answered
    • 처리 방안: 1차 표준은 Hermes browser tool과 현재 설치된 /usr/bin/google-chrome-stable을 사용한 로컬 browser evidence 절차로 한다. Playwright Python은 후속 CI 자동화 후보로 두고, Streamlit AppTest + HTTP 200 smoke는 fallback evidence로 사용한다. snap 기반 chromium-browser는 표준 경로에서 제외한다.
    • 종료 조건: REQ에 Hermes browser/Google Chrome 기반 1차 절차, Playwright 후속 후보, AppTest/HTTP fallback, snap chromium 제외 원칙이 반영되면 Answered
  • OQ-2: 강화된 QC evidence 기준에서 browser-screenshot 증거를 어떤 batch 유형에 "필수(blocker)"로 둘지, 어디까지 PASS_WITH_NOTES 예외를 허용할지?
    • 상태: Answered
    • 처리 방안: Streamlit UI 또는 dashboard/app.py에 영향을 주는 batch는 browser screenshot/snapshot evidence를 필수로 한다. 비-UI batch는 browser evidence를 선택으로 두고, docs-only batch는 불필요로 한다. 환경 장애가 명확하면 AppTest + HTTP 200 fallback evidence와 실패 사유를 남기는 조건으로 PASS_WITH_NOTES를 허용한다.
    • 종료 조건: REQ의 QC gate 규칙에 UI/non-UI/docs-only 유형별 최소 증거와 PASS_WITH_NOTES 예외 조건이 반영되면 Answered

7. 초기 성공 기준

이 변경이 성공했다고 판단할 기준을 측정 가능하게 정의한다. 가능하면 데이터 출처까지 연결한다.

  • S-1: 재현 가능한 표준 절차로 headless Chromium을 기동해 Streamlit 주요 화면(최소 분류 규칙, 확인필요 큐, import preview) 중 1개 이상에서 실제 browser-level screenshot 증거를 확보한다.
  • S-2: QC evidence 등급과 batch 유형별 최소 증거·게이트 규칙이 문서로 정의되어, 검수관이 동일 기준으로 PASS/PASS_WITH_NOTES를 판정할 수 있다.
  • S-3: 검증 환경·증거 절차가 docs/runtime-flows.md와 docs/project-structure.md에 반영되고, Streamlit E2E 증거 수집 runbook 후보가 추가되어 후속 REQ/Batch에서 참조 가능하다.

측정 방식 및 데이터 출처

각 성공 기준을 어떻게 측정할지와 어떤 데이터나 문서를 근거로 쓸지 적는다.

  • S-1 측정 방식: fixture DB로 기동한 Streamlit 화면의 스크린샷 파일이 증거 디렉터리에 생성되었는지와 절차 재실행 시 동일 증거가 재현되는지 확인 / 데이터 출처: E2E 스크립트 실행 로그, 저장된 screenshot 증거 파일, fixture DB
  • S-2 측정 방식: evidence 등급·게이트 규칙 문서의 존재와, 동일 batch에 대해 검수관 판정이 규칙과 일치하는지 리뷰 / 데이터 출처: 신규 QC evidence 기준 문서, batch verification 문서의 evidence 등급 기록
  • S-3 측정 방식: 문서 존재 및 검증 흐름·도구 구조 반영 여부 리뷰 / 데이터 출처: docs/runtime-flows.md, docs/project-structure.md, docs/runbooks/

8. REQ로 넘기기 전 확인 체크

REQ 초안 작성 단계로 넘기기 전에 무엇이 확정되어야 하는지 확인한다. 미완료 항목은 후속 결정이 필요함을 뜻한다.

  • 범위(In Scope/Out of Scope) 확정
    • 기준: 이번 반복은 로컬 재현 가능한 browser evidence 복구와 증거 등급화까지로 한정한다. CI 통합은 Project #4의 pytest/AppTest/Smoke CI 자동화 항목으로 분리하고, visual regression은 제외한다.
  • 성공 지표의 측정 방식/데이터 출처 확정
    • 기준: Hermes browser/Google Chrome 기반 screenshot/snapshot evidence, console 확인, Streamlit 서버 로그, AppTest+HTTP fallback이 REQ acceptance criteria에 반영된다.
  • High 영향 리스크 우선순위 및 해소 책임자 지정
    • 기준: R-1(Chromium 확보 불가)은 현재 설치된 /usr/bin/google-chrome-stable을 1차 runtime으로 사용하고, 렛저장인이 로컬 evidence 절차를 구현·검증한다.
  • 모든 오픈 질문(OQ) Open 상태 없음 확인
    • 기준: OQ-1(도구 표준화), OQ-2(게이트 정책)가 Answered 처리됨.
  • Freeze 확정 담당자(CONFIRMED_BY) 지정
    • 기준: 사용자 진환 고가 권장안을 승인하고 다음 과정 진행을 지시했다.

9. 파일 처리 결과

이 Discovery 문서 생성/갱신 결과와 참조 문서를 기록한다. 이후 추적과 리뷰 시 근거로 사용한다.

  • 처리 결과: 생성
  • 생성 경로: docs/discovery/dcy-004_20260629_browser-streamlit-e2e-evidence-recovery.md
  • 참조 문서:
    • docs/discovery/dcy-001_20260626_streamlit-ux-e2e-categorization-refund-workflows.md
    • docs/batches/bat-001_20260626_category-rule-ops/verification.md
    • docs/runtime-flows.md
    • docs/project-structure.md

10. 사용자 결정 필요 항목 요약

사용자나 승인자가 결정해야 하는 항목만 모아 정리한다. 결정, 확인, 데이터 요청을 구분해서 적는다.

DECIDE

  • E2E 1차 표준은 Hermes browser tool과 설치된 /usr/bin/google-chrome-stable 기반 로컬 browser evidence 절차로 한다. Playwright Python은 후속 CI 자동화 후보로 두고, Streamlit AppTest + HTTP 200 smoke는 fallback evidence로 사용한다.
  • Streamlit UI 또는 dashboard/app.py 영향 batch는 browser screenshot/snapshot evidence를 필수로 한다. 비-UI batch는 선택, docs-only batch는 불필요로 한다. 환경 장애가 명확하면 AppTest + HTTP 200 fallback과 실패 사유를 남기는 조건으로 PASS_WITH_NOTES를 허용한다.
  • 이번 dcy-004는 로컬 재현 가능한 browser evidence 복구까지로 한정한다. CI 파이프라인 통합은 Project #4의 pytest/AppTest/Smoke CI 자동화 항목에서 별도 처리한다.

CONFIRM

  • Chromium/Chrome runtime은 현재 설치된 /usr/bin/google-chrome-stable 149.0.7827.200을 1차 runtime으로 사용한다. snap 기반 chromium-browser는 표준 경로에서 제외한다.

DATA

  • browser E2E는 운영 DB가 아니라 synthetic/validation DB를 사용한다. 계좌번호, 실제 거래처, raw_payload, 원본 파일명, 비밀번호는 screenshot/log에 노출하지 않고 가짜 값 또는 공란으로 둔다.

11. Discovery Freeze

REQ 초안 작성 인계 시점의 확정 플래그와 섹션 참조만 기록한다. 내용 재작성 없이 원본 섹션을 링크로 대신한다.

섹션 참조

Freeze 플래그

  • Handoff Decision: 승인
  • Handoff Rationale: 사용자 승인으로 E2E 도구 표준, evidence gate 정책, CI 범위, Chrome runtime, fixture/마스킹 원칙이 확정되었으므로 REQ 초안 작성으로 넘긴다.
  • Ready for REQ Drafting: true
  • Confirmed By: 진환 고
  • Confirmed At (KST): 2026-06-29 13:49
View Git Blame Copy Permalink