Skip to content

Persistence, Cache & Concurrency

Fitur Annotations menyimpan data ke penyimpanan lokal (SQLite) serta melakukan sinkronisasi awan (CloudKit) agar konsisten di berbagai perangkat pengguna.

Skema SQLite (AnnotationRepository)

AnnotationRepository bertindak sebagai lapisan akses data langsung (Direct Data Access) menggunakan pembungkus SQLiteDatabase. Berkas basis data disimpan pada direktori Application Support dengan nama Annotations.sqlite.

Basis data memiliki 3 tabel utama:

1. Tabel annotations

Menyimpan metadata detail setiap anotasi.

erDiagram
    ANNOTATIONS ||--o{ ANNOTATION_TAGS : "annotationId (CASCADE)"
    TAGS ||--o{ ANNOTATION_TAGS : "tagId (CASCADE)"
    ANNOTATIONS ||--o{ PENDING_SYNC : "ckRecordId"

    ANNOTATIONS {
        INTEGER id PK
        INTEGER bkId
        INTEGER contentId
        INTEGER startIndex
        INTEGER length
        INTEGER startIndexDiac
        INTEGER lengthDiac
        TEXT color
        INTEGER type
        TEXT note
        INTEGER createdAt
        TEXT context
        INTEGER part
        INTEGER page
        TEXT ckRecordId UK
        INTEGER lastModified
    }

    TAGS {
        INTEGER id PK
        TEXT name
        TEXT normalizedName UK
    }

    ANNOTATION_TAGS {
        INTEGER annotationId FK
        INTEGER tagId FK
    }
Kolom Tipe Data Deskripsi
id INTEGER PRIMARY KEY AUTOINCREMENT ID auto-increment dari SQLite.
bkId INTEGER ID Buku Maktabah.
contentId INTEGER ID Konten/Halaman dari Buku.
startIndex INTEGER Titik awal rentang teks tanpa harakat.
length INTEGER Panjang rentang teks tanpa harakat.
startIndexDiac INTEGER Titik awal rentang teks dengan harakat.
lengthDiac INTEGER Panjang rentang teks dengan harakat.
color TEXT Kode heksadesimal warna (misalnya #FFFF00).
type INTEGER Mode Anotasi (0: Highlight, 1: Underline).
note TEXT Catatan teks tambahan (nullable).
createdAt INTEGER UNIX timestamp detik pembuatan anotasi.
context TEXT Salinan teks yang dianotasi (denormalisasi untuk pencarian cepat).
part INTEGER Bagian / Jilid buku.
page INTEGER Halaman cetak buku.
ckRecordId TEXT UUID string khusus rekaman CloudKit.
lastModified INTEGER UNIX timestamp detik modifikasi terakhir (untuk Conflict Resolution).

Indeks Pencarian:

  • idx_ann_bk_content pada (bkId, contentId): Digunakan saat merender UI Reader yang perlu mengambil anotasi pada halaman aktif secara cepat.
  • idx_ann_ck_record_id pada (ckRecordId): Untuk efisiensi sinkronisasi CloudKit.

2. Tabel Relasi Many-to-Many (Tags)

  • tags: Berisi id (INTEGER), name (TEXT), dan normalizedName (TEXT UNIQUE) untuk pencarian case-insensitive.
  • annotation_tags: Tabel junction berisi annotationId (INTEGER) dan tagId (INTEGER). Dilengkapi Unique Index idx_ann_tag_ids untuk mencegah duplikasi tag pada satu anotasi.

Lapisan In-Memory Cache (AnnotationStore)

Aplikasi mengoptimalkan interaksi data dengan tidak melakukan pembacaan/penulisan langsung ke AnnotationRepository di UI Thread, melainkan melalui AnnotationStore, sebuah singleton yang mengelola in-memory cache.

private struct CacheState: Sendable {
    var cacheById: [Int64: Annotation] = [:]
    var cacheByContent: [ContentKey: [Annotation]] = [:]
    var cacheByBook: [Int: [Annotation]] = [:]
    var cacheTagsByAnnotationId: [Int64: [String]] = [:]
    var cachedAllTagNames: [String]?
}

Pengamanan Thread-Safety (Synchronization.Mutex)

State cache dilindungi oleh Mutex bawaan framework Synchronization (Swift 6):

import Synchronization

private let cache = Mutex(CacheState())

func loadAnnotations(bkId: Int, contentId: Int) -> [Annotation] {
    let key = ContentKey(bkId: bkId, contentId: contentId)

    // 1. Ambil dari Cache In-Memory (kompleksitas O(1))
    let cached = cache.withLock { $0.cacheByContent[key] }
    if let cached { return cached }

    // 2. Jika Cache Miss, ambil dari SQLite
    let loaded = (try? repository.loadAnnotations(bkId: bkId, contentId: contentId)) ?? []

    // 3. Perbarui Cache dengan Mutex Lock
    cache.withLock { state in
        state.cacheByContent[key] = loaded
        // ... simpan pemetaan lookup berdasarkan ID
    }

    return loaded
}

Penggunaan Mutex.withLock berbasis operasi lock atomik tingkat OS memastikan tidak ada kondisi data race saat membaca ataupun memperbarui data anotasi secara konkuren oleh search worker dan Main Thread.

Pemuatan Massal & Preservasi Urutan (loadAnnotationsByIds)

Untuk menghindari query individual secara berulang (N+1) saat antarmuka membutuhkan sekumpulan anotasi berdasarkan ID (misalnya pada penentuan common tags di popover tag), AnnotationStore menyediakan loadAnnotationsByIds(_ ids: [Int64]):

  1. Pemeriksaan Cache Terkonsolidasi: Memeriksa seluruh ids di dalam cacheById di bawah satu kunci Mutex.
  2. Pengambilan Missing IDs: Anotasi yang belum ada di memori diambil dari SQLite dalam satu query menggunakan klausa IN yang di-chunk per 500 ID (repository.loadAnnotationsByIds).
  3. Preservasi Urutan Asli: Hasil akhir dipetakan kembali mengikuti urutan array ids input (ids.compactMap { byId[$0] }) guna menjamin determinisme saat menentukan tag pertama atau irisan metadata.
  4. DRY Delegation: loadAnnotationById(_ id: Int64) mendelegasikan langsung ke loadAnnotationsByIds([id]).first.

Mutasi Tag Massal Atomik (addTags & removeTags)

Sebelumnya, penambahan atau penghapusan beberapa tag sekaligus mengeksekusi operasi per-tag secara terpisah (menghasilkan $N$ transaksi basis data, $N$ kali pembaruan cache, $N$ kali antrean CloudKit, dan $N$ kali pemicu notifikasi UI).

Sistem mengonsolidasikan mutasi tersebut melalui API batch:

  • Satu Transaksi Atomik: Seluruh perubahan tag untuk sekumpulan anotasi dieksekusi di dalam 1 blok transaksi SQLite tunggal (transaction { ... }).
  • Sanitasi Terpusat: Tag dibersihkan dari spasi (trimmed) dan dideduplikasi berdasarkan nama normalisasi (case-insensitive) sebelum diproses.
  • Pembersihan Otomatis: Pada operasi penghapusan tag (removeTags), fungsi deleteUnusedTags() langsung dieksekusi di dalam transaksi yang sama.
  • Efisiensi Sinkronisasi & UI: applyBatchTagUpdates memperbarui cache memori sekaligus, mengunggah satu batch perubahan ke CloudKit, dan hanya memancarkan satu event .batchUpdated(annotations) ke antarmuka pengguna.

Batch Query Tag pada Pembaruan Kitab (updateAnnotationsBookId)

Ketika ID kitab berubah (misalnya pada proses import atau restrukturisasi arsip), pembaruan relasi tag pada seluruh anotasi terkait dilakukan tanpa query individual berulang: * Tag diambil secara massal melalui fetchTagsForAnnotations(ids:) menggunakan klausa IN (SELECT at.annotation_id, t.name FROM tags t INNER JOIN annotation_tags at ... WHERE at.annotation_id IN (...)). * Seluruh anotasi yang terdampak diperbarui dan dicatat ke antrean sinkronisasi CloudKit dalam satu transaksi.

Alur Sinkronisasi Offline & CloudKit (AnnotationSyncHandler.swift)

Untuk mendukung kesinambungan baca lintas perangkat, modul Anotasi terhubung ke CloudKitSyncManager melalui zona kustom (Custom Zone) di Private Database CloudKit pengguna.

Alur Sinkronisasi Keluar (Upload & Delete)

flowchart TD
    ACT(["Aksi Pengguna: Buat / Ubah / Hapus"]) --> Store["AnnotationStore (In-Memory Cache)"]
    Store --> Repo["AnnotationRepository"]
    Store --> TreeBuilder["AnnotationTreeBuilder"]

    TreeBuilder -.-> Diffing(["Publish AnnotationEvent"])

    Repo ~~~ STORES

    subgraph STORES ["Persistensi Lokal"]
        Pending[("SyncPendingStore (Queue)")]
        SQLite[("Annotations.sqlite (WAL Mode)")]
    end

    Repo -->|"Catat Antrean"| Pending
    Repo -->|"Simpan Lokal"| SQLite

    Store -->|"Push Perubahan"| CK["CloudKitSyncManager.shared"]
    CloudKit[("CloudKit Private Zone")]

    CK -->|"Kirim Batch CKRecord"| CloudKit
    CloudKit -->|"Sukses"| ClearPending(["Hapus ID dari SyncPendingStore"])

    classDef ui fill:#e040fb26,stroke:#c026d3,stroke-width:2px;
    classDef vm fill:#3b82f626,stroke:#2563eb,stroke-width:2px;
    classDef store fill:#22c55e26,stroke:#16a34a,stroke-width:2px;
    classDef db fill:#f9731626,stroke:#ea580c,stroke-width:2px;
    classDef event fill:#be185d26,stroke:#9d174d,stroke-width:2px,color:#9d174d;

    class ACT,Diffing,ClearPending event;
    class Store,Repo,TreeBuilder,CK store;
    class Pending,SQLite,CloudKit db;

Alur Sinkronisasi Masuk & Resolusi Konflik (LWW)

Ketika data remote diterima dari CloudKit via fetchChanges:

flowchart TD
    Remote(["Terima Rekaman dari CloudKit"]) --> CheckExisting{"Apakah Rekaman Ada di SQLite?"}

    CheckExisting -->|"Ya"| CompareTime{"remoteLastModified >= localLastModified?"}
    CompareTime -->|"Ya"| UpdateLocal["Perbarui Data Lokal di SQLite"]
    CompareTime -->|"Tidak"| DropRemote["Abaikan Data Remote / Pertahankan Lokal"]

    CheckExisting -->|"Tidak"| InsertNew["Sisipkan Baris Baru ke SQLite"]

    UpdateLocal --> UpdateCache["Perbarui In-Memory Cache via Mutex"]
    InsertNew --> UpdateCache
    UpdateCache --> ReloadUI(["Picu Notifikasi & Render Ulang Reader UI"])

    classDef ui fill:#e040fb26,stroke:#c026d3,stroke-width:2px;
    classDef vm fill:#3b82f626,stroke:#2563eb,stroke-width:2px;
    classDef store fill:#22c55e26,stroke:#16a34a,stroke-width:2px;
    classDef db fill:#f9731626,stroke:#ea580c,stroke-width:2px;
    classDef event fill:#be185d26,stroke:#9d174d,stroke-width:2px,color:#9d174d;

    class Remote,ReloadUI event;
    class CheckExisting,CompareTime ui;
    class UpdateLocal,DropRemote,InsertNew,UpdateCache store;

Apabila sinkronisasi menarik versi Cloud yang lebih baru dari versi lokal, SQLite akan menimpa (overwrite) versi lokal, cache memori diperbarui di bawah proteksi Mutex, dan antarmuka Reader dipicu untuk merender anotasi terbaru. Jika data remote lebih usang, data tersebut diabaikan untuk menjaga integritas data lokal.

Penanganan Mode Luring (SyncPendingStore)

Setiap mutasi (Insert, Update, Delete) yang dilakukan di AnnotationRepository dicatat ke dalam antrean sinkronisasi tertunda (pending sync):

try transaction {
    try exec(insertAnnotationSQL, parameters: params)
    // ...
    try self.addPendingSync(ckRecordId: ckId, operation: "upload")
}

Jika modifikasi lokal gagal terunggah (misalnya saat perangkat luring), perubahan tersimpan dengan aman pada SyncPendingStore. CloudKitSyncManager akan melakukan flush pada antrean tersebut secara asinkron setelah konektivitas internet kembali pulih.

Thread-Safety & Sendable Conformance (AnnotationRepository)

AnnotationRepository mengadopsi protokol Sendable secara langsung tanpa membutuhkan penanda @unchecked. Komponen ini membungkus pointer basis data, URL, dan instance SyncPendingStore ke dalam kontainer state terisolasi:

final class AnnotationRepository: SyncPendingManaging, Sendable {
    private struct State: Sendable {
        var db: SQLiteDatabase?
        var syncPendingStore: SyncPendingStore?
        var dbURL: URL?
    }

    private let state = Mutex(State())

    var _db: SQLiteDatabase? {
        state.withLock { $0.db }
    }
    var syncPendingStore: SyncPendingStore? {
        state.withLock { $0.syncPendingStore }
    }
    var dbURL: URL? {
        state.withLock { $0.dbURL }
    }
}

Setiap operasi pembukaan koneksi, penutupan (disconnect), atau pengambilan pointer basis data dieksekusi di dalam blok state.withLock, menjamin keamanan thread tanpa resiko data race pada Swift 6.

Operasi Reset Database & Impor

Sebagai fitur pemulihan, AnnotationStore menyediakan fungsi nukeDatabase() (yang mengosongkan tabel secara menyeluruh) dan importAnnotations() yang mengeksekusi strategi penggantian massal saat pengguna merestorasi berkas arsip anotasi lokal.