♻️ Refactor synchronization service

internal/syncer/merge/merger.go

@@ -0,0 +1,19 @@
+package merge
+
+import (
+	"context"
+	"voidraft/internal/syncer/snapshot"
+)
+
+// Report 描述一次合并中的统计信息。
+type Report struct {
+	Added     int
+	Updated   int
+	Deleted   int
+	Conflicts int
+}
+
+// Merger 描述快照合并策略。
+type Merger interface {
+	Merge(ctx context.Context, local *snapshot.Snapshot, remote *snapshot.Snapshot) (*snapshot.Snapshot, Report, error)
+}

internal/syncer/merge/updated_at_wins.go

@@ -0,0 +1,98 @@
+package merge
+
+import (
+	"context"
+	"sort"
+	"time"
+	"voidraft/internal/syncer/snapshot"
+)
+
+// UpdatedAtWinsMerger 使用 updated_at 作为默认冲突解决依据。
+type UpdatedAtWinsMerger struct{}
+
+// NewUpdatedAtWinsMerger 创建新的默认合并器。
+func NewUpdatedAtWinsMerger() *UpdatedAtWinsMerger {
+	return &UpdatedAtWinsMerger{}
+}
+
+// Merge 合并本地与远端快照。
+func (m *UpdatedAtWinsMerger) Merge(ctx context.Context, local *snapshot.Snapshot, remote *snapshot.Snapshot) (*snapshot.Snapshot, Report, error) {
+	_ = ctx
+
+	localSnapshot := snapshot.Clone(local)
+	remoteSnapshot := snapshot.Clone(remote)
+
+	index := make(map[string]snapshot.Record)
+	report := Report{}
+
+	for _, kind := range sortedKinds(localSnapshot, remoteSnapshot) {
+		for _, record := range localSnapshot.Resources[kind] {
+			index[recordKey(kind, record.ID)] = snapshot.CloneRecord(record)
+		}
+		for _, remoteRecord := range remoteSnapshot.Resources[kind] {
+			key := recordKey(kind, remoteRecord.ID)
+			localRecord, exists := index[key]
+			if !exists {
+				index[key] = snapshot.CloneRecord(remoteRecord)
+				report.Added++
+				continue
+			}
+
+			switch {
+			case remoteRecord.UpdatedAt.After(localRecord.UpdatedAt):
+				index[key] = snapshot.CloneRecord(remoteRecord)
+				report.Updated++
+			case remoteRecord.UpdatedAt.Equal(localRecord.UpdatedAt):
+				if snapshot.RecordDigest(localRecord) != snapshot.RecordDigest(remoteRecord) {
+					report.Conflicts++
+				}
+			default:
+				if remoteRecord.DeletedAt != nil && localRecord.DeletedAt == nil {
+					report.Deleted++
+				}
+			}
+		}
+	}
+
+	merged := snapshot.New()
+	for _, key := range sortedKeys(index) {
+		record := index[key]
+		merged.Resources[record.Kind] = append(merged.Resources[record.Kind], snapshot.CloneRecord(record))
+	}
+	merged.CreatedAt = time.Now()
+
+	return merged, report, nil
+}
+
+// sortedKinds 返回两个快照内的全部资源类型集合。
+func sortedKinds(local *snapshot.Snapshot, remote *snapshot.Snapshot) []string {
+	index := make(map[string]struct{})
+	for kind := range local.Resources {
+		index[kind] = struct{}{}
+	}
+	for kind := range remote.Resources {
+		index[kind] = struct{}{}
+	}
+
+	kinds := make([]string, 0, len(index))
+	for kind := range index {
+		kinds = append(kinds, kind)
+	}
+	sort.Strings(kinds)
+	return kinds
+}
+
+// sortedKeys 返回稳定排序后的索引键集合。
+func sortedKeys(index map[string]snapshot.Record) []string {
+	keys := make([]string, 0, len(index))
+	for key := range index {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	return keys
+}
+
+// recordKey 生成 record 的稳定索引键。
+func recordKey(kind string, id string) string {
+	return kind + ":" + id
+}

internal/syncer/merge/updated_at_wins_test.go

@@ -0,0 +1,50 @@
+package merge
+
+import (
+	"context"
+	"testing"
+	"time"
+	"voidraft/internal/syncer/snapshot"
+)
+
+// TestUpdatedAtWinsMergerMerge 验证较新的记录会覆盖较旧记录。
+func TestUpdatedAtWinsMergerMerge(t *testing.T) {
+	localRecord, err := snapshot.NewRecord("documents", "doc-1", map[string]interface{}{
+		"uuid":       "doc-1",
+		"updated_at": time.Date(2026, 3, 29, 9, 0, 0, 0, time.UTC).Format(time.RFC3339),
+		"title":      "local",
+	}, nil)
+	if err != nil {
+		t.Fatalf("build local record: %v", err)
+	}
+
+	remoteRecord, err := snapshot.NewRecord("documents", "doc-1", map[string]interface{}{
+		"uuid":       "doc-1",
+		"updated_at": time.Date(2026, 3, 29, 10, 0, 0, 0, time.UTC).Format(time.RFC3339),
+		"title":      "remote",
+	}, nil)
+	if err != nil {
+		t.Fatalf("build remote record: %v", err)
+	}
+
+	localSnapshot := snapshot.New()
+	localSnapshot.Resources["documents"] = []snapshot.Record{localRecord}
+
+	remoteSnapshot := snapshot.New()
+	remoteSnapshot.Resources["documents"] = []snapshot.Record{remoteRecord}
+
+	merger := NewUpdatedAtWinsMerger()
+	merged, report, err := merger.Merge(context.Background(), localSnapshot, remoteSnapshot)
+	if err != nil {
+		t.Fatalf("merge snapshot: %v", err)
+	}
+
+	if report.Updated != 1 {
+		t.Fatalf("expected updated report to be 1, got %d", report.Updated)
+	}
+
+	record := merged.Resources["documents"][0]
+	if got := record.Values["title"]; got != "remote" {
+		t.Fatalf("expected remote title, got %v", got)
+	}
+}