Append-Only 문서 버저닝 설계 및 구현

문제 정의

수정 이력을 보존해야 하는 도메인에서는 "update overwrite" 방식이 감사 추적을 깨뜨립니다. Append-Only는 기존 문서를 덮어쓰지 않고 새 버전을 추가합니다.

권장 저장 구조

• documents: 모든 버전 스냅샷
• current_documents: 최신 버전만 캐시

이중 구조를 쓰면 감사 추적과 조회 성능을 동시에 맞출 수 있습니다.

쓰기 흐름

1. 최신 버전 조회
2. 변경 반영한 새 버전 생성 (version + 1)
3. documents에 insert
4. current_documents upsert
5. audit log 기록

트랜잭션으로 묶어 원자성을 보장합니다.

최소 모델

type Document struct {
	URI       string
	Version   int32
	Status    string // ACTIVE, DELETED
	Fields    map[string]any
	CreatedAt time.Time
	UpdatedAt time.Time
}

운영에서 중요한 점

• (uri, version) 유니크 인덱스 필수
• 최신 조회용 (uri, updated_at) 인덱스 최적화
• 소프트 삭제도 새 버전으로 표현
• 히스토리 압축/아카이빙 정책 미리 정의

자주 하는 실수

• 최신 컬렉션만 유지하고 히스토리 정합성 검증 없음
• 버전 생성 로직을 여러 서비스가 중복 구현
• 업데이트 중간에 audit 기록 누락

요약

Append-Only의 핵심은 "무조건 저장"이 아니라 "일관된 버전 생성 규칙"입니다. 쓰기 경로를 단일화하고 트랜잭션으로 묶으면 감사성과 복구성이 크게 좋아집니다.