jarca-ledger-mcp/docs/discovery/dcy-002_20260627_operational-safety-backup-restore-validation-db.md

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

- 상태: confirmed
- 문서 ID: dcy-002_20260627_operational-safety-backup-restore-validation-db
- 이슈명: Jarca Ledger 운영 안전장치 및 백업·복구·검증 DB 워크플로우 정립
- 작성 시각(KST): 2026-06-27 00:06
- 마지막 갱신 시각(KST): 2026-06-27 10:17
- 대체됨: 없음
- 후속 Discovery 참조: 없음
- 생성된 REQ 참조: REQ-002 (`docs/srs/Non-Functional/req-002_operational-safety-backup-restore-validation-db.md`)

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

- 연계 문서 현황:
	- 관련 점수 파일: 미생성
	- 관련 TODO/메모: 없음
- 해석:
	- dcy-001의 BAT-001은 분류 규칙 운영 액션을 작은 단위로 안정화했고, 검증 과정에서 synthetic DB와 기본 DB mtime 확인을 대체 smoke evidence로 사용했다.
	- 이번 Discovery는 이후 import, rollback, categorization, reconciliation 같은 위험 작업을 원본 운영 DB 훼손 없이 진행하기 위한 백업·복구·검증 DB 표준 워크플로우를 정의한다.

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

- 판정: 신규
- 근거
	- dcy-001은 Streamlit 운영 UX/E2E와 분류·환급 workflow 안정화가 중심이고, 백업/복구/검증 DB 운용 체계 자체를 독립 성공 기준으로 다루지 않는다.
	- `docs/runtime-flows.md`, `docs/data-model.md`에는 destructive migration 회피와 백업 승인 필요성이 gap/constraint로만 기록되어 있어 별도 Discovery로 운영 안전장치를 추적하는 것이 명확하다.

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

- 현재 상태
	- 기본 SQLite DB는 `~/.local/share/jarca/ledger.sqlite3`이며 `JARCA_LEDGER_DB_PATH`로 대체 가능하다. `db.py`는 DB path resolution과 schema initialization을 담당하지만, 운영 DB 백업/복구 workflow는 아직 명시적 기능이나 runbook으로 정리되어 있지 않다.
	- Streamlit Import 화면에는 import batch rollback UI가 있고, service/server에는 import rollback 도구가 있지만, rollback 전후 백업 생성, 검증용 DB copy, 원본 DB 미변경 증거, restore smoke check가 일관된 acceptance criteria로 묶여 있지 않다.
- 기대 상태
	- 운영자는 import, rollback, 대량 categorization, reconciliation, schema 변경 전후에 표준화된 백업·검증 DB 절차를 따라 원본 운영 DB 훼손 위험을 낮출 수 있다.
	- 렛저장인과 검수관은 REQ/BAT 수행 시 어떤 DB를 사용했는지, 원본 DB를 직접 건드리지 않았는지, 복구 가능한 백업이 있는지, smoke check가 통과했는지를 동일한 evidence 형식으로 검증할 수 있다.
- 이해관계자
	- Jarca Ledger 운영자: 실제 가계부 운영 DB를 안전하게 유지해야 하는 사용자
	- Jarca/Hermes Agent: DB 변경 작업과 검증을 보조하고 승인/중단 기준을 판단하는 자동화 주체
	- 렛저장인/검수관: 구현과 verification gate를 분담하는 profile subagents
	- 프로젝트 유지보수자: SQLite schema, service layer, Streamlit UI, 운영 문서를 유지하는 개발 주체
- 제약사항
	- 실제 금융 DB, 원본 PDF/XLS/XLSX/CSV, 비밀번호, 전체 계좌식별정보는 테스트·문서·커밋에 노출하지 않는다.
	- 파괴적 SQLite migration, 원본 운영 DB 직접 mutation, 대량 data rewrite는 사용자 명시 승인 없이는 진행하지 않는다.

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

- 운영자가 새 KB/Toss/SeoulPay 자료를 import하기 전에 운영 DB 백업을 만들고, 검증 DB copy에서 preview/import/rollback smoke를 먼저 실행한다.
- 운영자가 분류 규칙 apply나 확인필요 큐 정리처럼 여러 거래를 바꿀 수 있는 작업을 하기 전에 원본 DB hash/mtime/row count를 기록하고, 변경 후 보고서와 DB 상태를 비교한다.
- 렛저장인이 batch 구현을 완료하면 검수관이 backup 존재 여부, 검증 DB 사용 여부, 원본 DB 미변경 증거, restore/health check 결과를 확인한 뒤 PASS/BLOCKED를 판단한다.

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

