jsfamily/jarca-ledger-mcp
5
0
Fork 1
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Jarca
2026-06-30 16:06:47 +09:00
parent 67d8d4871b
commit 4929e52189
75 changed files with 8367 additions and 252 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/discovery/dcy-003_20260629_statement-unavailable-manual-evidence-balance-reconciliation.md
+210
View File
@@ -0,0 +1,210 @@
# 0. 문서 상태
이 문서의 현재 상태와 식별 정보를 기록한다. 문서 추적과 승인 흐름에 필요한 최소 메타데이터를 적는다.
- 상태: confirmed
- 문서 ID: dcy-003_20260629_statement-unavailable-manual-evidence-balance-reconciliation
- 이슈명: Statement-unavailable 계좌 수동 증빙 및 잔액대조 워크플로우 정립
- 작성 시각(KST): 2026-06-29 12:33
- 마지막 갱신 시각(KST): 2026-06-29 13:06
- 대체됨: 없음
- 후속 Discovery 참조: 없음
- 생성된 REQ 참조: REQ-003 (`docs/srs/Interface/req-003_statement-unavailable-manual-evidence-balance-reconciliation.md`)
# 1. 계획 상태 요약
현재 Discovery가 어떤 배경에서 작성되고 있는지, 연계 문서가 있는지, 지금 시점의 해석이 무엇인지 짧게 요약한다.
- 연계 문서 현황:
- 관련 GitHub Project 항목: https://github.com/users/genichin/projects/4 DraftIssue
- 관련 TODO/메모: Statement-unavailable 계좌 수동 증빙 및 잔액대조 워크플로우 정립
- 해석:
- dcy-001(분류·환급 UX)과 dcy-002(백업·복구 안전장치)는 모두 statement(거래내역 파일)가 존재하는 계좌의 import·분류·검증 흐름을 전제로 하며, statement가 없거나 자동 import가 어려운 계좌를 다루는 표준 절차는 아직 정의되지 않았다.
- 이번 Discovery는 거래내역 파일이 없는 계좌에 대한 수동 증빙 입력, 잔액대조(reconciliation), 확인필요 큐 처리, 계좌이동/실지출 판정 기준을 독립 주기로 정의한다.
# 2. 요구사항 판정 결과
이번 요청이 기존 요구사항과 비교해 신규인지, 유사한지, 중복인지 판단하고 그 근거를 남긴다.
- 판정: 신규
- 근거
- 기존 Discovery dcy-001/dcy-002와 REQ-001/REQ-002는 statement 기반 import·분류·백업 범위를 다루며, statement-unavailable 계좌의 수동 증빙·잔액대조를 독립 성공 기준으로 다루지 않는다.
- 코드에는 `source='manual'` 거래, `ledger_accounts.last_balance`, `transactions.balance_after`, transfer 매칭/확인필요 큐가 부분적으로 존재하나, 이를 잔액대조 워크플로우로 묶는 명시적 절차·acceptance criteria가 없어 별도 주기로 추적할 필요가 있다.
# 3. 문제점의 요약
문제의 현재 상태, 기대 상태, 관련 이해관계자, 제약사항을 정리한다. Discovery의 핵심 맥락을 가장 먼저 이해할 수 있어야 한다.
- 현재 상태
- import 경로는 statement 파일을 전제로 한다: `service.py`의 `preview_ledger_csv_import`, `preview_kb_bank_pdf_import`, `preview_seoulpay_xlsx_import`, `preview_toss_bank_pdf_import`, `preview_toss_securities_pdf_import` 등은 모두 입력 파일이 있어야 동작한다.
- 스키마에는 수동 증빙·잔액대조의 토대가 일부 존재한다: `db.py`의 `ledger_accounts.last_balance`/`last_synced_at`, `transactions.balance_after`, `transactions.source`(기본값 `manual`).
- 계좌이동/실지출 판정 요소가 분산되어 있다: `find_self_transfer_candidates`, `link_self_transfer_pair`, `run_cross_account_transfer_match`/`list_cross_transfer_review_queue`(확인필요 성격의 review 큐), `infer_cashflow_kind`(category→cashflow_kind 추론). 그러나 statement가 없는 계좌에 대해 수동 입력 거래를 어떤 기준으로 계좌이동 또는 실지출로 판정할지에 대한 단일 규칙·증빙 요건은 문서화되어 있지 않다.
- `docs/runbooks/`에는 `ledger-backup-restore.md`만 있고, 수동 증빙/잔액대조 운영 절차 runbook이 없다. `docs/runtime-flows.md`도 statement-unavailable 계좌의 입력·대조 흐름을 다루지 않는다.
- 기대 상태
- 운영자는 거래내역 파일이 없거나 자동 import가 어려운 계좌에 대해, 표준화된 수동 증빙(거래·증빙 출처·금액·일자) 입력 절차로 누락 없이 거래를 기록할 수 있다.
- 각 계좌의 기준 잔액(`last_balance`)과 누적 거래로 산출한 계산 잔액을 대조하여 차이를 정량적으로 확인하고, 허용 오차를 벗어나는 차이는 확인필요 큐로 라우팅한다.
- 수동 입력·대조 과정에서 발생한 모호 거래를 계좌이동/실지출 판정 기준에 따라 일관되게 분류하여 월간 현금흐름·카테고리 지출 보고서의 왜곡을 줄인다.
- 이해관계자
- 렛저장인(운영자 겸 작성자) — 수동 증빙 입력과 잔액대조 실행 주체
- 검수관/리뷰어 — 대조 결과와 판정 근거의 검증 주체
- StagePilot 후속 SDLC(REQ/Batch) 수행자 — 본 Discovery를 후속 요구사항으로 정제
- 제약사항
- 개인 금융정보를 다루므로 증빙 원문·계좌번호는 마스킹(`account_number_masked`)·최소 보관 원칙을 따른다.
- 원본 운영 DB 훼손을 피하기 위해 dcy-002에서 정의한 백업·검증 DB 절차를 전제로 한다.
- 수동 입력은 휴먼 에러 가능성이 높아 입력 검증과 재대조 가능성이 필요하다.
## 주요 사용자 시나리오
사용자 또는 운영자가 실제로 어떤 상황에서 이 변경을 필요로 하는지 대표 시나리오를 적는다.
- 운영자가 거래내역 파일을 제공하지 않는 계좌(예: 일부 현금 계좌, 모임 통장, 명세서 비공개 계좌)의 월말 잔액만 알고 있을 때, 누락 거래를 수동 증빙으로 입력하고 계산 잔액을 기준 잔액과 맞춘다.
- import는 되지만 일부 기간 데이터가 비어 있는 계좌에서, 비어 있는 구간의 거래를 수동 증빙으로 보완한 뒤 잔액대조로 정합성을 확인한다.
- 잔액대조 결과 차이가 허용 오차를 초과하여 확인필요 큐에 올라온 항목을, 운영자가 계좌이동(다른 내 계좌로의 이동)인지 실지출인지 판정하여 처리한다.
# 4. 이번에 정의할 변경
이번 Discovery에서 다루는 핵심 변경 항목을 목록으로 적는다. 기능, 구조, 규칙 변경을 함께 포함해도 된다.
- `accounts.statement_status`를 추가해 `manual_only`를 statement-unavailable 계좌로 정의하고, `partial_import`도 수동 보완/잔액대조 대상으로 포함한다.
- statement-unavailable 계좌에 대한 수동 증빙 입력 표준(필수 필드: 일자, 금액, 출처/증빙 유형, 메모, source=manual)과 입력 검증 규칙을 정의한다.
- 계좌별 기준 잔액(`last_balance`) 대비 누적 거래 계산 잔액을 비교하는 잔액대조 절차를 정의한다. 정기 기준 시점은 매월 말일 23:59 KST, 수시 기준 시점은 사용자 입력 스냅샷 시각이며, 초기 허용 오차는 1,000원으로 한다.
- 확인필요 큐 항목에 대한 계좌이동/실지출/실수입/투자이동/분석제외/확인필요 판정 기준을 문서화한다. 자동 확정은 제한하고 추천/후보 제시 후 사용자 수동 확정을 기본으로 한다.
- 수동 증빙·잔액대조 운영 절차를 `docs/runtime-flows.md`(신규 흐름)와 신규 runbook 후보(`docs/runbooks/`)에 반영할 필요를 명시한다.
## 영향 범위
변경이 미칠 코드/문서/운영 범위를 명시해 REQ 정제와 batch planning에서 추정 누락을 줄인다.
- 코드 영향:
- `jarca_ledger_mcp/service.py` — 수동 증빙 입력/잔액대조/확인필요 라우팅 서비스 로직 신설 또는 기존 transfer·workbench 로직 확장
- `jarca_ledger_mcp/server.py` — 대조·증빙 관련 MCP tool 노출 (필요 시)
- `dashboard/app.py` — 계좌 화면의 `statement_status` 표시/수정, 최소 잔액대조 결과 표시. 전용 잔액대조 워크벤치 전체 신설은 후속 범위로 분리
- `jarca_ledger_mcp/db.py` — `accounts.statement_status` 추가 및 대조 메타(기준 잔액 스냅샷, 대조 시각 등) 보강 필요 여부 검토
- 문서 영향:
- `docs/runtime-flows.md` — statement-unavailable 수동 증빙·잔액대조 흐름 추가
- `docs/runbooks/` — 수동 증빙·잔액대조 운영 runbook 신규 후보
- `docs/data-model.md` — 대조 관련 필드 의미 보강 필요 여부 검토
- 운영 영향:
- 월말/정기 잔액대조 운영 루틴이 신설되며, 대조 전 dcy-002 백업 절차 선행이 요구된다.
# 5. 요구사항 목록
실제로 구현과 검증으로 이어질 요구사항을 기능/비기능으로 나누어 정리하고, 범위 경계를 명확히 적는다.
## 기능 요구사항
- FR-1: `accounts.statement_status` 필드를 `unknown`, `import_supported`, `manual_only`, `partial_import` 값으로 관리하고, `manual_only` 계좌를 statement-unavailable 계좌로 정의해야 한다. `partial_import` 계좌는 수동 보완 및 잔액대조 대상으로 포함한다.
- FR-1a: statement-unavailable 계좌에 대해 일자·금액·증빙유형·메모를 갖춘 수동 증빙 거래를 `source='manual'`로 입력·수정할 수 있어야 하며, 필수 필드 누락 시 입력을 거부해야 한다.
- FR-2: 계좌별 기준 잔액(`last_balance`)과 누적 거래 기반 계산 잔액을 비교하여 차액과 대조 시점을 산출하는 잔액대조 기능을 제공해야 한다. 정기 대조 기준 시점은 매월 말일 23:59 KST이고, 수시 대조는 사용자가 입력한 스냅샷 시각을 기준으로 한다.
- FR-3: 잔액대조 차액이 초기 허용 오차 1,000원을 초과하면 해당 항목을 확인필요 큐로 라우팅하고, 운영자가 계좌이동/실지출/분석제외로 판정해 처리할 수 있어야 한다. 기준 잔액 대비 0.1% 비율은 참고값으로만 표시하고 1차 판정 기준에는 사용하지 않는다.
- FR-4: 확인필요 항목은 계좌이동, 실지출, 실수입, 투자이동, 분석제외, 확인필요 6개 판정값으로 처리할 수 있어야 한다. 자동 확정보다는 후보 추천과 사용자 수동 확정을 기본으로 하며, 확정 결과는 `cashflow_kind`에 반영되어 월간 현금흐름·카테고리 지출 보고서에 일관되게 적용되어야 한다.
- FR-5: 수동 증빙·잔액대조 운영 흐름을 `docs/runtime-flows.md`에 반영하고, 운영 절차 runbook을 `docs/runbooks/` 후보로 추가해야 한다.
## 비기능 요구사항
성능, 운영성, 일관성, 자동화 안정성 등 기능 외 요구사항을 적는다.
- NFR-1: 모든 대조·증빙 작업은 dcy-002의 백업·검증 DB 절차를 전제로 수행되어 원본 운영 DB 훼손 위험을 낮춰야 한다.
- NFR-2: 증빙 원문·계좌 식별정보는 마스킹·최소 보관 원칙을 따르고, 문서·로그에 평문 계좌번호/자격증명을 남기지 않아야 한다.
- NFR-3: 잔액대조 결과는 재현 가능해야 하며, 동일 입력에 대해 동일한 차액·확인필요 분류 결과를 산출해야 한다.
## 범위 경계
이번 반복에서 반드시 포함할 범위와 명시적으로 제외할 범위를 구분한다.
- In Scope
- `accounts.statement_status` 기반 statement-unavailable 계좌 분류와 수동 증빙 입력·검증 규칙 정의
- 기준 잔액 대비 계산 잔액 대조, 월말/수시 기준 시점, 1,000원 허용 오차 및 확인필요 라우팅 규칙 정의
- 계좌이동/실지출 판정 기준의 문서화
- Out of Scope
- statement 파일 기반 자동 import 파서 신규 추가(기존 KB/Toss/SeoulPay 경로 변경 없음)
- 잔액대조 자동 스케줄링/알림. 이번 반복은 수동 실행 가능한 잔액대조와 결과 리포트까지만 포함한다.
- 전용 잔액대조 워크벤치 전체 신설. 이번 반복은 계좌 화면의 `statement_status` 표시/수정과 최소 잔액대조 결과 표시까지만 포함한다.
# 6. 리스크/가정 목록
불확실성과 전제 조건을 분리해서 적는다. 리스크는 영향과 완화 방안을, 가정은 현재 판단의 전제를 기록한다.
## 리스크
- R-1 (High): 수동 입력 휴먼 에러로 거래가 중복·누락되어 잔액대조 차액이 실제 오류를 가릴 수 있다.
- 완화 방안: 필수 필드 검증, 입력 후 재대조, 차액 변화 로그로 추적 가능성 확보
- R-2 (Medium): 계좌이동/실지출 판정 기준이 모호하면 동일 거래가 작업자마다 다르게 분류되어 보고서 일관성이 깨진다.
- 완화 방안: 자기계좌 간 이동·외부 지출·분석제외에 대한 명시적 판정표 정의 및 기존 `infer_cashflow_kind`/transfer 매칭과 정합
- R-3 (Medium): 허용 오차 임계값이 부적절하면 확인필요 큐가 과도하게 커지거나 실제 차이를 놓친다.
- 완화 방안: 초기 임계값을 보수적으로 설정하고 운영 데이터로 조정, 임계값을 설정값으로 외부화
## 가정
아직 확정되지 않았지만 현재 문서 작성의 기반이 되는 전제를 적는다.
- A-1: `ledger_accounts.last_balance`, `transactions.balance_after`/`source`, 신규 `accounts.statement_status` 필드를 잔액대조의 기준 데이터로 재사용할 수 있다.
- A-2: 기존 transfer 매칭(`link_self_transfer_pair`, cross-account match)과 확인필요 review 큐 구조를 계좌이동 판정 흐름에 연계할 수 있다.
- A-3: 대조 작업은 dcy-002 백업·검증 DB 절차가 이미 운영 가능한 상태임을 전제로 한다.
## 오픈 질문
답을 아직 모르는 항목을 적는다. 추정으로 덮지 말고 REQ 초안 작성 이전에 확인할 질문으로 남긴다.
- OQ-1: 잔액대조 허용 오차(절대 금액/비율)와 기준 시점(월말/임의 스냅샷)을 어떻게 정의할 것인가?
- 상태: Answered
- 처리 방안: 정기 잔액대조는 매월 말일 23:59 KST 기준으로 수행한다. 수시 대조는 사용자가 입력한 스냅샷 시각을 기준으로 허용한다. 초기 허용 오차는 절대 금액 1,000원으로 두며, 차액이 1,000원을 초과하면 확인필요 큐로 라우팅한다. 기준 잔액 대비 0.1% 비율은 표시/참고값으로만 제공하고, 1차 판정 기준으로는 사용하지 않는다.
- 종료 조건: REQ의 acceptance criteria에 기준 시점, 허용 오차 1,000원, 확인필요 라우팅 조건이 수치로 반영되면 Answered
- OQ-2: 어떤 계좌를 "statement-unavailable"로 분류·표시할 것인가(계좌 속성 신설 여부)?
- 상태: Answered
- 처리 방안: `accounts` 테이블에 `statement_status` 필드를 추가한다. 허용값은 `unknown`, `import_supported`, `manual_only`, `partial_import`로 정의한다. 기본값은 `unknown`이다. `manual_only` 계좌를 dcy-003의 statement-unavailable 계좌로 간주하고, `partial_import` 계좌는 수동 보완 및 잔액대조 대상으로 포함한다.
- 종료 조건: REQ의 데이터 모델/acceptance criteria에 `statement_status` 필드, 허용값, 기본값, 잔액대조 대상 조건이 반영되면 Answered
# 7. 초기 성공 기준
이 변경이 성공했다고 판단할 기준을 측정 가능하게 정의한다. 가능하면 데이터 출처까지 연결한다.
- S-1: `statement_status=manual_only` 또는 `partial_import`인 대상 계좌에 대해 수동 증빙 입력 후 계산 잔액과 기준 잔액의 차액이 1,000원 이내로 수렴한다.
- S-2: 잔액대조 차액이 1,000원을 초과하는 모든 항목이 확인필요 큐에 라우팅되고, 계좌이동/실지출/분석제외 중 하나로 판정·처리된다.
- S-3: 수동 증빙·잔액대조 운영 흐름이 `docs/runtime-flows.md`와 runbook 후보 문서로 정리되어 후속 REQ/Batch에서 참조 가능하다.
## 측정 방식 및 데이터 출처
각 성공 기준을 어떻게 측정할지와 어떤 데이터나 문서를 근거로 쓸지 적는다.
- S-1 측정 방식: 검증 DB에서 `statement_status in (manual_only, partial_import)` 계좌별 (계산 잔액 − 기준 잔액) 차액 산출 및 1,000원 이내 여부 확인 / 데이터 출처: `accounts.statement_status`, `ledger_accounts.last_balance`, `transactions`(`amount`/`balance_after`)
- S-2 측정 방식: 확인필요 큐 적재 건수와 미판정 잔여 건수 비교 / 데이터 출처: 확인필요 큐(서비스 로직 결과), 판정 처리 로그
- S-3 측정 방식: 문서 존재 및 흐름 반영 여부 리뷰 / 데이터 출처: `docs/runtime-flows.md`, `docs/runbooks/`
# 8. REQ로 넘기기 전 확인 체크
REQ 초안 작성 단계로 넘기기 전에 무엇이 확정되어야 하는지 확인한다. 미완료 항목은 후속 결정이 필요함을 뜻한다.
- [x] 범위(In Scope/Out of Scope) 확정
- 기준: 자동 스케줄링/알림과 전용 잔액대조 워크벤치 전체 신설은 제외하고, 수동 실행 잔액대조·결과 리포트·계좌 화면의 `statement_status` 표시/수정은 포함한다.
- [x] 성공 지표의 측정 방식/데이터 출처 확정
- 기준: 허용 오차 1,000원, 월말 23:59 KST 정기 기준 시점, 사용자 입력 수시 스냅샷 기준 시점이 측정 방식에 반영됨
- [x] High 영향 리스크 우선순위 및 해소 책임자 지정
- 기준: R-1(수동 입력 휴먼 에러)은 렛저장인이 필수 필드 검증·재대조·검증 DB evidence로 해소한다.
- [x] 모든 오픈 질문(OQ) `Open` 상태 없음 확인
- 기준: OQ 목록에 `Open` 상태 항목이 0개이거나, 잔여 항목 전부 `Deferred` 처리 완료
- [x] Freeze 확정 담당자(CONFIRMED_BY) 지정
- 기준: 사용자 진환 고가 본 Discovery 권장안을 승인하고 구현 위임을 지시했다.
# 9. 파일 처리 결과
이 Discovery 문서 생성/갱신 결과와 참조 문서를 기록한다. 이후 추적과 리뷰 시 근거로 사용한다.
- 처리 결과: 생성
- 생성 경로: docs/discovery/dcy-003_20260629_statement-unavailable-manual-evidence-balance-reconciliation.md
- 참조 문서:
- docs/discovery/dcy-002_20260627_operational-safety-backup-restore-validation-db.md
- docs/runtime-flows.md
- docs/data-model.md
# 10. 사용자 결정 필요 항목 요약
사용자나 승인자가 결정해야 하는 항목만 모아 정리한다. 결정, 확인, 데이터 요청을 구분해서 적는다.
## DECIDE
- 잔액대조 자동 스케줄링/알림은 이번 반복 범위에서 제외하고, 수동 실행 가능한 잔액대조와 결과 리포트까지만 포함한다.
- 전용 수동 증빙/잔액대조 워크벤치 전체 신설은 제외하고, 계좌 화면의 `statement_status` 표시/수정과 최소 잔액대조 결과 표시까지만 포함한다.
- 계좌이동, 실지출, 실수입, 투자이동, 분석제외, 확인필요 6개 판정값을 사용한다. 자동 확정보다는 추천/후보 제시 후 사용자 수동 확정을 기본으로 한다.
## CONFIRM
- 대조 작업 전 dcy-002 백업·검증 DB 절차 선행을 운영 표준으로 확정한다. 운영 DB 변경 전 백업은 필수이며, 검증 DB에서 preview/reconcile을 먼저 수행한다. Restore는 사용자 명시 승인 없이는 실행하지 않는다.
## DATA
- 실제 계좌별 기준 잔액 값은 운영 시점에 입력한다. REQ에는 `account_id`, `statement_status`, `baseline_balance`, `baseline_at`, `source_note`, `memo` 입력 포맷과 검증 규칙을 정의한다.
# 11. Discovery Freeze
REQ 초안 작성 인계 시점의 확정 플래그와 섹션 참조만 기록한다. 내용 재작성 없이 원본 섹션을 링크로 대신한다.
## 섹션 참조
- 범위: [# 5. 요구사항 목록 > 범위 경계](#5-요구사항-목록)
- 리스크/오픈 질문: [# 6. 리스크/가정 목록](#6-리스크가정-목록)
- 성공 기준: [# 7. 초기 성공 기준](#7-초기-성공-기준)
- 인계 전 확인: [# 8. REQ로 넘기기 전 확인 체크](#8-req로-넘기기-전-확인-체크)
- 사용자 결정 필요: [# 10. 사용자 결정 필요 항목 요약](#10-사용자-결정-필요-항목-요약)
## Freeze 플래그
- Handoff Decision: 승인
- Handoff Rationale: 사용자 승인으로 잔액대조 허용 오차, 기준 시점, statement-unavailable 계좌 분류 방식, 자동화/UI 범위, 판정 기준, 백업 선행 조건, 기준 잔액 데이터 처리 방식이 확정되었으므로 REQ 초안 작성과 구현 위임으로 넘긴다.
- Ready for REQ Drafting: true
- Confirmed By: 진환 고
- Confirmed At (KST): 2026-06-29 13:06
docs/discovery/dcy-004_20260629_browser-streamlit-e2e-evidence-recovery.md
+210
View File
@@ -0,0 +1,210 @@
# 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 초안 작성 단계로 넘기기 전에 무엇이 확정되어야 하는지 확인한다. 미완료 항목은 후속 결정이 필요함을 뜻한다.
- [x] 범위(In Scope/Out of Scope) 확정
- 기준: 이번 반복은 로컬 재현 가능한 browser evidence 복구와 증거 등급화까지로 한정한다. CI 통합은 Project #4의 `pytest/AppTest/Smoke CI 자동화` 항목으로 분리하고, visual regression은 제외한다.
- [x] 성공 지표의 측정 방식/데이터 출처 확정
- 기준: Hermes browser/Google Chrome 기반 screenshot/snapshot evidence, console 확인, Streamlit 서버 로그, AppTest+HTTP fallback이 REQ acceptance criteria에 반영된다.
- [x] High 영향 리스크 우선순위 및 해소 책임자 지정
- 기준: R-1(Chromium 확보 불가)은 현재 설치된 `/usr/bin/google-chrome-stable`을 1차 runtime으로 사용하고, 렛저장인이 로컬 evidence 절차를 구현·검증한다.
- [x] 모든 오픈 질문(OQ) `Open` 상태 없음 확인
- 기준: OQ-1(도구 표준화), OQ-2(게이트 정책)가 Answered 처리됨.
- [x] 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 초안 작성 인계 시점의 확정 플래그와 섹션 참조만 기록한다. 내용 재작성 없이 원본 섹션을 링크로 대신한다.
## 섹션 참조
- 범위: [# 5. 요구사항 목록 > 범위 경계](#5-요구사항-목록)
- 리스크/오픈 질문: [# 6. 리스크/가정 목록](#6-리스크가정-목록)
- 성공 기준: [# 7. 초기 성공 기준](#7-초기-성공-기준)
- 인계 전 확인: [# 8. REQ로 넘기기 전 확인 체크](#8-req로-넘기기-전-확인-체크)
- 사용자 결정 필요: [# 10. 사용자 결정 필요 항목 요약](#10-사용자-결정-필요-항목-요약)
## 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
docs/discovery/dcy-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow.md
+209
View File
@@ -0,0 +1,209 @@
# 0. 문서 상태
이 문서의 현재 상태와 식별 정보를 기록한다. 문서 추적과 승인 흐름에 필요한 최소 메타데이터를 적는다.
- 상태: confirmed
- 문서 ID: dcy-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow
- 이슈명: Jarca Ledger 대시보드 운영 허브 사양 정립 (이번 달 현금흐름 + 자산 유동성 + 운영 미처리)
- 작성 시각(KST): 2026-06-29 14:02 KST
- 마지막 갱신 시각(KST): 2026-06-29 20:03 KST
- 대체됨: 없음
- 후속 Discovery 참조: 없음
- 생성된 REQ 참조: REQ-005 (`docs/srs/Interface/req-005_dashboard-operations-hub-liquidity-monthly-cashflow.md`)
# 1. 계획 상태 요약
현재 Discovery가 어떤 배경에서 작성되고 있는지, 연계 문서가 있는지, 지금 시점의 해석이 무엇인지 짧게 요약한다.
- 연계 문서 현황:
- 관련 점수 파일: 미생성
- 관련 TODO/메모: 없음
- 해석:
- 대시보드 첫 화면(`page_overview`)이 현재는 전체 기간 누적 손익·계좌 입출금 위주라, "이번 달 운영 상태"와 "현재 자산 유동성/부채 구조"를 한 화면에서 보려는 운영자 요구를 충족하지 못한다.
- 이번 Discovery는 대시보드를 단일 운영 허브로 재정의하고, 이번 달 현금흐름·자산 유동성·운영 미처리 경고를 우선순위 구조로 묶는 변경 범위와 데이터 모델 보강(`liquidity_bucket`) 필요성을 판단한다.
# 2. 요구사항 판정 결과
이번 요청이 기존 요구사항과 비교해 신규인지, 유사한지, 중복인지 판단하고 그 근거를 남긴다.
- 판정: 신규
- 근거
- dcy-001은 Streamlit UX/E2E·분류·환급 워크플로우 안정화, dcy-002~004는 백업·복구, statement-unavailable 수동 증빙/잔액대조, E2E evidence 환경 복구로 문제 정의가 다르며 "대시보드 화면 구성·자산 유동성 뷰"를 다루지 않는다.
- 본 요청은 대시보드 정보구조 재정의와 신규 자산 분류 축(`liquidity_bucket`) 도입을 핵심으로 하므로 기존 후보의 미세 조정이 아니라 독립 주기로 추적하는 것이 명확하다.
# 3. 문제점의 요약
문제의 현재 상태, 기대 상태, 관련 이해관계자, 제약사항을 정리한다. Discovery의 핵심 맥락을 가장 먼저 이해할 수 있어야 한다.
- 현재 상태
- `dashboard/app.py`의 `page_overview`는 `status='active'` 전체 거래를 누적 집계해 "실제 수입/지출/순현금흐름/저축률/확인필요"와 "계좌 입출금 흐름", 월별/인원별/카테고리 Top20 차트를 보여준다. 상단 지표가 당월이 아니라 전체 기간 합계 기준이라 "이번 달 현황"을 즉시 읽기 어렵다.
- 자산 측면에서 `ledger_accounts.type`은 bank/card/cash/investment/loan 구분만 있고(`docs/data-model.md` Entity: LedgerAccount), 현금·투자·예적금·부동산·대출을 유동성 관점으로 묶는 `liquidity_bucket` 축은 없다. 자산 유동성/구성/순자산 뷰가 대시보드에 존재하지 않는다.
- 운영 미처리 신호(미분류 거래, 확인필요 큐, 잔액대조 필요, 백업/import 상태)는 `page_uncategorized`, `page_cross_transfer_review`, `docs/runbooks/manual-balance-reconciliation.md`, 백업 워크플로우 등 별도 화면/문서에 흩어져 있어 한 화면에서 운영 상태를 점검하지 못한다.
- `docs/project-structure.md`, `docs/runtime-flows.md` baseline 문서는 존재하나 대시보드 운영 허브 정보구조와 `liquidity_bucket` 데이터 흐름을 아직 반영하지 않는다.
- 기대 상태
- 대시보드 첫 화면이 "이번 달 수입/지출 현황 → 자산 유동성 현황 → 자산 구성 → 지출 구조/예산 → 운영 경고" 순서의 운영 허브로 동작한다.
- 자산을 유동성 버킷(현금/투자/예적금/부동산/대출)으로 묶어 금액·비율을 확인하고, 대출은 자산 구성 비율에서 제외하되 부채/순자산 계산에서 별도 차감한다.
- 이해관계자
- 가계 재무를 운영하는 사용자(대시보드 1차 사용자)
- 문서/요구사항 리뷰어 및 승인자(Hermes/사용자)
- 대시보드·서비스·DB를 구현/운영하는 개발 담당자
- 제약사항
- DB 스키마 변경은 additive/idempotent 원칙을 따르며 파괴적 마이그레이션은 명시 승인·백업 후에만 한다(`docs/data-model.md` Persistence Notes).
- 부동산·무기한 자산처럼 거래 기반이 아닌 자산은 입력 소스가 불명확해 데이터 확보 방식 결정이 선행되어야 한다.
- 본 Discovery 단계에서는 소스 코드/테스트/스키마를 변경하지 않고 사양만 정의한다.
## 주요 사용자 시나리오
사용자 또는 운영자가 실제로 어떤 상황에서 이 변경을 필요로 하는지 대표 시나리오를 적는다.
- 사용자가 월중에 대시보드를 열어 "이번 달 수입·지출·순현금흐름·저축률"을 최상단에서 즉시 확인하고 이번 달 지출 속도를 점검한다.
- 사용자가 "지금 당장 쓸 수 있는 현금이 얼마이고, 1~2주 내 가용 투자/예적금이 얼마이며, 부동산·대출까지 포함한 순자산이 얼마인지" 자산 유동성·구성 섹션에서 한눈에 파악한다.
- 사용자가 같은 화면 하단의 운영 경고에서 미분류 건수, 확인필요 큐, 잔액대조 필요 계좌, 최근 백업/import 상태를 보고 후속 정리 작업으로 이동한다.
# 4. 이번에 정의할 변경
이번 Discovery에서 다루는 핵심 변경 항목을 목록으로 적는다. 기능, 구조, 규칙 변경을 함께 포함해도 된다.
- 대시보드 운영 허브 정보구조 확정: ① 이번 달 수입/지출 현황 ② 자산 유동성 현황 ③ 자산 구성 ④ 지출 구조/예산 ⑤ 운영 경고의 5개 섹션 우선순위와 각 섹션 표시 지표를 사양으로 정의한다.
- 자산 유동성 분류 축 도입 검토: `liquidity_bucket`(cash, investment, deposit, real_estate, loan, other)을 권장 필드로 정의하고, 대출은 자산 구성 비율에서 제외·부채/순자산에서 별도 차감하는 집계 규칙을 정한다.
- baseline 문서 반영: `liquidity_bucket` 데이터 모델과 대시보드 운영 허브 화면 흐름을 `docs/data-model.md`, `docs/project-structure.md`, `docs/runtime-flows.md`에 갱신 요구로 등록한다.
## 영향 범위
변경이 미칠 코드/문서/운영 범위를 명시해 REQ 정제와 batch planning에서 추정 누락을 줄인다.
- 코드 영향:
- `dashboard/app.py`의 `page_overview` 재구성(이번 달 스코프 집계, 자산 유동성/구성/순자산 섹션, 운영 경고 통합 패널) 및 관련 집계 헬퍼.
- `liquidity_bucket` 도입 시 `jarca_ledger_mcp/db.py` 스키마(additive)와 `service.py` 자산/유동성 집계 함수, 분류 매핑 로직.
- 문서 영향:
- `docs/data-model.md`(LedgerAccount/LedgerCategory에 `liquidity_bucket` 축, 순자산/부채 집계 규칙), `docs/project-structure.md`, `docs/runtime-flows.md`(대시보드 운영 허브 화면 흐름) 갱신.
- 운영 영향:
- 부동산·대출 등 비거래 자산 입력/갱신 절차가 신설될 수 있어 운영 입력 루틴과 잔액대조 운영 흐름에 영향을 준다.
# 5. 요구사항 목록
실제로 구현과 검증으로 이어질 요구사항을 기능/비기능으로 나누어 정리하고, 범위 경계를 명확히 적는다.
## 기능 요구사항
- FR-1: 대시보드 최상단 1순위 섹션은 "이번 달 수입/지출 현황"으로, 당월 기준 실제 수입·실제 지출·순현금흐름·저축률을 표시한다. 당월 범위는 거래일(`transaction_date`) 기준 현재 월을 기본으로 한다.
- FR-2: "자산 유동성 현황" 섹션은 현금(당장 사용 가능), 투자(1~2주 내 사용 가능), 예적금(달~년), 부동산(무기한), 대출(부채)을 버킷으로 묶어 각 금액과 비율을 표시한다. 비율 분모는 대출(부채)을 제외한 자산 합계로 하고, 대출은 부채/순자산 계산에서 별도 차감한다.
- FR-3: 대시보드는 ① 이번 달 수입/지출 현황 ② 자산 유동성 현황 ③ 자산 구성 ④ 지출 구조/예산 ⑤ 운영 경고(미분류, 확인필요, 잔액대조 필요, 백업/import 상태)의 순서로 섹션을 배치한다.
- FR-4: 자산을 유동성 관점으로 묶기 위해 `accounts.liquidity_bucket`(cash, investment, deposit, real_estate, loan, other) 분류 축을 데이터 모델에 도입한다. `liquidity_bucket`의 권위 소스는 계좌 단위이며, 미지정 계좌는 `other`로 폴백한다. 거래/카테고리 단위 override는 이번 범위에서 제외한다.
- FR-5: `docs/data-model.md`, `docs/project-structure.md`, `docs/runtime-flows.md` baseline 문서에 `liquidity_bucket` 모델과 대시보드 운영 허브 화면 흐름 갱신을 포함한다.
## 비기능 요구사항
성능, 운영성, 일관성, 자동화 안정성 등 기능 외 요구사항을 적는다.
- NFR-1 (일관성): 자산 구성 비율과 순자산/부채 계산은 단일 정의(대출은 구성 비율 제외, 순자산에서 차감)를 모든 섹션·집계에서 동일하게 적용한다.
- NFR-2 (운영성): 운영 경고 섹션의 각 항목(미분류·확인필요·잔액대조·백업/import)은 건수/상태와 함께 해당 상세 화면으로 이동할 수 있는 단서를 제공한다.
- NFR-3 (안정성): `accounts.liquidity_bucket` 스키마 변경은 additive/idempotent로 적용하고, 미지정 계좌는 `other`로 안전하게 폴백해 기존 대시보드 동작을 깨지 않는다.
## 범위 경계
이번 반복에서 반드시 포함할 범위와 명시적으로 제외할 범위를 구분한다.
- In Scope
- 대시보드 운영 허브 5개 섹션 정보구조와 각 섹션 핵심 지표 사양 정의.
- `accounts.liquidity_bucket` 축과 자산 유동성/구성/순자산·부채 집계 규칙 정의 및 baseline 문서 갱신 요구.
- Out of Scope
- 다계좌 실시간 잔액 연동, 외부 시세/투자 평가액 자동 연동.
- 카드 미결제금, 보험 해지환급금, 자동 시세 연동 자산 반영.
- 별도 자산 평가 테이블(`asset_snapshots`, `manual_assets` 등) 신설. 초기 구현은 `accounts` 항목의 수동 입력으로 처리한다.
# 6. 리스크/가정 목록
불확실성과 전제 조건을 분리해서 적는다. 리스크는 영향과 완화 방안을, 가정은 현재 판단의 전제를 기록한다.
## 리스크
- R-1 (Medium): `liquidity_bucket` 권위 소스가 구현 중 계좌 외 카테고리/거래 override로 확장되면 자산 집계 소스가 이중화돼 비율이 어긋날 수 있다.
- 완화 방안: 이번 반복의 단일 권위 소스는 `accounts.liquidity_bucket`으로 고정하고, 거래/카테고리 override는 후속 범위로 제외한다. 미매핑은 `other`로 폴백한 뒤 운영 경고로 노출한다.
- R-2 (Medium): 부동산·대출 등 비거래 자산은 거래 데이터로 산출되지 않아 입력 누락 시 자산 유동성/순자산 수치가 왜곡된다.
- 완화 방안: 초기에는 `accounts` 항목에 수동 입력하고, `last_balance`를 현재 평가액/잔액, `last_synced_at`을 기준일, `memo`를 출처 메모로 사용한다. 미입력 자산은 수치에서 제외했음을 화면에 표기한다.
- R-3 (Low): 상단 "이번 달" 스코프와 기존 전체 기간 차트가 한 화면에 공존하면 사용자가 기준 기간을 혼동할 수 있다.
- 완화 방안: 각 섹션에 기준 기간 라벨을 명시하고, 당월/전체 기준을 시각적으로 구분한다.
## 가정
아직 확정되지 않았지만 현재 문서 작성의 기반이 되는 전제를 적는다.
- A-1: 저축률은 기존 `page_overview` 정의(순현금흐름 ÷ 실제 수입)를 당월 범위로 적용한다.
- A-2: 실제 수입/지출 판정은 기존 `ledger_categories.cashflow_kind`(income/expense 등) 기준을 그대로 재사용한다.
- A-3: 대출은 자산이 아니라 부채로 취급하며 자산 구성 비율의 분모에서 제외하고, 총부채/순자산 계산에만 사용한다.
## 오픈 질문
답을 아직 모르는 항목을 적는다. 추정으로 덮지 말고 REQ 초안 작성 이전에 확인할 질문으로 남긴다.
- OQ-1: `liquidity_bucket`의 권위 소스를 계좌 단위로 둘지, 카테고리/거래 단위로 둘지 결정한다.
- 상태: Answered
- 처리 방안: `liquidity_bucket`의 권위 소스는 `accounts.liquidity_bucket`으로 둔다. 허용값은 `cash`, `investment`, `deposit`, `real_estate`, `loan`, `other`이며, 미지정 계좌는 `other`로 폴백한다. 거래/카테고리 override는 이번 범위에서 제외한다.
- 종료 조건: 자산 집계 권위 소스와 폴백 규칙이 REQ 초안에 명시되면 Answered 처리.
- OQ-2: 부동산·무기한 자산과 대출 잔액의 입력/갱신 방식(수동 입력 vs 전용 계좌 vs 외부 연동)을 어떻게 둘지 결정한다.
- 상태: Answered
- 처리 방안: 부동산, 예적금, 대출 잔액 등 거래내역만으로 산출되지 않는 자산/부채는 초기에는 `accounts` 항목으로 수동 입력한다. `last_balance`는 현재 평가액/잔액, `last_synced_at`은 기준일, `memo`는 출처 메모로 사용한다. 별도 자산 평가 테이블과 자동 시세 연동은 후속 범위로 둔다.
- 종료 조건: 비거래 자산 입력/갱신 방식이 REQ 초안과 운영 절차에 반영되면 Answered 처리.
### 오픈 질문 처리 기준
- `Open`: 아직 답이 없고 다음 단계 진행에 영향이 있는 상태다. 문서에 유지한다.
- `Answered`: 답이 확정된 상태다. 관련 본문/요구사항에 반영한 뒤 오픈 질문 목록에서는 제거하거나 resolved 기록으로 이동한다.
- `Deferred`: 지금 단계에서 결정하지 않고 다음 단계 또는 후속 이슈로 넘기는 상태다. 넘길 대상과 이유를 반드시 적는다.
- `Dropped`: 더 이상 유효하지 않은 질문이다. 삭제 사유를 짧게 남기고 목록에서 제거한다.
- 처리 원칙 1: 질문만 남기지 말고 반드시 `상태`, `처리 방안`, `종료 조건`을 함께 적는다.
- 처리 원칙 2: 답이 나온 질문은 본문 반영 없이 단순 삭제하지 않는다. 반영 위치를 먼저 갱신한다.
- 처리 원칙 3: High 영향 질문은 `Deferred` 처리 후 처리 방안에 REQ 인계 추적 방식을 명시한다.
# 7. 초기 성공 기준
이 변경이 성공했다고 판단할 기준을 측정 가능하게 정의한다. 가능하면 데이터 출처까지 연결한다.
- S-1: 대시보드 첫 화면에서 이번 달 수입/지출 현황, 자산 유동성 현황, 운영 경고가 정의된 우선순위 순서로 모두 노출된다.
- S-2: 자산 유동성/구성 섹션에서 `accounts.liquidity_bucket` 기준 버킷별 금액·비율, 대출 제외 자산 합계, 총부채, 순자산이 단일 정의에 따라 일관되게 계산된다.
- S-3: `liquidity_bucket` 데이터 모델과 대시보드 운영 허브 화면 흐름이 `docs/data-model.md`, `docs/project-structure.md`, `docs/runtime-flows.md`에 반영된다.
## 측정 방식 및 데이터 출처
각 성공 기준을 어떻게 측정할지와 어떤 데이터나 문서를 근거로 쓸지 적는다.
- S-1 측정 방식: 대시보드 운영 허브 화면 검수(스크린샷/E2E)로 섹션 순서·표시 지표 확인 / 데이터 출처: `dashboard/app.py` 렌더 결과, REQ 화면 사양
- S-2 측정 방식: 표본 데이터로 버킷 합계·비율·순자산 계산을 손검증과 비교 / 데이터 출처: `transactions`, `ledger_accounts`, `accounts.liquidity_bucket` 매핑 규칙
- S-3 측정 방식: baseline 문서 diff에서 `liquidity_bucket`·운영 허브 화면 흐름 반영 여부 확인 / 데이터 출처: `docs/data-model.md`, `docs/project-structure.md`, `docs/runtime-flows.md`
# 8. REQ로 넘기기 전 확인 체크
REQ 초안 작성 단계로 넘기기 전에 무엇이 확정되어야 하는지 확인한다. 미완료 항목은 후속 결정이 필요함을 뜻한다.
- [x] 범위(In Scope/Out of Scope) 확정
- 기준: 순자산 산식은 `accounts.liquidity_bucket` 기준 금융자산·수동 입력 비거래 자산에서 `loan`을 차감하는 방식으로 확정하고, 부동산 평가 자동화·자동 시세 연동·별도 자산 테이블은 제외한다.
- [x] 성공 지표의 측정 방식/데이터 출처 확정
- 기준: S-1~S-3의 검수 방식과 데이터 출처가 REQ에서 실행 가능하게 구체화됨
- [x] High 영향 리스크 우선순위 및 해소 책임자 지정
- 기준: `liquidity_bucket` 권위 소스는 계좌 단위로 고정하고, 비거래 자산 입력 리스크는 수동 입력 계좌/자산 항목과 기준일/출처 메모로 해소한다.
- [x] 모든 오픈 질문(OQ) `Open` 상태 없음 확인
- 기준: OQ 목록에 `Open` 상태 항목이 0개이거나, 잔여 항목 전부 `Deferred` 처리 완료
- [x] Freeze 확정 담당자(CONFIRMED_BY) 지정
- 기준: 사용자 진환 고가 권장안을 승인하고 confirm-discovery 진행을 지시했다.
# 9. 파일 처리 결과
이 Discovery 문서 생성/갱신 결과와 참조 문서를 기록한다. 이후 추적과 리뷰 시 근거로 사용한다.
- 처리 결과: 생성
- 생성 경로: docs/discovery/dcy-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow.md
- 참조 문서:
- docs/data-model.md (LedgerAccount/LedgerCategory, `liquidity_bucket` 도입 대상)
- docs/runtime-flows.md, docs/project-structure.md (대시보드 운영 허브 화면 흐름 갱신 대상; stage-pilot/templates/runtime-flows.md, stage-pilot/templates/project-structure.md를 논리 템플릿 참조로 사용)
- dashboard/app.py `page_overview` (현재 대시보드 첫 화면 구현 근거)
# 10. 사용자 결정 필요 항목 요약
사용자나 승인자가 결정해야 하는 항목만 모아 정리한다. 결정, 확인, 데이터 요청을 구분해서 적는다.
## DECIDE
- `liquidity_bucket`의 권위 소스는 `accounts.liquidity_bucket`으로 둔다. 허용값은 `cash`, `investment`, `deposit`, `real_estate`, `loan`, `other`이며, 미지정 계좌는 `other`로 폴백한다. 거래/카테고리 override는 이번 범위에서 제외한다.
- 순자산은 `cash`, `investment`, `deposit`, `real_estate`, `other` 중 자산성 항목의 합계에서 `loan` bucket 합계를 차감해 계산한다. 대출은 자산 구성 비율에는 포함하지 않고 총부채/순자산 계산에만 사용한다. 카드 미결제금, 보험 해지환급금, 자동 시세 연동은 이번 범위에서 제외한다.
## CONFIRM
- "이번 달"은 `transaction_date` 기준 현재 월(KST)로 정의한다. `posted_date` 기준 또는 사용자 정의 회계 월 마감은 후속 옵션으로 둔다.
## DATA
- 부동산, 예적금, 대출 잔액 등 거래내역만으로 산출되지 않는 자산/부채는 초기에는 `accounts` 항목으로 수동 입력한다. `last_balance`는 현재 평가액/잔액, `last_synced_at`은 기준일, `memo`는 출처 메모로 사용한다. 별도 자산 테이블과 자동 시세 연동은 후속 범위로 둔다.
# 11. Discovery Freeze
REQ 초안 작성 인계 시점의 확정 플래그와 섹션 참조만 기록한다. 내용 재작성 없이 원본 섹션을 링크로 대신한다.
## 섹션 참조
- 범위: [# 5. 요구사항 목록 > 범위 경계](#5-요구사항-목록)
- 리스크/오픈 질문: [# 6. 리스크/가정 목록](#6-리스크가정-목록)
- 성공 기준: [# 7. 초기 성공 기준](#7-초기-성공-기준)
- 인계 전 확인: [# 8. REQ로 넘기기 전 확인 체크](#8-req로-넘기기-전-확인-체크)
- 사용자 결정 필요: [# 10. 사용자 결정 필요 항목 요약](#10-사용자-결정-필요-항목-요약)
## Freeze 플래그
- Handoff Decision: 승인
- Handoff Rationale: 사용자 승인으로 대시보드 운영 허브 정보구조, `accounts.liquidity_bucket` 권위 소스, 순자산/부채 계산 경계, 이번 달 기준, 비거래 자산 수동 입력 방식이 확정되었으므로 REQ 초안 작성으로 넘긴다.
- Ready for REQ Drafting: true
- Confirmed By: 진환 고
- Confirmed At (KST): 2026-06-29 14:08 KST
docs/discovery/dcy-006_20260630_pytest-apptest-smoke-ci-automation.md
+216
View File
@@ -0,0 +1,216 @@
# 0. 문서 상태
이 문서의 현재 상태와 식별 정보를 기록한다. 문서 추적과 승인 흐름에 필요한 최소 메타데이터를 적는다.
- 상태: confirmed
- 문서 ID: dcy-006_20260630_pytest-apptest-smoke-ci-automation
- 이슈명: pytest/AppTest/Smoke CI 자동화
- 작성 시각(KST): 2026-06-30 13:32
- 마지막 갱신 시각(KST): 2026-06-30 14:42 KST
- 대체됨: 없음
- 후속 Discovery 참조: 없음
- 생성된 REQ 참조: REQ-006 (`docs/srs/Testing/req-006_pytest-apptest-smoke-ci-automation.md`)
# 1. 계획 상태 요약
현재 Discovery가 어떤 배경에서 작성되고 있는지, 연계 문서가 있는지, 지금 시점의 해석이 무엇인지 짧게 요약한다.
- 연계 문서 현황:
- 관련 GitHub Project 항목: https://github.com/users/genichin/projects/4 의 `pytest/AppTest/Smoke CI 자동화` 항목 (Project #4 잔여 작업)
- 선행 Discovery: `docs/discovery/dcy-004_20260629_browser-streamlit-e2e-evidence-recovery.md` (Out of Scope/체크리스트에서 CI 통합을 본 항목으로 분리)
- 해석:
- dcy-004는 로컬 재현 가능한 browser evidence 복구까지로 범위를 한정하고, `pytest/AppTest/Smoke CI 자동화`를 Project #4의 별도 항목으로 명시적으로 분리했다. 본 Discovery는 그 분리된 후속 작업을 독립 주기로 끌어올려 추적한다.
- 현재 저장소에는 pytest 회귀 스위트, Streamlit AppTest, HTTP/DB safety smoke 자산이 이미 존재하지만 이를 강제 실행·게이트화하는 CI 계약(workflow)이 전혀 없다. 본 Discovery는 "이미 있는 검증 자산을 CI로 자동 실행·게이트화하는 계약"을 정의하는 것을 목표로 한다.
# 2. 요구사항 판정 결과
이번 요청이 기존 요구사항과 비교해 신규인지, 유사한지, 중복인지 판단하고 그 근거를 남긴다.
- 판정: 신규
- 근거
- dcy-004는 browser-level evidence 복구와 QC evidence 등급 정의가 중심이며, "검증 자산을 CI에서 자동 실행·게이트화"하는 자동화 계약을 독립 성공 기준으로 다루지 않았다. dcy-004 본문(`# 5 범위 경계`, `# 8 확인 체크`)이 CI 통합을 본 항목으로 명시 분리했다.
- 저장소에 `.github/workflows/`가 존재하지 않고 `docs/project-structure.md`도 "CI workflow and deployment/service management are not yet defined."로 기록한다. 따라서 CI 자동화는 기존 요구사항의 미세 조정이 아니라 신규 governance unit이다.
# 3. 문제점의 요약
문제의 현재 상태, 기대 상태, 관련 이해관계자, 제약사항을 정리한다. Discovery의 핵심 맥락을 가장 먼저 이해할 수 있어야 한다.
- 현재 상태
- CI 계약이 부재하다: 저장소에 `.github/workflows/` 디렉터리 자체가 없어, push/PR 시 자동으로 테스트를 실행·차단하는 게이트가 존재하지 않는다. 검증은 전적으로 작성자/검수관의 수동 로컬 실행에 의존한다. `docs/project-structure.md`도 "CI workflow and deployment/service management are not yet defined."로 명시한다.
- 검증 자산은 이미 풍부하다: pytest 회귀 스위트(`tests/test_categorization.py`, `tests/test_service.py`, `tests/test_backup_workflow.py`, `tests/test_dashboard_app.py` 등 11개 테스트 모듈), `pyproject.toml`의 `[tool.pytest.ini_options]`(testpaths=["tests"], dev extra의 `pytest>=8.0.0`)가 갖춰져 있다. 그러나 이들을 자동 실행하는 외부 계약이 없다.
- AppTest/smoke 자산이 로컬에 묶여 있다: Streamlit `AppTest` 기반 `tests/test_dashboard_app.py`, browser evidence 스크립트 `scripts/streamlit_browser_evidence.py`, DB restore safety smoke `scripts/ledger_restore_smoke.py`가 존재하지만 모두 로컬 수동 실행이 전제다. `docs/project-structure.md`는 "Local browser evidence capture exists ... broader flow coverage and CI automation remain planned."로 이 한계를 기록한다.
- browser evidence가 로컬 한정이다: dcy-004 결과로 `/usr/bin/google-chrome-stable` 기반 로컬 browser evidence 절차는 복구됐으나, 이는 헤드리스 Chrome/snap 가용성에 의존해 CI runner로 그대로 이식하기 어렵다. 따라서 CI 1차 게이트는 browser-screenshot이 아니라 결정적으로 실행 가능한 pytest/AppTest/HTTP/DB safety smoke로 구성해야 한다.
- 기대 상태
- push/PR 시 pytest 회귀 스위트, Streamlit AppTest, HTTP smoke, DB safety smoke가 CI에서 자동 실행되어 합격/불합격이 게이트로 강제된다.
- CI 계약이 문서화된 단일 진입점(workflow 정의)으로 존재하고, 어떤 검증이 blocker이고 어떤 것이 best-effort인지 명확히 구분된다.
- browser-level evidence처럼 환경 의존이 큰 검증은 CI 필수 게이트에서 분리하고, 로컬/수동 evidence 절차(dcy-004)와의 경계가 명확히 정의된다.
- 이해관계자
- 렛저장인(운영자 겸 작성자) — CI workflow를 구성·유지하고 로컬 검증과의 경계를 운영하는 주체
- 검수관/리뷰어 — CI 게이트 결과를 QC gate 판정의 1차 근거로 사용하는 주체
- StagePilot 후속 SDLC(REQ/Batch) 수행자 — 본 Discovery를 CI 자동화 요구사항으로 정제
- 제약사항
- 개인 금융정보를 다루므로 CI 실행 로그·아티팩트에 실계좌번호·잔액·raw_payload·원본 파일명 등 민감정보가 노출되어서는 안 된다. CI 검증은 synthetic fixture를 우선 사용한다.
- CI runner는 헤드리스 browser/snap 가용성이 보장되지 않으므로, browser-screenshot E2E를 CI 필수 게이트로 강제하지 않는다(dcy-004 evidence 등급의 fallback 경로를 CI 맥락에서 재해석).
- DB safety smoke는 운영 DB가 아니라 임시 fixture/검증 DB(dcy-002 절차)에서만 수행하여 원본 데이터를 훼손하지 않아야 한다.
## 주요 사용자 시나리오
사용자 또는 운영자가 실제로 어떤 상황에서 이 변경을 필요로 하는지 대표 시나리오를 적는다.
- 작성자가 분류/서비스/백업 로직을 변경해 PR을 올리면, CI가 pytest 회귀 스위트를 자동 실행하고 실패 시 머지를 차단해 회귀를 조기에 잡는다.
- 작성자가 `dashboard/app.py`를 변경하면, CI가 Streamlit AppTest와 HTTP smoke를 fixture DB로 실행해 대시보드가 기동·렌더링되는지 자동 검증한다.
- 검수관이 batch verification을 작성할 때, CI 게이트 통과 로그를 1차 evidence로 인용하고, browser-screenshot evidence는 환경이 허용하는 로컬 절차(dcy-004)에서 보강한다.
- 백업/복구 로직을 변경하면, CI가 DB safety smoke(`scripts/ledger_restore_smoke.py` 계열)를 임시 fixture DB로 실행해 복구 절차가 운영 DB를 건드리지 않고 통과하는지 확인한다.
# 4. 이번에 정의할 변경
이번 Discovery에서 다루는 핵심 변경 항목을 목록으로 적는다. 기능, 구조, 규칙 변경을 함께 포함해도 된다.
- pytest 회귀 스위트를 push/PR에서 자동 실행하는 CI 계약(workflow)을 신설한다. 어떤 이벤트에서 어떤 job이 실행되고 무엇이 머지 blocker인지 정의한다.
- Streamlit AppTest와 HTTP smoke, DB safety smoke를 CI job으로 자동화한다. 모두 synthetic fixture/임시 검증 DB에서 결정적으로 실행되도록 표준화한다.
- CI 필수 게이트와 환경 의존 검증(browser-screenshot E2E)의 경계를 규칙으로 정의한다. browser evidence는 CI 필수 게이트에서 분리하고 로컬 절차(dcy-004)와의 역할을 문서화한다.
- CI 계약과 검증 job 구조를 baseline 문서에 반영한다: `docs/project-structure.md`의 "CI workflow ... not yet defined" 항목을 갱신하고, `docs/runtime-flows.md`에 CI 검증 흐름을 추가할 필요를 명시한다.
## 영향 범위
변경이 미칠 코드/문서/운영 범위를 명시해 REQ 정제와 batch planning에서 추정 누락을 줄인다.
- 코드 영향:
- `.github/workflows/` — CI workflow 정의 신설(파일 경로/이름은 REQ/Batch에서 확정). pytest, AppTest, HTTP smoke, DB safety smoke job 구성.
- `scripts/` — 기존 `ledger_restore_smoke.py`, `streamlit_browser_evidence.py`를 CI에서 호출 가능한 결정적 진입점으로 재사용/래핑할 가능성. HTTP smoke 전용 헬퍼 신설 여부는 후속 범위.
- `tests/` — 기존 pytest/AppTest 자산은 보존. CI에서 fixture DB를 결정적으로 준비하는 공용 유틸 추가 가능성.
- `pyproject.toml` — CI 실행에 필요한 dev/dashboard extra 설치 경계 확인(이미 `dev`=pytest, `dashboard`=streamlit/pandas/plotly 존재).
- 문서 영향:
- `docs/project-structure.md` — "CI workflow and deployment/service management are not yet defined." 및 "CI automation remain planned." 항목 갱신.
- `docs/runtime-flows.md` — CI 검증 흐름(이벤트 → job → 게이트 결과) 추가.
- `docs/interface-contract.md` — CI 게이트 결과를 QC evidence로 인용하는 기준 반영 검토.
- `docs/runbooks/` — CI 실패 대응/로컬 재현 runbook 후보.
- 운영 영향:
- push/PR마다 자동 검증이 실행되어 수동 로컬 실행 의존도가 낮아진다.
- QC gate 운영에서 CI 통과 로그가 1차 evidence로 표준화되고, browser evidence는 환경 허용 시 보강 증거로 운영된다.
# 5. 요구사항 목록
실제로 구현과 검증으로 이어질 요구사항을 기능/비기능으로 나누어 정리하고, 범위 경계를 명확히 적는다.
## 기능 요구사항
- FR-1: push/PR 이벤트에서 pytest 회귀 스위트(`testpaths=["tests"]`)를 자동 실행하고, 실패 시 머지 blocker로 동작하는 CI workflow를 제공해야 한다.
- FR-2: Streamlit `AppTest`(`tests/test_dashboard_app.py` 계열)와 대시보드 HTTP smoke(고정 포트로 기동 후 HTTP 200 확인)를 synthetic fixture DB로 CI에서 자동 실행해야 한다.
- FR-3: DB safety smoke(`scripts/ledger_restore_smoke.py` 계열)를 임시 fixture/검증 DB에서 CI job으로 실행하여, 복구 절차가 원본 운영 DB를 건드리지 않고 통과하는지 자동 검증해야 한다.
- FR-4: CI 필수 게이트(pytest/AppTest/HTTP/DB safety smoke)와 환경 의존 검증(browser-screenshot E2E)을 명확히 구분하고, browser evidence는 CI 필수 게이트에서 제외하되 로컬 절차(dcy-004)와의 역할을 문서화해야 한다.
- FR-5: CI 계약과 검증 job 구조를 `docs/project-structure.md`와 `docs/runtime-flows.md`에 반영하고("CI workflow ... not yet defined" 항목 갱신), 필요 시 CI 실패 대응 runbook 후보를 `docs/runbooks/`에 추가해야 한다.
## 비기능 요구사항
성능, 운영성, 일관성, 자동화 안정성 등 기능 외 요구사항을 적는다.
- NFR-1: CI 검증은 결정적이어야 한다. 동일 커밋에 대해 동일 결과를 산출하도록 synthetic fixture·고정 포트/경로·로드 완료 대기 조건을 표준화한다(flaky job 최소화).
- NFR-2: CI 로그·아티팩트에 실계좌번호·잔액·raw_payload·원본 파일명·비밀번호 등 민감정보가 평문으로 노출되어서는 안 되며, 모든 CI 검증은 synthetic fixture를 우선 사용한다.
- NFR-3: CI는 운영 DB를 절대 사용하지 않고 임시 fixture/검증 DB(dcy-002 절차)에서만 동작하여 원본 데이터 훼손 위험이 없어야 한다.
- NFR-4: CI runner의 browser/snap 가용성에 의존하지 않고도 필수 게이트가 통과 가능해야 한다(headless browser는 best-effort, 필수 게이트는 pytest/AppTest/HTTP/DB safety smoke).
## 범위 경계
이번 반복에서 반드시 포함할 범위와 명시적으로 제외할 범위를 구분한다.
- In Scope
- pytest 회귀 스위트, Streamlit AppTest, 대시보드 HTTP smoke, DB safety smoke를 push/PR에서 자동 실행하는 CI 계약 정의
- CI 필수 게이트와 환경 의존(browser) 검증의 경계 규칙 정의 및 baseline 문서 반영
- synthetic fixture 우선·민감정보 금지·운영 DB 미사용 원칙의 CI 적용
- Out of Scope
- browser-screenshot/visual regression의 CI 필수 게이트화(환경 의존이 커 best-effort로만 검토). 로컬 browser evidence는 dcy-004 범위로 유지.
- 배포/릴리스 자동화(CD), 외부 호스팅/서비스 운영 도입. 본 반복은 검증 CI 게이트까지로 한정.
- 테스트 커버리지 목표치 강제, 성능 벤치마크 게이트 같은 고도화 품질 게이트는 후속 반복으로 분리.
- CI 플랫폼은 GitHub Actions로 고정하고, 기본 트리거는 `pull_request`와 `main` 대상 `push`, 선택 경로는 `workflow_dispatch`로 둔다.
# 6. 리스크/가정 목록
불확실성과 전제 조건을 분리해서 적는다. 리스크는 영향과 완화 방안을, 가정은 현재 판단의 전제를 기록한다.
## 리스크
- R-1 (Medium): Streamlit AppTest/HTTP smoke가 동적 렌더링·비동기 로딩으로 CI에서 비결정적으로 실패(flaky)하면 게이트 신뢰도가 떨어진다.
- 완화 방안: 결정적 synthetic fixture DB, 고정 포트, 기동 후 readiness 대기(HTTP 200 폴링) 조건을 표준화하고, 재시도/타임아웃 정책을 명시한다.
- R-2 (Medium): CI 실행 중 fixture 준비나 로그 출력에 실데이터/민감정보가 섞이면 외부 CI 로그에 평문 노출될 수 있다.
- 완화 방안: 모든 CI 검증을 synthetic fixture로 고정하고 운영 DB 경로 접근을 차단한다. 로그/아티팩트 마스킹 및 민감 필드 공란 원칙을 검증 단계에 포함한다.
- R-3 (Low): browser evidence를 CI 필수 게이트로 무리하게 끌어들이면 runner 환경 제약으로 게이트가 상시 실패할 수 있다.
- 완화 방안: browser-screenshot E2E를 필수 게이트에서 제외하고 best-effort/로컬 절차로 분리하는 경계 규칙을 명시한다.
## 가정
아직 확정되지 않았지만 현재 문서 작성의 기반이 되는 전제를 적는다.
- A-1: 기존 pytest 스위트, `tests/test_dashboard_app.py`의 AppTest, `scripts/ledger_restore_smoke.py`, `scripts/streamlit_browser_evidence.py` 자산을 CI에서 재사용 가능한 형태로 호출할 수 있다.
- A-2: CI 필수 게이트는 headless browser 없이도 pytest/AppTest/HTTP smoke/DB safety smoke만으로 의미 있는 회귀 보호를 제공한다.
- A-3: DB safety smoke와 fixture 준비는 dcy-002의 백업·검증 DB 절차가 운영 가능한 상태임을 전제로 임시/복사본 DB에서 수행한다.
- A-4: synthetic fixture만으로 핵심 import/분류/대시보드 경로의 CI 검증이 가능하며, 실데이터 없이도 회귀를 충분히 포착할 수 있다.
## 오픈 질문
답을 아직 모르는 항목을 적는다. 추정으로 덮지 말고 REQ 초안 작성 이전에 확인할 질문으로 남긴다.
- OQ-1: CI 실행 플랫폼과 트리거 범위를 무엇으로 확정할 것인가(GitHub Actions push/PR vs 수동 dispatch vs 로컬 pre-commit 병행)?
- 상태: Answered
- 답변: GitHub Actions를 기본 CI 플랫폼으로 사용하고, `pull_request`와 `main` 대상 `push`를 기본 트리거로 하며 `workflow_dispatch`를 선택적 수동 재실행 경로로 허용한다.
- 반영 메모: REQ acceptance criteria에는 PR 기준 필수 게이트와 `main` push 재실행 기준, 선택적 수동 실행 허용을 포함한다.
- OQ-2: HTTP smoke와 DB safety smoke를 기존 `scripts/` 자산을 그대로 CI에서 호출할지, CI 전용 결정적 진입점으로 별도 래핑할지?
- 상태: Answered
- 답변: 기존 `scripts/`와 테스트 자산의 내부 로직은 재사용하되, CI에서는 종료코드·인자·로그가 결정적인 얇은 wrapper entrypoint를 별도로 둔다.
- 반영 메모: REQ/Batch 설계 시 smoke job은 CI 전용 wrapper를 표준 진입점으로 사용하고, 기존 자산은 내부 구현으로 재사용한다.
# 7. 초기 성공 기준
이 변경이 성공했다고 판단할 기준을 측정 가능하게 정의한다. 가능하면 데이터 출처까지 연결한다.
- S-1: push/PR 이벤트에서 pytest 회귀 스위트가 CI로 자동 실행되고, 의도적으로 깨진 변경에 대해 게이트가 머지를 차단함을 재현 가능하게 확인한다.
- S-2: Streamlit AppTest, HTTP smoke, DB safety smoke가 synthetic fixture/임시 검증 DB로 CI에서 통과하고, 실행 로그·아티팩트에 민감정보가 노출되지 않음을 확인한다.
- S-3: CI 필수 게이트와 browser evidence 경계, CI 검증 흐름이 `docs/project-structure.md`("CI workflow ... not yet defined" 갱신)와 `docs/runtime-flows.md`에 반영되어 후속 REQ/Batch에서 참조 가능하다.
## 측정 방식 및 데이터 출처
각 성공 기준을 어떻게 측정할지와 어떤 데이터나 문서를 근거로 쓸지 적는다.
- S-1 측정 방식: CI 실행 결과(성공/실패) 로그와, 의도적 회귀 주입 시 게이트가 fail하는지 재현 확인 / 데이터 출처: CI workflow 실행 로그, pytest 결과
- S-2 측정 방식: AppTest/HTTP/DB safety smoke job의 통과 로그 확인 및 로그·아티팩트의 민감정보 미노출 검수 / 데이터 출처: CI job 로그·아티팩트, synthetic fixture DB
- S-3 측정 방식: baseline 문서 갱신 및 CI 검증 흐름 반영 여부 리뷰 / 데이터 출처: `docs/project-structure.md`, `docs/runtime-flows.md`, `docs/runbooks/`
# 8. REQ로 넘기기 전 확인 체크
REQ 초안 작성 단계로 넘기기 전에 무엇이 확정되어야 하는지 확인한다. 미완료 항목은 후속 결정이 필요함을 뜻한다.
- [x] 범위(In Scope/Out of Scope) 확정
- 기준: 본 반복은 검증 CI 게이트(pytest/AppTest/HTTP/DB safety smoke)까지로 한정하고 CD·visual regression·커버리지 게이트는 제외한다는 점을 사용자가 확인한다.
- [x] 성공 지표의 측정 방식/데이터 출처 확정
- 기준: CI 실행 로그·아티팩트·synthetic fixture가 acceptance criteria의 측정 근거로 확정된다.
- [ ] High 영향 리스크 우선순위 및 해소 책임자 지정
- 기준: flaky 위험(R-1)과 민감정보 노출(R-2) 완화 책임자를 지정한다. 본 Discovery에 현재 High 리스크는 없으나 R-1/R-2를 우선 관리한다.
- [x] 모든 오픈 질문(OQ) `Open` 상태 없음 확인
- 기준: OQ-1(CI 플랫폼/트리거), OQ-2(smoke 진입점 재사용 vs 래핑)가 모두 Answered로 정리되었다.
- [x] Freeze 확정 담당자(CONFIRMED_BY) 지정
- 기준: 사용자(진환 고)가 권장안을 승인했다.
# 9. 파일 처리 결과
이 Discovery 문서 생성/갱신 결과와 참조 문서를 기록한다. 이후 추적과 리뷰 시 근거로 사용한다.
- 처리 결과: 생성
- 생성 경로: docs/discovery/dcy-006_20260630_pytest-apptest-smoke-ci-automation.md
- 참조 문서:
- docs/discovery/dcy-004_20260629_browser-streamlit-e2e-evidence-recovery.md
- docs/project-structure.md
- docs/runtime-flows.md
- stage-pilot/templates/project-structure.md
- stage-pilot/templates/runtime-flows.md
# 10. 사용자 결정 필요 항목 요약
사용자나 승인자가 결정해야 하는 항목만 모아 정리한다. 결정, 확인, 데이터 요청을 구분해서 적는다.
## DECIDE
- CI 플랫폼은 GitHub Actions를 사용한다. 기본 트리거는 `pull_request`와 `main` 대상 `push`이며, `workflow_dispatch`는 선택적 수동 재실행 경로로 허용한다.
- HTTP smoke/DB safety smoke는 기존 `scripts/`와 테스트 자산을 내부적으로 재사용하되, CI에서는 종료코드·인자·로그가 결정적인 얇은 wrapper entrypoint를 표준으로 사용한다.
## CONFIRM
- CI 필수 게이트는 `pytest`, `Streamlit AppTest`, `HTTP smoke`, `DB safety smoke`로 한정한다. browser-screenshot E2E는 필수 차단 게이트에 넣지 않고 로컬 보강 evidence 절차(dcy-004)로 유지한다.
## DATA
- CI는 매 실행 시 생성되는 synthetic fixture DB만 사용한다. 운영 DB는 사용하지 않으며 실계좌번호·실잔액·`raw_payload`·원본 파일명·비밀번호는 포함하지 않는다.
- synthetic fixture DB는 계좌/거래/확인필요 큐/월간 현금흐름/복구 smoke가 모두 재현 가능한 최소 결정적 샘플 세트를 포함하고, runner temp 경로 또는 동등한 임시 경로에 생성한다.
# 11. Discovery Freeze
REQ 초안 작성 인계 시점의 확정 플래그와 섹션 참조만 기록한다. 내용 재작성 없이 원본 섹션을 링크로 대신한다.
## 섹션 참조
- 범위: [# 5. 요구사항 목록 > 범위 경계](#5-요구사항-목록)
- 리스크/오픈 질문: [# 6. 리스크/가정 목록](#6-리스크가정-목록)
- 성공 기준: [# 7. 초기 성공 기준](#7-초기-성공-기준)
- 인계 전 확인: [# 8. REQ로 넘기기 전 확인 체크](#8-req로-넘기기-전-확인-체크)
- 사용자 결정 필요: [# 10. 사용자 결정 필요 항목 요약](#10-사용자-결정-필요-항목-요약)
## Freeze 플래그
- Handoff Decision: 승인
- Handoff Rationale: 사용자가 권장 기본안(GitHub Actions + CI 전용 얇은 smoke wrapper + pytest/AppTest/HTTP/DB safety smoke 필수 게이트 + synthetic fixture DB 정책)을 승인해 사람 결정 항목이 해소되었다. 남은 책임자 지정은 REQ/Batch planning 단계에서 할당 가능한 운영 항목이며 Discovery confirm을 막지 않는다.
- Ready for REQ Drafting: true
- Confirmed By: 진환 고
- Confirmed At (KST): 2026-06-30 13:54 KST
docs/discovery/index.md
+4
View File
@@ -8,3 +8,7 @@
|---|---|---|---|---|
| dcy-001_20260626_streamlit-ux-e2e-categorization-refund-workflows | 20260626 | Streamlit 운영 UX/E2E 검증 및 분류·환급 워크플로우 안정화 | [Discovery](./dcy-001_20260626_streamlit-ux-e2e-categorization-refund-workflows.md) | approved |
| dcy-002_20260627_operational-safety-backup-restore-validation-db | 20260627 | Jarca Ledger 운영 안전장치 및 백업·복구·검증 DB 워크플로우 정립 | [Discovery](./dcy-002_20260627_operational-safety-backup-restore-validation-db.md) | confirmed |
| dcy-003_20260629_statement-unavailable-manual-evidence-balance-reconciliation | 20260629 | Statement-unavailable 계좌 수동 증빙 및 잔액대조 워크플로우 정립 | [Discovery](./dcy-003_20260629_statement-unavailable-manual-evidence-balance-reconciliation.md) | confirmed |
| dcy-004_20260629_browser-streamlit-e2e-evidence-recovery | 20260629 | Browser/Streamlit E2E evidence 환경 복구 및 QC evidence 기준 강화 | [Discovery](./dcy-004_20260629_browser-streamlit-e2e-evidence-recovery.md) | confirmed |
| dcy-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow | 20260629 | Jarca Ledger 대시보드 운영 허브 사양 정립 (이번 달 현금흐름 + 자산 유동성 + 운영 미처리) | [Discovery](./dcy-005_20260629_dashboard-operations-hub-liquidity-monthly-cashflow.md) | confirmed |
| dcy-006_20260630_pytest-apptest-smoke-ci-automation | 20260630 | pytest/AppTest/Smoke CI 자동화 | [Discovery](./dcy-006_20260630_pytest-apptest-smoke-ci-automation.md) | confirmed |