Jarca
67d8d4871b
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
46 lines
3.9 KiB
Markdown
46 lines
3.9 KiB
Markdown
# REQ-002: 운영 안전 백업·복구·검증 DB 워크플로우
|
|
|
|
## Metadata
|
|
- ID: REQ-002
|
|
- Type: Non-Functional
|
|
- Status: Implemented
|
|
- Priority: High
|
|
- Owner: 렛저장인
|
|
- Source Discovery: dcy-002_20260627_operational-safety-backup-restore-validation-db
|
|
- Created At (KST): 2026-06-27 10:17
|
|
- Approved At (KST): 2026-06-27 10:17
|
|
|
|
## Intent
|
|
원본 Jarca Ledger 운영 DB를 직접 훼손하지 않고 import, rollback, categorization, reconciliation, migration 검증을 반복할 수 있도록 백업 생성, 검증 DB 선택, 복구 smoke, QC evidence 기준을 표준화한다.
|
|
|
|
## Requirement
|
|
시스템은 운영 DB의 timestamped backup을 생성·조회·상태 확인할 수 있는 additive service/MCP 인터페이스와, restore를 MCP로 노출하지 않는 script/runbook 기반 절차를 제공해야 한다. 모든 검증 evidence는 DB 파일 경로, 크기, mtime, sha256/checksum, 주요 table row count, aggregate total, health/test 결과처럼 민감정보가 없는 메타데이터로 제한해야 한다.
|
|
|
|
## Acceptance Criteria
|
|
1. Backup 생성은 기본 위치 `/root/.local/share/jarca/backups/ledger/`에 timestamped SQLite 파일을 만들고, source DB와 backup DB의 path, size, mtime, sha256, integrity_check, 주요 table row count를 반환한다.
|
|
2. Backup 보관 정책은 최근 30일 또는 최근 20개 backup 유지이며, retention 실행 결과로 pruned path 목록을 메타데이터로 확인할 수 있다.
|
|
3. Backup 목록/status/hash 확인은 additive service/MCP tool로 제공되며 기존 MCP success response shape를 깨지 않는다.
|
|
4. Restore 실행은 MCP tool로 노출하지 않고 `scripts/ledger_restore_smoke.py`와 runbook으로만 제공하며, 기존 target overwrite에는 명시 승인 token이 필요하다.
|
|
5. 검증은 synthetic fixture DB를 우선 사용하고, 운영 DB copy가 필요한 경우 repo 밖 경로에서 hash/mtime/row count/aggregate만 evidence로 남긴다.
|
|
6. `docs/runtime-flows.md`, `docs/data-model.md`, `docs/interface-contract.md`는 backup/status/list/hash/restore 제한 정책과 민감정보 금지 evidence 기준을 반영한다.
|
|
7. 테스트는 synthetic DB에서 backup 생성, list, status/hash, retention, restore smoke 또는 health/status check를 검증하고 원본 운영 DB mutation 없이 통과한다.
|
|
8. 검수관 QC gate는 원본 운영 DB 직접 mutation 여부, restore MCP 노출 금지, 민감정보 노출 금지, synthetic fixture 또는 DB copy 기반 smoke evidence를 확인해 PASS/PASS_WITH_NOTES/BLOCKED 판정을 기록한다.
|
|
|
|
## Impacted Area
|
|
- `jarca_ledger_mcp/service.py`: DB status, backup 생성, backup 목록/status helper 추가.
|
|
- `jarca_ledger_mcp/server.py`: restore 제외, backup/status/list/hash additive MCP tool 추가.
|
|
- `scripts/ledger_restore_smoke.py`: 사용자 승인 기반 restore smoke helper.
|
|
- `tests/test_backup_workflow.py`: synthetic DB 기반 regression.
|
|
- `docs/runtime-flows.md`, `docs/data-model.md`, `docs/interface-contract.md`, `docs/runbooks/ledger-backup-restore.md`: 운영 안전 flow와 interface 계약 갱신.
|
|
|
|
## Notes
|
|
- 원본 운영 DB 직접 mutation, 실제 운영 DB restore, 파괴적 migration, 대량 data rewrite는 사용자 명시 승인 전까지 금지한다.
|
|
- Restore는 intentionally non-MCP surface다. 자동화가 필요해도 MCP tool로 추가하지 않는다.
|
|
- 거래 원문, merchant/counterparty 전체 dump, 계좌번호, raw_payload, 원본 금융 파일 내용은 docs/tests/logs evidence에 포함하지 않는다.
|
|
- 사용자 기본안이 승인되었으므로 REQ 상태는 Proposed 생성 직후 자르카 대리 승인 원칙에 따라 Approved로 전환했다.
|
|
|
|
## Change Log
|
|
- 2026-06-27 10:17 KST: dcy-002에서 REQ-002 초안 생성.
|
|
- 2026-06-27 10:17 KST: 사용자 승인 기본안에 따라 REQ-002를 Approved로 전환.
|
|
- 2026-06-27 10:33 KST: BAT-002 verification 및 jarcaledgerqc PASS 근거로 REQ-002를 Implemented로 전환.
|