chore(jarca-ledger): finalize approved batch docs, dashboard, and CI smoke updates

2026-06-30 16:06:47 +09:00
parent 67d8d4871b
commit 4929e52189
75 changed files with 8367 additions and 252 deletions
@@ -0,0 +1,80 @@
+# REQ-003 Statement-unavailable 계좌 수동 증빙 및 잔액대조
+
+- Status: Implemented
+- Type: Interface
+- Priority: High
+- Owner: 렛저장인
+- Source Discovery: `docs/discovery/dcy-003_20260629_statement-unavailable-manual-evidence-balance-reconciliation.md`
+- Batch: `docs/batches/bat-003_20260629_statement-unavailable-reconciliation/`
+- Created At (KST): 2026-06-29
+- Implemented At (KST): 2026-06-29
+
+## 1. 배경
+
+거래내역 파일이 없거나 일부 기간만 import 가능한 계좌는 기존 statement import 흐름만으로 정합성을 보장할 수 없다. dcy-003 confirmed Discovery에 따라 계좌별 statement 지원 상태를 명시하고, 수동 실행 가능한 잔액대조 report 및 계좌 화면의 최소 UI를 제공한다.
+
+## 2. 범위
+
+### In Scope
+- `accounts.statement_status` 필드 추가 및 서비스 검증.
+- 허용값: `unknown`, `import_supported`, `manual_only`, `partial_import`.
+- `manual_only`는 statement-unavailable 계좌로 정의한다.
+- `partial_import`도 수동 보완 및 잔액대조 대상에 포함한다.
+- 기준 잔액 입력 포맷: `account_id`, `statement_status`, `baseline_balance`, `baseline_at`, `source_note`, `memo`.
+- 수동 실행 잔액대조 report: 계산 잔액, 차액, 허용 오차, 0.1% 참고 비율, `OK`/`REVIEW_NEEDED`/`BASELINE_REQUIRED` 상태.
+- 계좌 화면의 `statement_status` 표시/수정 및 최소 잔액대조 결과 표시.
+- MCP tool surface에 계좌 update 및 잔액대조 report를 additive로 노출.
+- dcy-002 백업/검증 DB 절차 선행 원칙 문서화.
+
+### Out of Scope
+- 자동 스케줄링/알림.
+- 전용 잔액대조 워크벤치 전체 신설.
+- 사용자 승인 없는 restore 실행 또는 restore MCP tool 노출.
+- 자동 확정형 확인필요 라우팅 mutation. 이번 구현은 preview/report 중심이며 수동 확정을 전제로 한다.
+
+## 3. 기능 요구사항
+
+### FR-1. 계좌 statement 상태
+- `accounts.statement_status`는 `TEXT NOT NULL DEFAULT 'unknown'`이어야 한다.
+- 서비스 계층은 허용값 외 입력을 `validation_error`로 거부해야 한다.
+- `create_ledger_account`, `list_ledger_accounts`, `update_ledger_account`에서 해당 필드를 사용할 수 있어야 한다.
+
+### FR-2. 잔액대조 입력 및 기준 시각
+- 잔액대조 입력은 다음 포맷을 지원해야 한다.
+  - `account_id`: 선택. 비어 있으면 `manual_only`, `partial_import` 활성 계좌 전체를 대상으로 한다.
+  - `baseline_balance`: 선택. 없으면 계좌의 `last_balance`를 사용한다.
+  - `baseline_at`: 선택. `YYYY-MM`이면 해당 월 말일 `23:59:00+09:00`, `YYYY-MM-DD`이면 해당일 `23:59:00+09:00`, ISO datetime이면 원문 기준으로 정규화 검증한다.
+  - `source_note`, `memo`: 선택 메타데이터. 원문 증빙이나 민감 식별자는 저장·출력하지 않는다.
+- 정기 대조 기준은 매월 말일 23:59 KST이며, 수시 대조는 사용자 입력 스냅샷 시각을 사용한다.
+
+### FR-3. 잔액대조 판정
+- 계산 잔액은 우선 `transactions.balance_after`의 최신 값을 사용하고, 없으면 기준 시점까지의 계좌 거래 순증감을 사용한다.
+- 차액은 `baseline_balance - calculated_balance`로 산출한다.
+- 초기 허용 오차는 절대 금액 1,000원이다.
+- `abs(difference) <= 1000`이면 `OK`, 초과하면 `REVIEW_NEEDED`로 표시한다.
+- 기준 잔액 대비 0.1%는 `difference_ratio`와 `reference_ratio_threshold=0.001`로 참고 표시만 하고 판정에는 사용하지 않는다.
+
+### FR-4. 확인필요 후보 판정값
+- `REVIEW_NEEDED` 결과는 다음 수동 판정 후보를 제시해야 한다: `계좌이동`, `실지출`, `실수입`, `투자이동`, `분석제외`, `확인필요`.
+- 자동 확정이 아닌 후보 제시/수동 확정을 기본으로 한다.
+
+### FR-5. 운영 안전
+- 운영 DB 변경 전 dcy-002 백업은 필수다.
+- 검증 DB에서 preview/reconcile을 먼저 수행한다.
+- restore는 사용자 명시 승인 없이 실행하지 않는다.
+
+## 4. Acceptance Criteria
+
+- AC-1: 새 DB 및 기존 DB migration 후 `accounts.statement_status`가 존재하고 기본값은 `unknown`이다.
+- AC-2: 잘못된 `statement_status`로 계좌 생성/수정 시 `validation_error`가 반환된다.
+- AC-3: `manual_only` 또는 `partial_import` 계좌에 대해 잔액대조 report가 `baseline_balance`, `calculated_balance`, `difference`, `tolerance=1000`, `difference_ratio`, `status`를 반환한다.
+- AC-4: 차액이 1,000원 이내면 `OK`, 초과면 `REVIEW_NEEDED`이며 확인필요 후보 판정값 6개가 표시된다.
+- AC-5: dashboard 계좌 화면에서 `statement_status`를 확인/수정하고 최소 잔액대조 report를 실행할 수 있다.
+- AC-6: MCP tool로 `update_ledger_account`, `get_balance_reconciliation_report`가 additive 노출된다.
+- AC-7: data model, interface contract, runtime flow, runbook 문서가 dcy-003 범위를 반영한다.
+
+## 5. 구현 메모
+
+- Schema version은 `7`로 올린다.
+- 잔액대조는 현재 preview/report만 수행하며 transaction/category mutation은 하지 않는다.
+- 대조 기준 잔액 실제 값은 운영 시점에 사용자가 입력한다.
@@ -0,0 +1,93 @@
+# REQ-005 Dashboard operations hub/liquidity/monthly cashflow
+
+- Status: Approved
+- Type: Interface
+- Priority: High
+- Owner: 렛저장인
+- Source Discovery: `docs/discovery/dcy-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow.md`
+- Batch: BAT-005
+- Created At (KST): 2026-06-29
+- Approved At (KST): 2026-06-29 21:08 KST
+
+## 1. 배경
+
+현재 Streamlit 대시보드 첫 화면은 전체 기간 누적 현금흐름과 계좌 입출금 중심으로 구성되어 있어, 운영자가 월중에 필요한 "이번 달 수입/지출 현황", "현재 자산 유동성", "미처리 운영 경고"를 한 화면에서 즉시 판단하기 어렵다. dcy-005 confirmed Discovery에 따라 대시보드 첫 화면을 운영 허브로 재정의하고, 계좌 단위 `liquidity_bucket` 축을 도입해 자산 유동성/구성/순자산 계산을 일관되게 제공한다.
+
+## 2. 범위
+
+### In Scope
+- `page_overview`를 다음 우선순위 섹션으로 재구성한다: ① 이번 달 수입/지출 현황 ② 자산 유동성 현황 ③ 자산 구성 ④ 지출 구조/예산 ⑤ 운영 경고.
+- 이번 달 수입/지출 현황은 KST 현재 월의 `transaction_date` 기준으로 실제 수입, 실제 지출, 순현금흐름, 저축률을 표시한다.
+- 자산 유동성 현황은 계좌 단위 `accounts.liquidity_bucket` 값을 기준으로 `cash`, `investment`, `deposit`, `real_estate`, `loan`, `other` 버킷별 금액과 비율을 표시한다.
+- `accounts.liquidity_bucket`은 additive/idempotent schema migration으로 도입하고, 미지정 계좌는 `other`로 폴백한다.
+- 비거래 자산/부채는 초기 구현에서 `ledger_accounts` 항목의 `last_balance`, `last_synced_at`, `memo`를 수동 입력 소스로 사용한다.
+- 운영 경고 섹션은 미분류 거래, 확인필요 큐, 잔액대조 필요 계좌, 최근 백업/import 상태를 한 화면에 노출하고 상세 화면/절차로 이동할 단서를 제공한다.
+- `docs/data-model.md`, `docs/project-structure.md`, `docs/runtime-flows.md`, 필요 시 `docs/interface-contract.md`에 대시보드 운영 허브와 `liquidity_bucket` 흐름을 반영한다.
+
+### Out of Scope
+- 다계좌 실시간 잔액 연동, 외부 시세/투자 평가액 자동 연동.
+- 카드 미결제금, 보험 해지환급금, 자동 시세 연동 자산 반영.
+- `asset_snapshots`, `manual_assets` 같은 별도 자산 평가 테이블 신설.
+- 거래/카테고리 단위 `liquidity_bucket` override.
+- 사용자 정의 회계 월 마감 또는 `posted_date` 기준 월간 현금흐름 전환.
+
+## 3. 기능 요구사항
+
+### FR-1. 이번 달 수입/지출 현황
+- 대시보드 최상단 1순위 섹션은 "이번 달 수입/지출 현황"이어야 한다.
+- 기본 기간은 KST 현재 월의 시작일부터 종료일까지이며, 집계 기준일은 `transactions.transaction_date`다.
+- 실제 수입/지출 판정은 기존 `ledger_categories.cashflow_kind` 기준을 재사용한다.
+- 표시 지표는 실제 수입, 실제 지출, 순현금흐름, 저축률을 포함해야 한다.
+- 저축률은 기존 정의와 동일하게 `순현금흐름 ÷ 실제 수입`을 당월 범위에 적용한다. 실제 수입이 0인 경우에는 나누기 오류 없이 안전한 대체 표시를 제공한다.
+
+### FR-2. 자산 유동성 분류 축
+- `accounts.liquidity_bucket`은 `TEXT NOT NULL DEFAULT 'other'` 성격의 additive 필드로 도입해야 한다.
+- 허용값은 `cash`, `investment`, `deposit`, `real_estate`, `loan`, `other`다.
+- 서비스 계층은 허용값 외 입력을 검증 오류로 거부해야 한다.
+- 계좌 생성, 계좌 목록, 계좌 수정 흐름에서 `liquidity_bucket`을 사용할 수 있어야 한다.
+- 기존 계좌 또는 미지정 계좌는 `other`로 안전하게 폴백해야 한다.
+
+### FR-3. 자산 유동성/구성/순자산 계산
+- 자산 유동성 현황은 `accounts.liquidity_bucket`을 단일 권위 소스로 사용한다.
+- 버킷별 금액은 각 계좌의 최신 `last_balance`를 우선 사용한다. `last_balance`가 없는 계좌는 계산에서 제외하거나 별도 미입력 경고로 표시하되, 임의의 거래 합계로 자산 평가액을 추정하지 않는다.
+- 자산 구성 비율의 분모는 `cash`, `investment`, `deposit`, `real_estate`, `other` 버킷 합계이며, `loan`은 제외한다.
+- 총부채는 `loan` 버킷 합계로 표시하고, 순자산은 대출을 제외한 자산 합계에서 총부채를 차감해 계산한다.
+- 부동산, 예적금, 대출 등 비거래 자산/부채는 `last_balance`를 현재 평가액/잔액, `last_synced_at`을 기준일, `memo`를 출처 메모로 사용한다.
+
+### FR-4. 운영 허브 화면 구성
+- `page_overview`는 다음 순서로 섹션을 배치해야 한다.
+  1. 이번 달 수입/지출 현황
+  2. 자산 유동성 현황
+  3. 자산 구성
+  4. 지출 구조/예산
+  5. 운영 경고
+- 각 섹션은 기준 기간 또는 기준일을 명확히 표시해야 한다.
+- 운영 경고 섹션은 최소한 미분류 거래 건수, 확인필요 큐 상태, 잔액대조 필요 계좌, 최근 백업/import 상태를 표시해야 한다.
+- 운영 경고 항목은 해당 상세 화면 또는 관련 실행 절차로 이동할 수 있는 라벨, 메뉴 안내, 버튼 등 명확한 단서를 제공해야 한다.
+
+### FR-5. 문서 및 기준선 정렬
+- `docs/data-model.md`는 `LedgerAccount`의 `liquidity_bucket`, 비거래 자산 수동 입력 방식, 자산/부채/순자산 계산 규칙을 설명해야 한다.
+- `docs/project-structure.md`는 대시보드 운영 허브와 관련 집계 책임이 `dashboard/app.py` 및 `jarca_ledger_mcp.service`에 걸치는 구조를 반영해야 한다.
+- `docs/runtime-flows.md`는 대시보드 운영 허브 조회 흐름과 KST 현재 월/`transaction_date` 기준, `last_balance` 기반 자산 유동성 집계 흐름을 반영해야 한다.
+- MCP/service/dashboard interface가 변경되면 `docs/interface-contract.md`도 함께 갱신해야 한다.
+
+## 4. Acceptance Criteria
+
+- AC-1: 새 DB 및 기존 DB migration 후 `accounts.liquidity_bucket`이 존재하고 기본값/폴백은 `other`다.
+- AC-2: 잘못된 `liquidity_bucket` 값으로 계좌 생성/수정 시 검증 오류가 반환된다.
+- AC-3: 계좌 생성, 계좌 목록, 계좌 수정 결과에서 `liquidity_bucket`을 확인·설정할 수 있다.
+- AC-4: 대시보드 첫 화면 최상단에 KST 현재 월 `transaction_date` 기준 실제 수입, 실제 지출, 순현금흐름, 저축률이 표시된다.
+- AC-5: 자산 유동성/구성 섹션이 `accounts.liquidity_bucket`과 `last_balance` 기준으로 버킷별 금액, 구성 비율, 총부채, 순자산을 표시한다.
+- AC-6: `loan` 버킷은 자산 구성 비율 분모에서 제외되고 총부채/순자산 계산에만 반영된다.
+- AC-7: `last_balance`가 없는 비거래 자산/부채는 임의 추정하지 않고 미입력 또는 제외 상태가 화면에 명확히 표시된다.
+- AC-8: 운영 경고 섹션이 미분류, 확인필요 큐, 잔액대조 필요, 백업/import 상태를 표시하고 상세 화면/절차 이동 단서를 제공한다.
+- AC-9: `pytest -q`가 통과하고, `dashboard/app.py` 영향 변경이므로 `scripts/streamlit_browser_evidence.py` 기반 screenshot/DOM evidence가 생성된다.
+- AC-10: `docs/data-model.md`, `docs/project-structure.md`, `docs/runtime-flows.md`, 필요 시 `docs/interface-contract.md`가 REQ-005 범위를 반영한다.
+
+## 5. 구현 메모
+
+- Schema version은 후속 batch에서 현재 값보다 1 증가시키고, migration은 additive/idempotent로 작성한다.
+- `liquidity_bucket`의 권위 소스는 계좌 단위로 고정하며 거래/카테고리 override는 이번 범위에서 제외한다.
+- 운영 DB, 원본 금융 파일, 민감정보를 사용하지 않고 synthetic/validation DB에서 대시보드 evidence를 생성한다.
+- dcy-004 QC 결과에 따라 UI 영향 batch는 browser screenshot/snapshot evidence를 필수로 한다.
+- 이 REQ는 구현 기준으로 승인되었으며, 후속 batch에서 구현·검증을 진행한다.
@@ -0,0 +1,72 @@
+# 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/`에 생성된다.
@@ -0,0 +1,88 @@
+# REQ-006 pytest/AppTest/Smoke CI 자동화
+
+- Status: Implemented
+- Type: Testing
+- Priority: High
+- Owner: 렛저장인
+- Source Discovery: `docs/discovery/dcy-006_20260630_pytest-apptest-smoke-ci-automation.md`
+- Batch: BAT-006
+- Created At (KST): 2026-06-30 14:42 KST
+- Approved At (KST): 2026-06-30 14:50 KST
+- Implemented At (KST): 2026-06-30 15:29 KST
+
+## 1. 배경
+
+현재 저장소에는 `pytest` 회귀 스위트, Streamlit `AppTest`, 대시보드 HTTP smoke, DB restore safety smoke 자산이 이미 존재하지만, 이를 `push`/`pull_request`에서 자동 실행해 머지를 차단하는 CI 계약이 없다. 그 결과 회귀 검증은 작성자와 검수관의 수동 로컬 실행에 의존하고, browser evidence 복구(dcy-004)와 dashboard 운영 허브(dcy-005)에서 확보한 검증 자산도 반복 가능한 게이트로 고정되지 못했다. dcy-006 confirmed Discovery에 따라 GitHub Actions 기반 CI를 도입하고, 결정적 synthetic fixture DB를 사용해 `pytest`/`AppTest`/`HTTP smoke`/`DB safety smoke`를 자동 실행하는 표준을 정의한다.
+
+## 2. 범위
+
+### In Scope
+- GitHub Actions 기반 CI workflow를 신설하고 `pull_request`, `main` 대상 `push`, 선택적 `workflow_dispatch` 트리거를 정의한다.
+- 필수 게이트를 `pytest`, Streamlit `AppTest`, 대시보드 HTTP smoke, DB safety smoke로 구성한다.
+- CI에서는 기존 테스트/스크립트 자산의 내부 로직을 재사용하되, 종료코드·인자·로그가 결정적인 얇은 wrapper entrypoint를 표준 진입점으로 사용한다.
+- 모든 CI 검증은 매 실행 시 생성되는 synthetic fixture DB 또는 임시 검증 DB에서 수행하고 운영 DB 접근을 금지한다.
+- `docs/project-structure.md`, `docs/runtime-flows.md`, 필요 시 `docs/runbooks/`를 갱신해 CI 게이트와 로컬 browser evidence(dcy-004) 경계를 문서화한다.
+
+### Out of Scope
+- browser-screenshot/visual regression을 CI 필수 차단 게이트로 승격하는 작업.
+- 배포/릴리스 자동화(CD), 서비스 호스팅, 운영 프로세스 관리.
+- 테스트 커버리지 퍼센트 강제, 성능 벤치마크 게이트, flaky test quarantine 시스템 같은 고도화 품질 체계.
+- 운영 DB 또는 실거래/실계좌 데이터를 CI에 반입하는 작업.
+
+## 3. 기능 요구사항
+
+### FR-1. GitHub Actions CI 진입점
+- 저장소는 GitHub Actions workflow 파일을 제공해야 한다.
+- 기본 트리거는 `pull_request`와 `main` 대상 `push`여야 하며, `workflow_dispatch`는 선택적 수동 재실행 경로로 허용해야 한다.
+- 필수 검증 job 실패 시 workflow 전체가 실패해야 하며, PR 병합 차단 근거로 사용할 수 있어야 한다.
+
+### FR-2. pytest 회귀 게이트
+- CI는 저장소의 표준 pytest 회귀 스위트를 자동 실행해야 한다.
+- 실행 진입점은 로컬과 CI에서 동일한 의미를 가지도록 표준 명령 또는 wrapper로 고정해야 한다.
+- 실패 결과는 어떤 테스트가 실패했는지 식별 가능한 형태로 로그에 남겨야 한다.
+
+### FR-3. Streamlit AppTest + HTTP smoke 게이트
+- CI는 `tests/test_dashboard_app.py` 계열 Streamlit `AppTest`를 synthetic fixture DB로 자동 실행해야 한다.
+- CI는 대시보드 HTTP smoke를 별도 job 또는 동일 단계에서 수행해, Streamlit 서버가 fixture DB 기준으로 기동되고 HTTP 200 응답을 반환하는지 확인해야 한다.
+- HTTP smoke는 고정 또는 결정적으로 할당되는 포트, readiness 대기, timeout/정리 정책을 포함해야 한다.
+
+### FR-4. DB safety smoke 게이트
+- CI는 `scripts/ledger_restore_smoke.py` 계열 DB safety smoke를 임시 fixture/검증 DB에서 자동 실행해야 한다.
+- smoke는 운영 DB 기본 경로를 사용하지 않아야 하며, overwrite/restore 위험 동작은 명시적으로 차단되어야 한다.
+- smoke 실패 시 복구/검증 절차가 어떤 단계에서 실패했는지 로그로 식별 가능해야 한다.
+
+### FR-5. CI 전용 wrapper entrypoint
+- HTTP smoke와 DB safety smoke는 기존 `scripts/`·테스트 자산의 내부 로직을 재사용하되, CI에서는 종료코드·입력 인자·출력 로그가 결정적인 얇은 wrapper entrypoint를 표준으로 사용해야 한다.
+- wrapper는 fixture 준비, 환경 변수 설정, readiness polling, timeout, 종료 후 정리를 일관되게 수행해야 한다.
+- wrapper는 민감정보가 섞일 수 있는 환경 변수/경로/데이터를 그대로 로그에 출력하지 않아야 한다.
+
+### FR-6. CI 게이트와 browser evidence 경계
+- CI 필수 게이트는 `pytest`, `Streamlit AppTest`, `HTTP smoke`, `DB safety smoke`로 한정해야 한다.
+- browser-screenshot E2E는 dcy-004의 로컬 보강 evidence 절차로 유지하고, CI 필수 차단 게이트에 포함하지 않아야 한다.
+- 문서에는 어떤 변경이 CI 필수 게이트만으로 충분한지, 어떤 경우에 로컬 browser evidence를 추가해야 하는지 경계를 설명해야 한다.
+
+### FR-7. 기준선 문서 정렬
+- `docs/project-structure.md`는 CI workflow와 관련 스크립트/wrapper 책임을 반영해야 한다.
+- `docs/runtime-flows.md`는 PR/push → CI jobs → gate result 흐름과 synthetic fixture DB 원칙을 반영해야 한다.
+- 필요 시 `docs/runbooks/`에 CI 실패 시 로컬 재현 절차 또는 smoke 실행 절차를 추가해야 한다.
+
+## 4. Acceptance Criteria
+
+- AC-1: `.github/workflows/` 아래에 GitHub Actions workflow가 생성되고, `pull_request`, `main` 대상 `push`, `workflow_dispatch` 트리거가 정의된다.
+- AC-2: CI에서 pytest 회귀 스위트가 자동 실행되고, 단일 테스트 실패 시 workflow가 실패 상태로 종료된다.
+- AC-3: CI에서 Streamlit `AppTest`가 synthetic fixture DB 기준으로 자동 실행되고 통과/실패 결과가 로그에 남는다.
+- AC-4: CI에서 대시보드 HTTP smoke가 fixture DB 기준으로 Streamlit을 기동한 뒤 HTTP 200 응답을 확인하고, 종료 후 프로세스를 정리한다.
+- AC-5: CI에서 DB safety smoke가 운영 DB 기본 경로를 사용하지 않고 임시 fixture/검증 DB에서 통과한다.
+- AC-6: HTTP smoke/DB safety smoke는 CI 전용 wrapper entrypoint를 통해 실행되며, wrapper가 종료코드·timeout·readiness·cleanup을 일관되게 처리한다.
+- AC-7: CI 로그·아티팩트에는 실계좌번호, 실잔액, `raw_payload`, 원본 금융 파일명, 비밀번호가 평문으로 포함되지 않는다.
+- AC-8: `docs/project-structure.md`와 `docs/runtime-flows.md`가 CI 게이트와 로컬 browser evidence 경계를 반영한다.
+- AC-9: browser-screenshot E2E는 CI 필수 차단 게이트에서 제외되고, dcy-004 로컬 evidence 절차와의 역할 분담이 문서에 명시된다.
+
+## 5. 구현 메모
+
+- 이 REQ는 테스트/검증 계약과 운영 문서를 함께 다루는 `Testing` 타입으로 관리한다.
+- CI는 synthetic fixture DB를 매 실행마다 새로 생성하는 방식을 기본으로 하며, repo에 실데이터 기반 fixture를 커밋하지 않는다.
+- PR 병합 차단의 실제 enforcement(브랜치 보호 규칙)는 GitHub 설정과 연동되므로, workflow 설계 시 required check 이름이 안정적으로 유지되도록 한다.
+- `scripts/streamlit_browser_evidence.py`는 CI 필수 게이트가 아니라 로컬 보강 evidence 경로로 유지한다.
+- 리스크 책임자 지정과 batch 단위 구현 분해는 BAT-006 planning 단계에서 확정한다.
+- 이 REQ는 BAT-006 구현 및 `jarcaledgerqc`의 PASS_WITH_NOTES 검증을 근거로 Implemented로 전환했다. 남은 note는 원격 GitHub Actions 실행/required check 설정 확인으로, 저장소 코드 범위를 넘는 운영 확인 항목이다.
@@ -33,7 +33,7 @@

 ## Next Requirement ID

