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_contentpada(bkId, contentId): Digunakan saat merender UI Reader yang perlu mengambil anotasi pada halaman aktif secara cepat.idx_ann_ck_record_idpada(ckRecordId): Untuk efisiensi sinkronisasi CloudKit.
2. Tabel Relasi Many-to-Many (Tags)
tags: Berisiid(INTEGER),name(TEXT), dannormalizedName(TEXT UNIQUE) untuk pencarian case-insensitive.annotation_tags: Tabel junction berisiannotationId(INTEGER) dantagId(INTEGER). Dilengkapi Unique Indexidx_ann_tag_idsuntuk 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]):
- Pemeriksaan Cache Terkonsolidasi: Memeriksa seluruh
idsdi dalamcacheByIddi bawah satu kunciMutex. - Pengambilan Missing IDs: Anotasi yang belum ada di memori diambil dari SQLite dalam satu query menggunakan klausa
INyang di-chunk per 500 ID (repository.loadAnnotationsByIds). - Preservasi Urutan Asli: Hasil akhir dipetakan kembali mengikuti urutan array
idsinput (ids.compactMap { byId[$0] }) guna menjamin determinisme saat menentukan tag pertama atau irisan metadata. - DRY Delegation:
loadAnnotationById(_ id: Int64)mendelegasikan langsung keloadAnnotationsByIds([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), fungsideleteUnusedTags()langsung dieksekusi di dalam transaksi yang sama. - Efisiensi Sinkronisasi & UI:
applyBatchTagUpdatesmemperbarui 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.