Gold Price Tracker
Platform untuk melihat pergerakan historis harga emas batangan di Indonesia: harga jual toko, harga buyback, dan spread untuk Antam, UBS, dan Galeri24, dibandingkan dengan harga emas dunia (XAU/USD) dan kurs USD/IDR.
Data dikumpulkan otomatis setiap hari oleh GitHub Actions dari logammulia.com, pegadaian.co.id, dan ubslifestyle.com, disimpan sebagai CSV di repository ini (git-as-database), lalu disajikan sebagai situs statis di Vercel.
Status: Fase 1 (pipeline harga ritel). Ketiga sumber ritel dijalankan otomatis setiap hari; notifikasi, karantina, dan backfill sudah aktif; observasi 7 hari menuju gerbang G1 sedang berjalan. Rencana lengkap di plan/.
Dokumentasi
Operasional
Pipeline berjalan sendiri lewat GitHub Actions. Bagian ini untuk saat ada yang perlu dicek atau diperbaiki. Detail lengkap ada di WORKFLOWS.md.
Jadwal
| Workflow | Kapan | Isi |
|---|
scrape-retail | 10.25 & 13.25 WIB (jendela day: UBS Lifestyle, Logam Mulia); 19.05 & 21.05 WIB (jendela evening: Pegadaian) | Slot pertama primary; slot kedua retry hanya untuk sumber yang belum sukses |
ci | Setiap push kode (bukan data/**) dan PR | Lint, typecheck, test |
backfill, quarantine, probe, notify-test | Manual | Lihat di bawah |
Cron GitHub sering terlambat berjam-jam (26–31 Okt 2026: ±6 jam). Run tetap menilai data terhadap tanggal slot, bukan jam saat run berjalan (D-27). Setiap run yang mengubah data membuat commit data: … dari github-actions[bot], jadi git pull dulu sebelum bekerja di lokal.
Menjalankan scrape manual
Actions → scrape-retail → Run workflow:
sources: kosong = semua sumber aktif (Pegadaian dilewati sebelum 18.45 WIB), atau daftar dipisah koma, mis. pegadaian.force: jalankan walau sumber itu sudah sukses hari ini.
Dari terminal:
gh workflow run scrape-retail.yml -f sources=pegadaian
Di lokal (--root harus absolut, karena pnpm --filter berjalan dari folder paket):
pnpm --filter scraper start plan --workflow scrape-retail --event workflow_dispatch --root "$PWD"
pnpm --filter scraper start scrape --source ubslifestyle --root "$PWD" --out "$PWD/out/ubslifestyle"
pnpm --filter scraper start merge --in "$PWD/out" --root "$PWD" --dry-run true
scrape tidak pernah menulis ke data/. merge --dry-run true hanya mencetak path yang akan berubah.
Membaca hasil run
| File | Isi |
|---|
data/meta/status.json | Kondisi terakhir per sumber: last_status, last_data_date, consecutive_failures. Tempat pertama untuk dicek |
data/meta/runs/{yyyy}.jsonl | Satu baris per sumber per run: status, error_code/error_message, data_date, jumlah insert/update/sama/ditahan/ditolak, path raw |
data/meta/revisions/{yyyy}.jsonl | Setiap nilai yang berubah: old_value → new_value, reason (source_changed, quarantine_approved, …) |
data/raw/{source}/{yyyy-mm}/ | Respons mentah (gzip) untuk diagnosis; hanya ditulis bila isinya berubah |
| Step summary run di Actions | Tabel ringkas per sumber |
| Status | Arti |
|---|
success | Data ditulis |
partial | Data ditulis, sebagian baris ditahan ke karantina |
stale | Sumber belum memperbarui harga untuk tanggal slot; tidak menulis. Dianggap gagal hanya di hari yang diharapkan menurut update_calendar, dan Issue baru dibuka di slot retry |
failed | Fetch, parse, atau validasi gagal; tidak menulis. Lihat error_code |
jq '.pegadaian' data/meta/status.json
tail -n 5 data/meta/runs/2026.jsonl | jq -c '{source, slot, status, data_date, error_message}'
Saat ada Issue pipeline-failure
Kegagalan membuka satu Issue per sumber (label pipeline-failure dan source:{id}) dan mengirim pesan Telegram. Kegagalan berikutnya menambah komentar di Issue yang sama, dan Issue ditutup otomatis saat sumber itu sukses lagi.
- Buka tautan run di Issue, lalu baca baris sumber di step summary dan
error_message di data/meta/runs/.
- Tindakan per
error_code:
- Tanpa
error_code (stale): sumber terlambat update. Biasanya pulih sendiri di slot berikutnya; bila perlu, jalankan scrape manual nanti.
FETCH_HTTP, FETCH_TIMEOUT: situs bermasalah atau sedang maintenance. Tunggu, lalu jalankan manual.BLOCKED: diblokir proteksi bot (paling mungkin Logam Mulia, D-26). Cek dengan workflow probe; bila terus terjadi, pertimbangkan self-hosted runner.PARSE_ERROR, SCHEMA_INVALID: struktur situs berubah. Ambil raw dari data/raw/, perbarui parser, fixture, dan uji, lalu jalankan manual.VALIDATION_FAILED: data tidak masuk akal (mis. buyback ≥ jual, gramasi kurang). Periksa raw sebelum mengubah aturan, dan catat perubahan aturan di DECISIONS.md.
- Issue
Pipeline gagal: merge berarti data run itu tidak ter-commit (mis. push ditolak). Jalankan ulang run tersebut.
Untuk menguji jalur notifikasi tanpa menyentuh data (mis. setelah mengganti secret Telegram): Actions → notify-test → failed (buka Issue + Telegram), lalu recovered (tutup Issue).
Karantina
Baris yang mencurigakan ditahan dan tidak ditulis: harga berubah lebih dari 10% dari nilai terakhir (PRICE_JUMP), gramasi di luar config/catalog.yml (UNKNOWN_ITEM), atau lebih dari 20 revisi histori dalam satu run (MASS_REVISION). Batch disimpan di data/quarantine/{source}/{tanggal}-{run_id}.json, dan Issue quarantine + Telegram menyebut path file-nya.
- Buka file batch dan bandingkan barisnya dengan situs sumber.
- Untuk
UNKNOWN_ITEM yang memang gramasi baru, tambahkan gramasi itu ke config/catalog.yml lewat commit biasa terlebih dulu.
- Actions → quarantine → isi
path (dari Issue), decision (approve atau reject), dan note.
approve: baris divalidasi ulang (kecuali aturan pemicunya), ditulis ke CSV, dan dicatat sebagai revisi quarantine_approved.reject: baris dibuang.- Keduanya memindahkan file ke
data/quarantine/_resolved/{source}/ beserta keputusan, pengambil keputusan, dan catatan. Issue ditutup bila tidak ada batch pending lagi untuk sumber itu.
Backfill histori
Actions → backfill → pilih job, opsional from/to (YYYY-MM-DD). Selalu jalankan dulu dengan dry_run (default): merge berjalan di runner tanpa commit, ringkasan diff tampil di step summary, dan diff lengkap ada di artifact backfill-diff. Bila diff sudah benar, jalankan lagi dengan dry_run dimatikan.
| Job | Isi | Status |
|---|
ubs-history | Buyback 1 g UBS dari grafik sejak Nov 2023, variant kosong (D-28) | Sudah dijalankan 31 Okt 2026 |
logammulia-archive | Harga dasar + buyback 1 g Antam sejak 2010, dari arsip lokal (--input, hanya dari terminal, D-29) | Sudah diimpor 31 Okt 2026 |
pegadaian-savings | Tabungan Emas Pegadaian (jual + buyback per 0,01 g), 360 hari terakhir dari grafik (D-30); bisa diulang untuk menambal hari terlewat | Sudah dijalankan 31 Okt 2026 |
worldbank, xaus, ecb, jisdor, annual-fx | Seri makro | Fase 2 |
Backfill tidak menimpa nilai yang sama, mencatat nilai yang berbeda sebagai revisi source_changed, dan tidak mengubah status.json.
Menambah sumber baru
- Riset: tambahkan target di
apps/scraper/src/probe/targets.ts, lalu jalankan workflow probe untuk memastikan sumber bisa diakses dari runner GitHub. Simpan fixture di apps/scraper/test/fixtures/{source}/ beserta README-nya, dan catat temuan di TECH-SPEC §5.
- Skema: tambahkan id ke
SCRAPER_IDS (dan PRICE_SOURCES untuk harga ritel) di packages/schema/src/enums.ts, serta gramasinya di config/catalog.yml.
- Modul: buat
apps/scraper/src/sources/{id}.ts sesuai kontrak SourceScraper (fetchRaw + parse murni), daftarkan di src/sources/index.ts, dan tambahkan MIN_ROWS di src/pipeline/validate.ts. Uji parser dengan fixture.
- Konfigurasi: tambahkan entri di
config/sources.yml dengan enabled: false, lalu uji dengan run manual sources={id}. Setelah hasilnya benar, ubah ke enabled: true. Pilih schedule_window sesuai jam sumber memperbarui harga.
- Catat keputusan yang tidak terlihat dari kode di
plan/DECISIONS.md.
Secrets dan variables
| Nama | Jenis | Dipakai oleh |
|---|
TELEGRAM_BOT_TOKEN, TELEGRAM_CHAT_ID | Secret | notify (tanpa keduanya Telegram dilewati; Issue tetap jalan) |
SCRAPER_USER_AGENT | Variable | Scraper HTTP |
GITHUB_TOKEN bawaan cukup untuk commit data dan Issue.
Situs web
Situs statis (apps/web, Next.js static export): Hari ini, Explorer, Spread, dan Data. Alamat: https://gold.hafidznrg.my.id (Vercel, dibangun ulang otomatis setiap ada commit data).
pnpm --filter web exec tsx scripts/build-data.ts # CSV di data/ -> JSON di apps/web/public/data
pnpm --filter web exec next dev -p 3100 # dev server di http://localhost:3100
pnpm --filter web build # build produksi ke apps/web/out (menjalankan build-data lebih dulu)
pnpm --filter web e2e # smoke test Playwright terhadap out/ (butuh build; pertama kali: pnpm --filter web exec playwright install chromium)
Atur NEXT_PUBLIC_SITE_URL saat build agar tag Open Graph memakai domain yang benar.
Lisensi
Kode berlisensi MIT. Data harga adalah milik masing-masing penerbit (lihat Catatan data di bawah).
Catatan data
Harga adalah milik masing-masing penerbit (PT Antam Tbk, PT Pegadaian, PT Untung Bersama Sejahtera). Proyek ini non-komersial dan bukan rekomendasi investasi; harga resmi selalu mengacu ke situs penerbit.
