gitea-impl-agent/jarca-ledger-mcp
1
0
Fork 0
forked from jsfamily/jarca-ledger-mcp
Code Pull Requests Activity
Files
2ccfc9c064963850aaeb232dd4795084b9559d84
jarca-ledger-mcp/docs/discovery/dcy-002_20260627_operational-safety-backup-restore-validation-db.md
T
Jarca 67d8d4871b feat: add ledger backup safety workflow 
confirm dcy-002 and add REQ/BAT evidence

add ledger backup/status metadata workflow

document restore as runbook/script-only guarded operation

add synthetic DB backup/restore smoke tests
2026-06-27 10:40:06 +09:00

19 KiB
Raw Blame History

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

  • 범위(In Scope/Out of Scope) 확정
    • 기준: 운영 안전장치/백업/복구/검증 DB에 집중하고 신규 parser, CI/CD, 배포 서비스화, 파괴적 migration은 제외하는지 확인한다.
  • 성공 지표의 측정 방식/데이터 출처 확정
    • 기준: synthetic fixture 또는 DB copy 기반의 backup/copy/restore/smoke evidence 방식이 충분한지 확인한다.
  • High 영향 리스크 우선순위 및 해소 책임자 지정
    • 기준: 원본 운영 DB mutation과 잘못된 restore 리스크에 대해 자르카/렛저장인/검수관의 책임 경계를 지정한다.
  • 모든 오픈 질문(OQ) Open 상태 없음 확인
    • 기준: OQ 목록에 Open 상태 항목이 0개이거나, 잔여 항목 전부 Deferred 처리 완료
  • 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 초안 작성 인계 시점의 확정 플래그와 섹션 참조만 기록한다. 내용 재작성 없이 원본 섹션을 링크로 대신한다.

섹션 참조

Freeze 플래그

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