---
id: pattern-offline-sync
title: "Offline Sync Pattern"
category: "Pattern_Mobile"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: ["offline sync", "오프라인 동기화", "optimistic update", "conflict resolution", "outbox"]
duplicate_of: ""
source_trust_level: "A"
confidence_score: 0.85
created_at: 2026-06-13
updated_at: 2026-06-13
review_reason: ""
merge_history: []
tags: ["pattern", "mobile", "offline", "sync", "platform-independent"]
raw_sources: ["일반 모바일 공학 지식", "AstraAI/src/features/_shared/eventSourcedStore.ts (개념 유사)"]
applied_in: []
github_commit: ""
---

# [[Offline Sync Pattern]]

## 🎯 한 줄 통찰 (One-line insight)
오프라인 동기화는 "네트워크 없이도 로컬에서 동작하고, 연결되면 변경을 *큐로 모아 동기화*하며 충돌을 해소" 하는 패턴으로, 핵심 난제는 동기화 자체가 아니라 **충돌 해소(conflict resolution)** 다.

## 🧠 핵심 개념 (Core concepts)
1. **로컬 우선 저장:** 모든 쓰기를 먼저 로컬에.
2. **outbox(변경 큐):** 미동기 변경을 append-only 로 쌓아 연결 시 전송.
3. **낙관적 업데이트:** UI 는 즉시 반영, 실패 시 롤백.
4. **충돌 해소:** last-write-wins / 버전 벡터 / 병합 / 사용자 선택.
5. **멱등성:** 재전송에도 안전하도록 변경에 고유 id.

## 📖 세부 내용 (Details · 패턴 명세)
- **Problem (언제 쓰나):** 불안정/없는 네트워크에서도 앱이 동작해야 할 때.
- **사용 조건:** 로컬 저장소; 변경을 식별/순서화 가능; 서버 동기 API.
- **장점:** 오프라인 사용성, 빠른 반응(낙관적), 복원력.
- **단점:** 충돌 해소 복잡, 데이터 일관성 약화, 디버깅 난해.
- **대안:** 온라인 전용(단순), CRDT(자동 병합, 복잡), 서버 권위(충돌 시 서버 우선).
- **실패 사례:** 멱등 키 없어 중복 적용; LWW 로 사용자 데이터 유실; outbox 순서 꼬임; 낙관적 업데이트 롤백 누락으로 유령 데이터.

## 💻 코드 패턴 (Code patterns)
```text
write(op): localDB.apply(op); outbox.append({id:uuid, op, ts})   # 로컬 우선 + 큐
onOnline: for op in outbox: try{ server.apply(op) /*멱등*/; outbox.remove(op) } catch{ retry }
onPull: merge(serverChanges, local, resolve=versionVector|userChoice)
```
개념 유사: AstraAI 의 append-only 이벤트([[이벤트 소싱 스토어 패턴]])가 outbox 와 같은 구조 — 변경을 줄로 쌓고 재생/전송.

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
LWW 는 간단하지만 데이터 손실 위험 — 협업/중요 데이터엔 버전 벡터/CRDT 또는 사용자 충돌 해소가 안전.

## 🛠️ 적용 사례 (Applied in summary)
일반 모바일 앱(노트/메신저). AstraAI 는 단일 로컬이라 동기화는 불필요하나 outbox 구조는 동일.

## 🔗 지식 그래프 (Knowledge Graph)
- **상위/루트:** [[패턴 카탈로그 인덱스]]
- **관련 개념:** [[Local Storage Pattern]], [[Background Task Pattern]], [[이벤트 소싱 스토어 패턴]], [[모바일 개발 가이드]]
- **참조 맥락:** 작은 모델이 오프라인 가능 앱을 설계할 때 참조.

## 📚 출처 (Sources)
- [S1] 일반 오프라인 동기화 지식(outbox, CRDT)
- [S2] AstraAI/src/features/_shared/eventSourcedStore.ts — 구조 유사

## 📝 변경 이력 (Change history)
- 2026-06-13: 프로젝트 독립 패턴 카드 작성.