- Current: `REQ-003`
+- Current: `REQ-007`
 - Rule: `Requirement Register`에 있는 가장 큰 REQ 번호보다 정확히 1 커야 한다.

 ## Requirement Register
@@ -42,6 +42,10 @@
 | --- | --- | --- | --- | --- | --- | --- |
 | REQ-001 | 분류 규칙 운영 액션의 DB 경로 일관성 및 삭제 노출 | Interface | Implemented | High | 렛저장인 | [req-001_category-rule-ops.md](Interface/req-001_category-rule-ops.md) |
 | REQ-002 | 운영 안전 백업·복구·검증 DB 워크플로우 | Non-Functional | Implemented | High | 렛저장인 | [req-002_operational-safety-backup-restore-validation-db.md](Non-Functional/req-002_operational-safety-backup-restore-validation-db.md) |
+| REQ-003 | Statement-unavailable 계좌 수동 증빙 및 잔액대조 | Interface | Implemented | High | 렛저장인 | [req-003_statement-unavailable-manual-evidence-balance-reconciliation.md](Interface/req-003_statement-unavailable-manual-evidence-balance-reconciliation.md) |
+| REQ-004 | Browser/Streamlit E2E evidence 환경 복구 | Testing | Implemented | High | 렛저장인 | [req-004_browser-streamlit-e2e-evidence-recovery.md](Testing/req-004_browser-streamlit-e2e-evidence-recovery.md) |
+| REQ-005 | Dashboard operations hub/liquidity/monthly cashflow | Interface | Approved | High | 렛저장인 | [req-005_dashboard-operations-hub-liquidity-monthly-cashflow.md](Interface/req-005_dashboard-operations-hub-liquidity-monthly-cashflow.md) |
+| REQ-006 | pytest/AppTest/Smoke CI 자동화 | Testing | Implemented | High | 렛저장인 | [req-006_pytest-apptest-smoke-ci-automation.md](Testing/req-006_pytest-apptest-smoke-ci-automation.md) |

 ## Recent Change Log Summary

