Dokumentasi Teknis: Sistem Pembaruan Buku (Book Update)
Dokumen ini membedah arsitektur dan implementasi teknis dari proses pembaruan buku pada aplikasi Maktabah, mulai dari antarmuka pengguna (BookUpdateView), logika bisnis (BookUpdateViewModel), hingga lapisan mesin basis data (BookUpdateManager).
1. Alur Arsitektur (Architecture Pipeline)
Alur arsitektur sistem pembaruan buku dirancang dengan pemisahan tanggung jawab yang jelas. Lapisan antarmuka (View) berkomunikasi dengan ViewModel untuk manajemen state dan eksekusi paralel. ViewModel kemudian menyerahkan pekerjaan berat (I/O, basis data, jaringan) kepada komponen terdedikasi, yaitu BookUpdateManager. Setelah selesai, Manager mengirimkan notifikasi ke sistem agar subsistem lain (misalnya Reader atau Library) dapat merespons pembaruan data.
1.1 Diagram Interaksi Komponen
flowchart TD
subgraph UI_VM ["Presentation Layer"]
UI["BookUpdateView"] --> VM["BookUpdateViewModel"]
end
UI_VM ~~~ Core_Engine
subgraph Core_Engine ["Update Engine & I/O"]
VM -->|"loadAvailableUpdates / executeBookUpdates"| BUM["BookUpdateManager"]
BUM -->|"Fetch CSV & SQLite"| Net["URLSession Network"]
BUM -->|"Apply Staged Update"| Importer["Proses Import & SQLite Engine"]
end
Core_Engine ~~~ Persistence
subgraph Persistence ["Target Storage"]
Importer --> MainDB[("main.sqlite<br/>(Tabel 0bok)")]
Importer --> ArchiveDB[("Archive DB<br/>(Tabel b{id}, t{id})")]
Importer --> FtsDB[("FTS DB<br/>(Tabel b{id}_fts)")]
Importer --> SpecDB[("special.sqlite<br/>(Tabel Muallif)")]
end
Persistence ~~~ Notifs
subgraph Notifs ["Event Dispatching"]
Importer -->|"Post Notification"| NC([".bookIntegrated"])
NC -.->|"Observer"| Lib["Library View"]
NC -.->|"Observer"| Read["Reader View"]
end
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 UI,Lib,Read ui;
class VM vm;
class BUM,Net,Importer store;
class MainDB,ArchiveDB,FtsDB,SpecDB db;
class NC event;
1.2 Alur Pembaruan (Update Pipeline)
Proses pembaruan buku secara garis besar berjalan dalam tahapan berikut:
- Pengambilan Metadata: Mengunduh dan mem-parsing berkas CSV berisi indeks buku (main) dan indeks pengarang (auth).
- Download Berkas (Staging): Mengunduh basis data SQLite baru per-buku ke direktori sementara (
Updates/). - Pengecekan Metadata Berkas: Membaca tabel
main_updatedari basis data hasil unduhan untuk mendapatkan informasi metadata yang akan disinkronisasikan. - Penerapan Pembaruan (Apply):
- Menutup koneksi pembaca aktif di
LibraryDataManageruntuk arsip tujuan. - Konversi isi teks menjadi blob Zstandard.
- Memindahkan tabel data dan TOC ke archive database.
- Menjalankan pembangunan ulang tabel FTS (Full-Text Search).
- Memperbarui metadata ke tabel
0bokdimain.sqlitedan data pengarang dispecial.sqlite.
- Menutup koneksi pembaca aktif di
- Pembersihan (Cleanup):
- Mengeksekusi checkpoint WAL (
TRUNCATE), mengembalikan journal mode keDELETE, menutup koneksi C-SQLite, lalu membersihkan berkas sidecar (-shm,-wal) pada basis data arsip dan FTS viaFileManager.default.removeDatabaseSidecars. - Menginvalidasi cache ketersediaan arsip di
DatabaseManager. - Menghapus basis data sementara hasil unduhan dan memancarkan notifikasi pembaruan sistem.
- Mengeksekusi checkpoint WAL (
1.3 Alur Konversi Tabel SQLite ke Disk
Maktabah melakukan optimalisasi ruang penyimpanan dengan menggunakan kompresi zstd pada kolom teks sebelum diintegrasikan secara final ke arsip.
flowchart TD
A(["Download file b{id}.sqlite"]) --> B["Duplikat sebagai FTS Source sementara"]
B --> C["Ubah nama tabel menjadi b{id} dan t{id}"]
C --> D["Konversi Zstd: Buat tabel temp_zstd"]
D --> E["Kompres kolom nass ke Blob Zstd"]
E --> F["Drop tabel lama & rename temp_zstd jadi b{id}"]
F --> G[("Attach ke archive_db & Copy via Transaksi")]
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 A event;
class B,C,D,E,F store;
class G db;
1.4 Metode Import, Rewrite, dan ChangeBookId
- Impor Luring (
importOfflineUpdate): Berfungsi untuk menerima berkas SQLite lokal yang dipilih pengguna. Logikanya mengabaikan pemeriksaan pembaruan daring dan mengeksekusi penimpaan (update/insert) berdasarkan tabelmain_updatelokal. - Rewrite Archive: Berkas sementara di-attach ke basis data arsip, lalu tabel disalin dari
source_dbke arsip. Tabel TOC disalin dengan pendekatan serupa. - Ubah ID Buku (
changeBookId): Mengubah ID buku yang ada dengan ID baru. Karena arsitektur membagi buku ke beberapa arsip dan indeks FTS, fungsi ini melakukan:- Mengubah nama tabel
b{oldId}dant{oldId}menjadib{newId}dant{newId}di basis data arsip. - Mengubah nama tabel
b{oldId}_ftsdi basis data FTS. - Memperbarui referensi kolom
bkiddi tabel induk0bok. - Menyediakan rollback otomatis jika salah satu langkah di atas mengalami kegagalan.
- Mengubah nama tabel
1.5 Pembangunan Ulang FTS (Rebuild FTS)
flowchart TD
Start(["Target Archive & FTS DB"]) --> Attach["Attach FTS DB & Source DB ke Archive DB"]
Attach --> Drop["Hapus tabel b{id}_fts jika sudah ada"]
Drop --> Build["Eksekusi ArchiveDatabaseTools.buildFTS"]
Build --> Insert["Insert batch via fts_source_db tabel asal"]
Insert --> Detach[("Detach Database & Truncate WAL Journal")]
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 Start event;
class Attach,Drop,Build,Insert store;
class Detach db;
Pada fase ini, BookUpdateManager tidak langsung menyalin FTS secara manual; ia menyerahkan eksekusinya ke ArchiveDatabaseTools.buildFTS yang menjalankan batch insertion dengan konfigurasi khusus demi performa tinggi.
2. Prinsip Pemisahan Tanggung Jawab (Separation of Concerns)
Maktabah mematuhi arsitektur berbasis fitur dengan batasan domain yang ketat:
- View Layer (
BookUpdateView.swift): Murni bertanggung jawab atas tampilan UI. Komponen ini merefleksikan perubahan properti dariviewModeldan menggunakan instruksi pra-kompilasi#if os(macOS)dan antarmuka khusus iOS untuk diferensiasi antarmuka native. - ViewModel Layer (
BookUpdateVM.swift): Menampung status presentasi (isUpdating,progressMessage) dan mengendalikan orkestrasi task. ViewModel memanfaatkanTaskGroupuntuk unduhan paralel, namun tidak menulis langsung ke disk atau basis data. - Manager Layer (
BookUpdateManager): Berperan sebagai engine I/O dan basis data. Terbagi ke dalam ekstensi-ekstensi:+Fetch.swift: Pengambilan CSV dan pemeriksaan versi.+Metadata.swift: Pembacaan dan penulisan metadata utama kemain.sqlite.+Import.swift: Logika FTS, kompresi Zstandard, dan penyalinan arsip.+SQLite.swift: Eksekusi operasi C-SQLite API tingkat rendah.
3. Bedah Komponen (Struct, Class, dan Enum)
3.1 Layer Tampilan (UpdateView & BookUpdateRow)
Implementasi antarmuka utama terbagi berdasarkan sistem operasi:
Daftar BookUpdateRow merupakan baris UI yang menampilkan status pembaruan dan ukuran berkas. Komponen ini memuat checkbox untuk memilih buku yang membutuhkan pembaruan.
3.2 BookUpdateViewModel (Class)
- Tipe:
@Observable final classyang memastikan keamanan pengiriman antar-thread (@unchecked Sendable). - Fungsi Utama:
loadAvailableUpdates(): Memanggil Manager untuk mem-parsing CSV dan mencocokkan versi lokal.performSelectedUpdates(): Mengumpulkan buku terpilih dan menjalankan unduhan secara asinkron menggunakanTaskGroup.
- Mekanisme Concurrency: Membatasi unduhan paralel maksimum menggunakan chunking (
maxConcurrentDownloads: 3).
// (1)!
for chunkStart in stride(from: 0, to: taskInputs.count, by: maxConcurrentDownloads) {
let chunkEnd = min(chunkStart + maxConcurrentDownloads, taskInputs.count)
let chunk = Array(taskInputs[chunkStart ..< chunkEnd])
await withTaskGroup(of: DownloadTaskOutput.self) { group in
for taskInput in chunk {
group.addTask { await self.stageSingleBookDownload(input: taskInput, authIndexMap: authIndexMap) }
}
// ... kumpulkan hasil
}
}
- Logika concurrency di dalam ViewModel membatasi eksekusi asinkron agar tidak membebani I/O jaringan maupun disk.
3.3 Struktur Data di Lapisan Model
BookIndexEntry (Struct)
Entitas yang merepresentasikan satu baris dalam berkas CSV indeks utama.
struct BookIndexEntry: Sendable {
let bkid: Int
let bk: String
let category: Int
let versionName: Int64
let downloadURL: String
let fileSize: Int64
}
bkid: Pengenal unik kitab (Book ID).bk: Judul kitab.category: ID kategori kitab.versionName: Versi bilangan bulat (nilai lebih tinggi menunjukkan versi lebih baru).downloadURL: URL unduhan berkas.fileSize: Estimasi ukuran berkas dalam byte.
AuthIndexEntry (Struct)
Entitas indeks untuk data pengarang (muallif).
BookMetadata (Struct)
Struct yang merepresentasikan skema tabel main_update dari basis data per-kitab.
struct BookMetadata: Sendable {
let bkid: Int
let cat: Int?
let bk: String
let archive: Int
let betaka: String?
let authno: Int?
let inf: String?
let tafseerNam: String?
let bVer: Int?
let link: String?
let pdfCs: Int?
}
StagedBookUpdate (Struct)
Struct yang merangkum seluruh dependensi dari satu pembaruan yang siap diterapkan (applied).
struct StagedBookUpdate: Sendable {
let entry: BookIndexEntry
let metadata: BookMetadata
let downloadedBookURL: URL
let ftsSourceURL: URL
let authorContext: AuthorContext?
let workingDirectory: URL
}
downloadedBookURL: Lokasi berkas SQLite buku yang selesai diunduh.ftsSourceURL: Lokasi berkas duplikat teks mentah untuk FTS.authorContext: Informasi pengarang terkait.
AuthorContext (Struct)
Konteks pengarang terkait yang dipasangkan dengan buku.
3.4 BookUpdateStatus (Enum) - Status Event
Sistem pembaruan dipandu oleh status-status yang didefinisikan dalam BookUpdateStatus:
enum BookUpdateStatus: Equatable {
case pending
case checking
case downloading
case processing
case downloaded
case new
case needsUpdate
case upToDate
case completed
case skipped
case failed(String)
}
stateDiagram-v2
[*] --> pending: Inisialisasi
pending --> checking: Cek Versi CSV
checking --> needsUpdate: Versi Baru Tersedia
checking --> upToDate: Versi Sudah Terkini
checking --> new: Buku Belum Ada
needsUpdate --> downloading: Eksekusi Update
new --> downloading: Eksekusi Download
downloading --> downloaded: Unduh SQLite Selesai
downloaded --> processing: Kompresi Zstd & Indexing FTS
processing --> completed: Integrasi Selesai
downloading --> failed: Jaringan / Disk Error
processing --> failed: SQLite Error
pending --> skipped: Dibatalkan Pengguna
completed --> [*]
upToDate --> [*]
failed --> [*]
skipped --> [*]
pending: Kondisi awal antrean.checking/downloading/processing: Transisi progres aktif.downloaded: Unduhan berhasil, siap dieksekusi ke arsip.needsUpdate: Versi lokal tertinggal dibanding server.new: Buku belum ada di basis data lokal.failed: Membawa pesan galat SQLite atau jaringan.
Status Pengecekan Database
Untuk mengecek ketersediaan buku, Maktabah menggunakan enum internal di BookUpdateManager yaitu BookVersionState:
.notInLibrary: Tidak ditemukan rekaman dengan ID terkait..unknownVersion: Buku ditemukan namun kolom versinya kosong atau kolombVerbelum tersedia (skema lawas)..version(Int64): Versi numerik tersedia.
3.5 BookUpdateManager (Class) - Singleton
Manajer I/O dan pembaruan data utama (final class BookUpdateManager: Sendable).
- Konkurensi: Memenuhi protocol
Sendableuntuk pemanggilan lintas Tasks, dengan perlindunganMutexpada cache kolom versi internal. - Fungsi Tahapan Eksekusi Utama:
stageBookDownload(_:authIndex:): Mengunduh dan menyiapkan metadata, mengembalikanStagedBookUpdate.applyStagedBookUpdate(_:knownExists:isOfflineImport:):- Memastikan data pengarang terunduh dan terpasang.
- Memanggil
convertBookDatabaseuntuk kompresi teks ke blob Zstandard. - Menggunakan
BookArchiveSingleFlightagar penulisan arsip terkunci serial guna mencegah bentrokan transaksi SQLite antar-thread. - Mengeksekusi
replaceArchiveDatabase(menutup koneksi pembaca aktif, menyalin data secara atomik, mengeksekusiwal_checkpoint(TRUNCATE), menutup koneksi basis data, membersihkan berkas sidecar-shm/-waldenganFileManager.default.removeDatabaseSidecars, serta menginvalidasi cache arsip). - Memperbarui rekaman metadata lokal (
saveBookMetadata).
Notifikasi Integrasi
Setelah pembaruan buku selesai, sistem memancarkan broadcast internal: NotificationCenter.default.post(name: .bookIntegrated, object: metadata.bkid). Subsistem UI lainnya akan merespons untuk memvalidasi cache dan memperbarui tampilan katalog.