- 운영 DB 변경 전 백업 생성, 검증 DB copy 생성, 복구 절차, smoke check를 하나의 표준 workflow로 정의한다.
- import, rollback, categorization, reconciliation, migration 같은 위험 작업의 사전/사후 체크리스트와 검수관 evidence 기준을 정의한다.
- `docs/runtime-flows.md`, `docs/data-model.md`, 필요 시 별도 runbook 또는 utility script를 갱신해 운영자가 재현 가능한 명령 단위 절차를 갖도록 한다.

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

- 코드 영향:
	- `jarca_ledger_mcp/db.py`: 필요 시 백업/복사/검증 DB 경로 helper 또는 안전 검사 helper 추가 후보.
	- `jarca_ledger_mcp/service.py` / `server.py`: 필요 시 백업/health/smoke 관련 additive tool 또는 service function 추가 후보.
	- `dashboard/app.py`: 필요 시 운영 DB 위험 작업 전 안내, 검증 DB 사용 안내, import/rollback 전 안전 상태 표시 추가 후보.
	- `scripts/` 또는 `tests/`: 백업/복구/검증 DB smoke를 재현하는 utility와 regression 추가 후보.
- 문서 영향:
	- `docs/runtime-flows.md`: 운영 DB 백업·복구·검증 DB workflow와 위험 작업 flow constraint 갱신.
	- `docs/data-model.md`: SQLite persistence/backup/restore policy와 destructive migration 승인 조건 갱신.
	- `docs/interface-contract.md`: 새 MCP tool 또는 dashboard action이 생길 경우 additive interface contract 갱신.
	- 후속 REQ/BAT 문서: backup, DB copy, restore smoke, QC evidence acceptance criteria 기록.
- 운영 영향:
	- 실제 운영 DB를 대상으로 하는 작업은 백업 또는 검증 DB copy 확인 후 진행한다.
	- 검수관은 batch verification에서 원본 DB 직접 mutation 여부와 복구 가능성을 evidence로 확인한다.

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

## 기능 요구사항
- FR-1: 운영 DB 변경 전 timestamped backup을 생성하고, 생성 경로·파일 크기·hash 또는 mtime 같은 식별 정보를 evidence로 남길 수 있어야 한다.
- FR-2: 검증용 DB copy 또는 synthetic fixture DB를 생성/선택하는 절차가 있어야 하며, Streamlit/MCP/pytest 검증이 해당 DB를 사용했음을 확인할 수 있어야 한다.
- FR-3: backup에서 restore하는 절차와 restore 후 `ledger_health_check` 또는 동등한 smoke check를 정의해야 한다.
- FR-4: import, rollback, categorization apply, reconciliation, migration 전후에 사용할 안전 체크리스트와 검수관 gate evidence 형식을 정의해야 한다.
- FR-5: 이번 Discovery가 확정하는 운영 flow는 `docs/runtime-flows.md`와 필요 시 `docs/data-model.md`에 반영되어야 한다.

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

- NFR-1: 원본 운영 DB 직접 mutation은 기본 금지이며, 불가피한 경우 사용자 명시 승인과 백업 evidence가 필요하다.
- NFR-2: 백업/검증/복구 절차는 민감정보를 노출하지 않는 방식으로 문서화되어야 하며, 원본 금융 파일·비밀번호·전체 계좌식별정보를 커밋하지 않는다.
- NFR-3: 기존 MCP tool 성공 응답 shape와 `cashflow_kind` 의미론은 보존하고, 새 도구나 응답 필드는 additive 방식으로 설계한다.
- NFR-4: 절차는 렛저장인과 검수관이 자동화 또는 반자동으로 반복 실행할 수 있을 만큼 명령어 단위로 재현 가능해야 한다.

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

- In Scope
	- 운영 DB 백업 생성 정책, 검증 DB copy/synthetic fixture 정책, restore smoke check 정의.
	- 위험 작업 전후 체크리스트와 검수관 QC evidence 기준 정의.
	- 필요한 경우 작은 additive helper/script/tool 및 문서 갱신.
	- dcy-001 후속 batch에서 사용할 수 있는 DB safety verification pattern 정립.
- Out of Scope
	- 신규 금융기관 parser 추가.
	- 파괴적 SQLite schema migration 또는 대량 데이터 rewrite 실행.
	- CI/CD 전체 구축과 배포 서비스화.
	- 원본 금융 파일 보관 정책 전체와 장기 암호화 저장소 설계.
	- 운영 DB의 실제 복구 실행. 실제 복구는 별도 사용자 승인 후 수행한다.

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

## 리스크
- R-1 (High): 백업/복구 절차 자체가 잘못 설계되면 운영 DB 손상 시 복구할 수 없거나 잘못된 DB를 복구할 수 있다.
	- 완화 방안: synthetic fixture 또는 운영 DB copy에서 먼저 backup/restore smoke를 검증하고, 원본 DB restore는 사용자 승인 전까지 실행하지 않는다.