@@ -49,3 +53,10 @@
 - 2026-06-26 23:41 KST: BAT-001 검증 및 검수관 PASS_WITH_NOTES 근거로 REQ-001을 Implemented 상태로 전환.
 - 2026-06-27 10:17 KST: dcy-002 후속 운영 안전장치 범위로 REQ-002를 생성하고 사용자 승인 기본안에 따라 Approved 상태로 등록.
 - 2026-06-27 10:33 KST: BAT-002 verification 및 jarcaledgerqc PASS 근거로 REQ-002를 Implemented 상태로 전환.
+- 2026-06-29 KST: dcy-003 confirmed 범위로 REQ-003을 생성하고 BAT-003 구현·검증 대상으로 등록.
+- 2026-06-29 KST: dcy-004 confirmed 범위로 REQ-004를 생성하고 BAT-004 browser evidence 구현·검증 대상으로 등록.
+- 2026-06-29 20:03 KST: dcy-005 confirmed 범위로 REQ-005를 Proposed 상태로 생성하고 dashboard operations hub/liquidity/monthly cashflow 요구사항으로 등록.
+- 2026-06-29 21:08 KST: REQ-005를 Approved로 전환하고 dcy-005 구현 입력으로 확정.
+- 2026-06-30 14:42 KST: dcy-006 confirmed 범위로 REQ-006을 Proposed 상태로 생성하고 GitHub Actions 기반 pytest/AppTest/HTTP smoke/DB safety smoke CI 요구사항으로 등록.
+- 2026-06-30 14:50 KST: REQ-006을 Approved로 전환하고 BAT-006 standard batch 입력으로 확정.
+- 2026-06-30 15:29 KST: BAT-006 구현과 jarcaledgerqc PASS_WITH_NOTES 검증을 근거로 REQ-006을 Implemented로 전환.