- R-2 (High): 검증 과정에서 실수로 기본 운영 DB를 대상으로 import, rollback, apply 작업을 실행할 수 있다.
	- 완화 방안: `JARCA_LEDGER_DB_PATH` 명시, DB path evidence, 원본 DB mtime/hash/row count 확인, 검수관 gate를 acceptance criteria에 포함한다.
- R-3 (Medium): 백업 파일이나 검증 DB copy에 민감 금융정보가 포함되어 커밋 또는 로그에 노출될 수 있다.
	- 완화 방안: 백업/DB copy는 git ignored 경로에 두고, 보고서에는 파일 경로·크기·hash 등 최소 메타데이터만 남긴다.

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

- A-1: Jarca Ledger는 현재 로컬 SQLite 중심 운영이며, 기본 운영 DB는 `/root/.local/share/jarca/ledger.sqlite3`이다.
- A-2: 운영 안전장치는 먼저 문서/스크립트/작은 additive helper 중심으로 구현하며, 파괴적 migration framework는 이번 범위에서 제외한다.
- A-3: 검수관은 실제 browser evidence가 불가능할 때도 AppTest, HTTP 200, service/DB smoke, hash/mtime evidence 같은 대체 증거를 평가할 수 있다.

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

- OQ-1: 운영 DB backup 파일의 기본 보관 위치와 보관 기간을 어디로 둘지 결정해야 한다.
	- 상태: Answered
	- 처리 방안: 기본 백업 위치는 `/root/.local/share/jarca/backups/ledger/`, 보관 정책은 최근 30일 또는 최근 20개 백업 유지로 확정한다.
	- 종료 조건: REQ acceptance criteria 또는 runbook에 해당 위치와 retention 정책을 반영한다.
- OQ-2: 백업/복구 기능을 MCP tool로 노출할지, 로컬 script/runbook으로만 둘지 결정해야 한다.
	- 상태: Answered
	- 처리 방안: 혼합 방식으로 확정한다. Backup 생성과 backup 목록/status/hash 확인은 MCP tool 또는 script를 허용하되, restore 실행은 MCP tool로 노출하지 않고 script/runbook과 사용자 명시 승인으로 제한한다.
	- 종료 조건: 후속 REQ 범위에 backup/status 노출과 restore 비노출 원칙을 명시한다.
- OQ-3: 운영 DB copy를 사용하는 검증에서 어떤 수준의 masking 또는 hash-only 보고를 요구할지 결정해야 한다.
	- 상태: Answered
	- 처리 방안: 검증 보고에는 DB 파일 경로, 파일 크기, mtime, sha256/checksum, 주요 table row count, category/report aggregate total, 테스트/health check 결과만 허용한다. 거래 원문, merchant/counterparty 전체 dump, 계좌번호, raw_payload, 원본 금융 파일 내용은 금지한다.
	- 종료 조건: 후속 REQ 또는 verification template에 hash/mtime/row count/aggregate 중심 evidence 정책을 반영한다.

### 오픈 질문 처리 기준
- `Open`: 아직 답이 없고 다음 단계 진행에 영향이 있는 상태다. 문서에 유지한다.
- `Answered`: 답이 확정된 상태다. 관련 본문/요구사항에 반영한 뒤 오픈 질문 목록에서는 제거하거나 resolved 기록으로 이동한다.
- `Deferred`: 지금 단계에서 결정하지 않고 다음 단계 또는 후속 이슈로 넘기는 상태다. 넘길 대상과 이유를 반드시 적는다.
- `Dropped`: 더 이상 유효하지 않은 질문이다. 삭제 사유를 짧게 남기고 목록에서 제거한다.
- 처리 원칙 1: 질문만 남기지 말고 반드시 `상태`, `처리 방안`, `종료 조건`을 함께 적는다.
- 처리 원칙 2: 답이 나온 질문은 본문 반영 없이 단순 삭제하지 않는다. 반영 위치를 먼저 갱신한다.
- 처리 원칙 3: High 영향 질문은 `Deferred` 처리 후 처리 방안에 REQ 인계 추적 방식을 명시한다.

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

- S-1: 운영 DB 백업 생성과 검증 DB copy 생성 절차가 명령어 또는 함수 단위로 재현 가능하고, 원본 DB를 직접 변경하지 않았다는 evidence를 남길 수 있다.
- S-2: backup restore 절차와 restore 후 health/smoke check가 synthetic fixture 또는 DB copy에서 성공한다.
- S-3: import, rollback, categorization apply, reconciliation, migration에 대한 위험 작업 체크리스트가 후속 REQ/BAT와 검수관 gate에서 사용할 수 있는 형식으로 정리된다.
- S-4: `docs/runtime-flows.md`와 필요 시 `docs/data-model.md`가 운영 안전장치 flow를 반영한다.

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

- S-1 측정 방식: backup/copy command 실행 결과, 파일 존재·크기·hash/mtime, 원본 DB mtime/hash 비교 / 데이터 출처: synthetic fixture DB 또는 운영 DB copy metadata
- S-2 측정 방식: restore 후 `ledger_health_check`, sqlite integrity check, pytest 또는 service smoke 결과 확인 / 데이터 출처: 복구된 검증 DB와 command output
- S-3 측정 방식: 후속 REQ acceptance criteria와 BAT verification checklist에 위험 작업 evidence 항목 존재 여부 확인 / 데이터 출처: `docs/srs/`, `docs/batches/`, 검수관 gate report
- S-4 측정 방식: baseline 문서 diff와 change log 확인 / 데이터 출처: `docs/runtime-flows.md`, `docs/data-model.md`, 필요 시 `docs/interface-contract.md`

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

- [x] 범위(In Scope/Out of Scope) 확정
	- 기준: 운영 안전장치/백업/복구/검증 DB에 집중하고 신규 parser, CI/CD, 배포 서비스화, 파괴적 migration은 제외하는지 확인한다.
- [x] 성공 지표의 측정 방식/데이터 출처 확정
	- 기준: synthetic fixture 또는 DB copy 기반의 backup/copy/restore/smoke evidence 방식이 충분한지 확인한다.
- [x] High 영향 리스크 우선순위 및 해소 책임자 지정
	- 기준: 원본 운영 DB mutation과 잘못된 restore 리스크에 대해 자르카/렛저장인/검수관의 책임 경계를 지정한다.
- [x] 모든 오픈 질문(OQ) `Open` 상태 없음 확인
	- 기준: OQ 목록에 `Open` 상태 항목이 0개이거나, 잔여 항목 전부 `Deferred` 처리 완료
- [x] Freeze 확정 담당자(CONFIRMED_BY) 지정
	- 기준: 사용자가 Discovery 내용을 확인하고 REQ draft 진행 가능 여부를 명시한다.

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

- 처리 결과: 생성
- 생성 경로: docs/discovery/dcy-002_20260627_operational-safety-backup-restore-validation-db.md
- 참조 문서:
	- docs/discovery/dcy-001_20260626_streamlit-ux-e2e-categorization-refund-workflows.md
	- docs/runtime-flows.md
	- docs/data-model.md
	- docs/interface-contract.md
	- docs/batches/bat-001_20260626_category-rule-ops/verification.md

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

## DECIDE
- 운영 DB backup 기본 저장 위치는 `/root/.local/share/jarca/backups/ledger/`, 보관 정책은 최근 30일 또는 최근 20개 백업 유지로 확정한다.
- 백업/복구 인터페이스는 혼합 방식으로 확정한다. Backup 생성과 목록/status/hash 확인은 MCP tool 또는 script를 허용하고, restore 실행은 MCP tool로 노출하지 않으며 script/runbook과 사용자 명시 승인으로 제한한다.
- 운영 DB copy 검증 보고에는 파일 경로, 크기, mtime, checksum, 주요 table row count, category/report aggregate, 테스트/health check 결과만 허용하고 거래 상세·계좌번호·raw_payload·원본 금융 파일 내용은 금지한다.

## CONFIRM
- 이번 Discovery는 운영 안전장치·백업·복구·검증 DB workflow로 한정하고 신규 parser, CI/CD, 배포 서비스화, 파괴적 migration은 제외하는 것으로 확정한다.
- 사용자 승인에 따라 REQ draft로 넘긴다.

## DATA
- 1차 검증은 synthetic fixture DB를 우선 사용하고, 필요 시 운영 DB copy를 repo 밖 임시/백업 디렉터리에 생성해 사용한다. 운영 DB copy evidence는 hash, mtime, row count, aggregate만 기록한다.

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

## 섹션 참조
- 범위: [# 5. 요구사항 목록 > 범위 경계](#5-요구사항-목록)
- 리스크/오픈 질문: [# 6. 리스크/가정 목록](#6-리스크가정-목록)
- 성공 기준: [# 7. 초기 성공 기준](#7-초기-성공-기준)
- 인계 전 확인: [# 8. REQ로 넘기기 전 확인 체크](#8-req로-넘기기-전-확인-체크)
- 사용자 결정 필요: [# 10. 사용자 결정 필요 항목 요약](#10-사용자-결정-필요-항목-요약)

## Freeze 플래그
- Handoff Decision: 승인
- Handoff Rationale: 사용자 승인으로 백업 위치/보관 기간, 백업·복구 인터페이스 수준, 검증 DB evidence 수준, 범위 경계가 확정되었으므로 REQ 초안 작성으로 넘긴다.
- Ready for REQ Drafting: true
- Confirmed By: 사용자 + Jarca
- Confirmed At (KST): 2026-06-27 10:12