Hong Kong Karaoke — Sistem Booking Room
Booking room karaoke untuk staf/kasir, berjalan di Vercel (Go serverless),
data disimpan di Google Sheets, dan timer + alarm di TV setiap room.
| Bagian | Lokasi | Keterangan |
|---|
| Halaman staf | / (public/index.html) | Login username + PIN, jadwal per room, booking, check-in, perpanjang, check-out, batal, laporan, aktivitas, kelola room & user |
| Halaman TV | /tv?room=R01&key=... (public/tv.html) | Sisa waktu, peringatan 5 menit, alarm saat waktu habis |
| API | /api/* (api/index.go → pkg/httpapi) | Satu Go function di Vercel |
| Aturan bisnis | pkg/booking | Harga, cek bentrok, status, laporan |
| Penyimpanan | pkg/sheetstore | Google Sheets API |
| Aplikasi Android TV | android-tv/ | APK WebView fullscreen, auto-start saat TV nyala |
Tampilan
- Halaman staf: gaya terang dengan warna brand navy
#1E3A8A, font Inter,
menu di sidebar kiri (di HP menjadi menu lipat lewat tombol ☰).
- Jadwal punya dua tampilan (pilihan tersimpan di browser):
- Timeline: baris per room, kolom per jam (default 10:00–02:00, melebar
otomatis), garis merah = sekarang. Klik blok untuk detail dan aksi; klik
area kosong untuk booking baru di room dan jam itu (dibulatkan ke 30 menit).
- Kartu: tampilan per room seperti sebelumnya.
- Layar TV tetap gelap (navy) agar tidak menyilaukan di ruangan karaoke, dengan
logo dan nama Hong Kong Karaoke.
- Nama dan warna brand ada di
public/index.html, public/tv.html,
public/css/app.css (--brand) dan public/css/tv.css.
WhatsApp ke tamu
Tombol WhatsApp di setiap booking (kartu, detail timeline, tab Daftar,
kartu pengingat) membuka dialog pratinjau: nomor tujuan, jenis pesan, dan isi
pesan yang bisa diedit. Buka WhatsApp membuka chat tamu di WhatsApp
Web/Desktop/HP kasir dengan pesan terisi; staf menekan Kirim di WhatsApp.
Sistem ini tidak mengirim pesan sendiri.
- Jenis pesan: Konfirmasi booking (Tentative menyebut batas tahan),
Pengingat sebelum datang, Waktu hampir habis/perpanjangan, Terima kasih.
Default dipilih dari status booking.
- Nomor dirapikan otomatis (
0812… → 62812…, +62 … → 62…). Jika kolom HP
kosong tetapi nomor terketik di kolom Nama, nomor itu dipakai.
- Form booking menolak nomor HP di kolom Nama tamu.
- Tidak tampil untuk Accounting.
Role dan hak akses
| Aksi | Staff | Supervisor | Admin | Accounting |
|---|
| Lihat jadwal & daftar booking | ✓ | ✓ | ✓ | ✓ |
| Booking baru, check-in, perpanjang, check-out | ✓ | ✓ | ✓ | |
| Konfirmasi Tentative, batalkan Tentative | ✓ | ✓ | ✓ | |
| Batalkan booking Confirm | | ✓ | ✓ | |
| Booking Compliment (gratis, alasan wajib) | ✓ | ✓ | ✓ | |
| Check-out lebih awal, tagih sesuai pemakaian | | ✓ | ✓ | |
| Laporan (harian atau rentang tanggal), log aktivitas | | ✓ | ✓ | ✓ |
| Kelola room (tambah, ubah nama, aktif/nonaktif) dan tabel harga | | | ✓ | |
| Kelola user (tambah, ubah role, nonaktifkan, reset PIN) | | | ✓ | |
| Kelola TV (buat kode pairing, cabut TV) | | | ✓ | |
| Unduh CSV (daftar booking, laporan) | | ✓ | ✓ | ✓ |
- Accounting hanya melihat dan mengunduh: tidak ada tombol aksi, tidak
bisa membuat/mengubah booking, room, harga, user, atau TV (server menolak
dengan 403), dan tidak mendapat pengingat/alarm. Nomor HP tamu tampil lengkap.
- Unduh CSV: tab Daftar (sesuai filter dan rentang tanggal, maks. 92 hari)
dan tab Laporan. File UTF-8, dipisah koma. Sel yang diawali
= + - @ diberi
tanda ' agar tidak dijalankan sebagai rumus di Excel. Setiap unduhan
tercatat di Aktivitas. Jika Excel menampilkan semua kolom dalam satu kolom
(pengaturan wilayah Indonesia memakai ;), buka lewat Data → From Text/CSV
dan pilih pemisah koma, atau buka di Google Sheets.
- Tabel hak akses ada di satu tempat: pkg/booking/roles.go.
Server memeriksanya di setiap request; halaman web hanya menyembunyikan tombol.
- Role user dibaca ulang dari sheet di setiap request (cache 5 detik), jadi
menonaktifkan user atau menurunkan role langsung berlaku.
- Semua user bisa mengganti PIN sendiri (tombol Ganti PIN). PIN 6-12 angka;
angka sama (
111111) atau berurutan (123456) ditolak.
- Admin tidak bisa menurunkan role atau menonaktifkan akun sendiri, dan harus
selalu ada minimal satu admin aktif.
- Salah PIN 5 kali: username dikunci 5 menit.
- Login pertama: selama tab
Users kosong, login dengan username admin
dan PIN = ADMIN_PIN. Akun admin itu langsung tersimpan di sheet; ganti PIN-nya
setelah login. Jika semua admin terkunci, kosongkan isi tab Users (sisakan
header) untuk memakai ADMIN_PIN lagi.
Log aktivitas (tab Activity): login, ganti/reset PIN, booking baru,
check-in, perpanjang, check-out, batal, perubahan room dan user, lengkap
dengan waktu, username, dan detail (mis. tarif Rp100.000 -> Rp120.000).
Booking juga menyimpan created_by, confirmed_by, checked_in_by, checked_out_by, cancelled_by, dan hold_until (batas tahan Tentative).
Alur booking
tentative ──konfirmasi──> booked (Confirm) ──check-in──> checked_in ──check-out──> finished
│ │ └─ +30 / +1 jam (perpanjang)
└──batal──> cancelled <───┘ batal
-
Confirm (booked di sheet): booking pasti.
-
Tentative: belum pasti, menahan slot sampai hold_until = 2 jam sebelum
jam mulai (minimal 30 menit dari saat dibuat, tidak lewat jam mulai). Setelah
itu tampil Kedaluwarsa dan slot terbuka untuk tamu lain. Booking
kedaluwarsa masih bisa dikonfirmasi jika slotnya masih kosong. Tentative harus
dikonfirmasi dulu sebelum check-in, dan tidak bisa diperpanjang.
-
Compliment (gratis): staff, supervisor & admin; alasan wajib diisi.
Statusnya Confirm, total Rp 0 termasuk perpanjangan; harga normal tetap
disimpan. Laporan menampilkan jumlah, jam, dan nilai normal compliment
(tidak masuk pendapatan); CSV punya kolom compliment, alasan_compliment,
nilai_normal. Tercatat di Aktivitas beserta alasannya.
Kolom Nomor voucher wajib diisi untuk setiap compliment: disimpan
huruf besar, satu voucher hanya untuk satu booking yang tidak dibatalkan
(dibatalkan → voucher bisa dipakai lagi), bisa dicari di tab Daftar, ikut di
CSV (voucher) dan Aktivitas.
-
Check-out lebih awal: jika tamu check-out sebelum jam selesai, muncul
pilihan tagihan:
- Sesuai booking (default, semua staf): tetap bayar durasi booking.
- Sesuai pemakaian (supervisor & admin): waktu sejak check-in dibulatkan ke
atas per 30 menit, minimal 1 jam, maksimal durasi booking. Contoh booking
2 jam, terpakai 1 jam 5 menit → ditagih 1,5 jam. Tercatat di Aktivitas
beserta harga sebelumnya; kolom
billed_minutes di tab Bookings.
Booking compliment tetap Rp 0. Laporan "Jam terpakai" memakai waktu
check-in s/d check-out sebenarnya; CSV punya kolom menit_pakai dan
menit_ditagih.
-
Tab Daftar: semua booking dengan filter status (Confirm, Tentative,
Tentative kedaluwarsa, Cancel, Check-in, Selesai), rentang tanggal mulai
(maks. 92 hari, default hari ini + 30 hari), dan pencarian nama/HP/catatan.
Menampilkan jumlah dan total harga, serta tombol aksi di tiap baris.
-
Harga (menu Harga, tab Pricing), sama untuk semua room:
| Hari | Mulai 11:00 – 16:59 | Mulai 17:00 – 10:59 |
|---|
| Senin – Kamis | Rp 60.000 / jam | Rp 120.000 / jam |
| Jumat – Minggu | Rp 85.000 / jam | Rp 170.000 / jam |
Alarm TV
| Kondisi | Tampilan | Suara |
|---|
| Tamu sudah check-in | Nama tamu, hitung mundur besar, progress bar | – |
| Sisa ≤ 5 menit | Angka dan banner oranye "Waktu tinggal N menit" | Chime 2× (sekali per jam selesai) |
| Waktu habis | Layar merah berkedip "WAKTU HABIS" | Sirene berulang tiap 2,5 detik |
Alarm waktu habis berbunyi terus sampai staf check-out atau perpanjang di
halaman staf. Tombol "Senyapkan 2 menit" di TV hanya menunda; setelah 2 menit
alarm bunyi lagi. Setelah perpanjang, peringatan 5 menit akan muncul lagi
untuk jam selesai yang baru.
Pengingat di halaman staf/kasir (semua role, di tab mana pun): halaman
staf memantau semua room yang sedang check-in hari ini (tiap 15 detik).
- Sisa ≤ 5 menit: kartu oranye di pojok kanan bawah dengan hitung mundur,
bunyi peringatan sekali, dan tombol +30 mnt / +1 jam / Check-out / Tutup.
- Waktu habis: kartu merah berkedip dan sirene tiap 2,5 detik sampai staf
check-out, perpanjang, atau menekan Senyapkan.
- Judul tab browser berkedip
⏰ (2) Hampir habis agar terlihat dari jendela lain.
- Browser hanya mengizinkan suara setelah ada klik, dan izin itu hilang setiap
halaman dibuka ulang. Setelah login suara langsung aktif. Setelah refresh,
header menampilkan 🔇 Suara nonaktif (klik di mana saja untuk
mengaktifkan); jika saat itu ada room yang hampir habis atau lewat waktu,
muncul peringatan merah "Alarm tidak berbunyi" di atas kartu pengingat.
Agar PC kasir tidak perlu klik setelah refresh, buka sistem lewat shortcut:
chrome.exe --autoplay-policy=no-user-gesture-required --app=https://sistembookingkaraoke.vercel.app
(tutup semua jendela Chrome dulu), atau minta IT menambahkan alamat ini ke
kebijakan Chrome/Edge AutoplayAllowlist.
- Biarkan tab halaman staf tetap terbuka. Browser bisa memperlambat timer di tab
yang lama tidak dilihat, sehingga bunyi bisa tertunda hingga ±1 menit; kartu
tetap tepat saat tab dibuka.
TV mengambil status dari server tiap 20 detik (10 detik saat peringatan/alarm),
dan menghitung mundur sendiri tiap detik memakai jam server. Jika internet
putus, timer tetap berjalan dan alarm tetap bunyi.
Setup (sekali saja)
1. Google Sheets + Service Account
-
Buat spreadsheet kosong di Google Sheets. Salin ID dari URL:
https://docs.google.com/spreadsheets/d/<SPREADSHEET_ID>/edit
-
Di Google Cloud Console:
- Buat project (atau pakai yang ada), aktifkan Google Sheets API.
- IAM & Admin → Service Accounts → Create. Tidak perlu role.
- Di service account: Keys → Add key → JSON. Simpan file-nya dengan aman.
-
Share spreadsheet ke email service account ([email protected])
sebagai Editor.
-
Buat tab dan header otomatis (opsi -seed menambah 4 contoh room):
# isi .env (lihat .env.example), GOOGLE_SERVICE_ACCOUNT_FILE=/path/ke/key.json
set -a; . ./.env; set +a
go run ./cmd/sheetsetup -check # hanya membaca: daftar tab
go run ./cmd/sheetsetup -seed # buat tab + 4 contoh room
Perintah ini hanya menambah tab yang belum ada; data yang sudah ada tidak diubah.
Struktur sheet (baris 1 = header, kolom dicari berdasarkan nama header):
- Rooms:
id | name | rate_per_hour | active — sebaiknya diubah lewat
menu Room (admin) supaya tercatat di log; edit langsung di sheet tetap bisa.
- Bookings:
id | room_id | customer_name | phone | start | end | duration_minutes | status | rate_per_hour | total_price | notes | checked_in_at | checked_out_at | created_at | updated_at | created_by | checked_in_by | checked_out_by | cancelled_by | confirmed_by | hold_until | complimentary | compliment_reason | billed_minutes | voucher_number
— diisi oleh aplikasi. Waktu dalam WIB, format YYYY-MM-DD HH:MM.
Boleh menambah kolom sendiri di kanan; isinya tidak akan ditimpa.
- Users:
username | name | role | pin_hash | active | created_at | updated_at
— kelola lewat menu User. pin_hash tidak bisa dibalik menjadi PIN tanpa
PIN_PEPPER yang hanya ada di server. Batasi siapa yang bisa membuka spreadsheet.
- Activity:
time | username | action | booking_id | room_id | detail — hanya ditambah, jangan diedit.
- Pricing:
day_type | start | end | rate_per_hour — weekday/weekend,
jam HH:MM; jam selesai lebih kecil dari jam mulai = melewati tengah malam.
Ubah lewat menu Harga (admin), yang memeriksa setiap jenis hari menutup
24 jam tanpa tumpang tindih.
- Devices:
id | name | room_id | status | token_hash | pair_code_hash | pair_expires | created_by | created_at | paired_at | revoked_by
— TV yang dipasangkan; kelola lewat menu TV, jangan diedit.
Setelah update aplikasi yang menambah kolom/tab, jalankan lagi
go run ./cmd/sheetsetup -check lalu go run ./cmd/sheetsetup. Perintah ini
hanya menambah tab dan kolom di ujung kanan; data lama tidak diubah.
Jangan ubah nama header atau isi kolom id. Hindari mengedit baris booking
yang sedang aktif langsung di sheet; pakai halaman staf.
2. Deploy ke Vercel
-
Push folder ini ke Git (GitHub/GitLab), lalu Import Project di Vercel.
Framework preset: Other. Tidak perlu build command.
-
Set Environment Variables (lihat .env.example):
| Nama | Isi |
|---|
ADMIN_PIN | PIN untuk login pertama sebagai admin (6-12 angka) |
SESSION_SECRET | openssl rand -base64 48 |
PIN_PEPPER | openssl rand -base64 48 — jangan pernah diganti setelah ada user |
TV_KEY | openssl rand -hex 16 |
SPREADSHEET_ID | ID spreadsheet |
GOOGLE_SERVICE_ACCOUNT_JSON | isi file JSON, atau base64-nya: base64 -i key.json |
APP_TIMEZONE | opsional, default Asia/Jakarta |
-
Deploy. Cek https://<app>.vercel.app/api/health → {"ok":true,...}.
-
Buka https://<app>.vercel.app/, login dengan PIN.
3. TV di setiap room
Pairing (cara utama). Setiap TV mendapat kunci sendiri; tidak perlu mengetik
kode room atau TV key.
- Admin buka menu TV → + Pasang TV baru, pilih room, beri nama TV, lalu
Buat kode pairing. Muncul kode 6 angka, berlaku 15 menit, sekali pakai.
- Di TV, buka aplikasi TV (atau halaman
/tv di browser TV). Layar
Pengaturan TV meminta kode pairing; ketik 6 angka itu dengan remote.
- TV langsung menampilkan room-nya (nama room di pojok kiri atas).
TV yang hilang, rusak, atau dipindah ruangan: menu TV → Cabut. TV itu
kembali ke layar pairing; TV lain tidak terpengaruh. Kode yang belum dipakai
bisa dibatalkan dengan tombol yang sama. Semua kejadian tercatat di Aktivitas.
Server hanya menyimpan hash kode dan hash token (tab Devices). Salah kode 10
kali dari alamat yang sama mengunci pairing dari alamat itu selama 10 menit.
Cara lama (masih didukung): kode room + TV_KEY bersama, lewat
/tv?room=R01&key=<TV_KEY> atau tautan "Cara lama" di layar pengaturan.
Opsi A – Browser TV / mini PC / Chromecast dengan browser:
buka https://<app>.vercel.app/tv dalam mode fullscreen, lalu masukkan kode pairing.
Tekan OK sekali saat muncul "Tekan OK untuk mengaktifkan suara" (aturan
autoplay browser). Pengaturan tersimpan di TV; buka /tv?setup=1 untuk mengubah.
Opsi B – Aplikasi Android TV (disarankan untuk Android TV / TV box):
suara alarm langsung aktif tanpa tekan tombol, layar tidak mati, dan aplikasi
terbuka sendiri setelah TV dinyalakan. Alamat server sudah terisi otomatis.
Build APK rilis (ditandatangani dengan release key; nilai KARAOKE_TV_* ada di .env):
set -a; . ./.env; set +a
cd android-tv
JAVA_HOME=/opt/homebrew/opt/openjdk@17 ./gradlew assembleRelease
# APK: android-tv/app/build/outputs/apk/release/app-release.apk
Simpan cadangan keystore ~/.config/karaoke-tv/release.jks beserta
password-nya (di .env) di tempat aman, misalnya password manager. Android
hanya mau memasang update yang ditandatangani dengan key yang sama; jika key
hilang, aplikasi di setiap TV harus di-uninstall dulu sebelum versi baru dipasang.
Pasang ke TV:
-
Di TV: Settings → Device Preferences → About, klik Build 7 kali untuk
membuka Developer options. Lalu Developer options → aktifkan USB debugging
/ Network debugging (ADB). Catat IP TV (Settings → Network).
-
Dari komputer di jaringan yang sama:
adb connect <IP-TV>:5555 # setujui prompt "Allow debugging" di TV
adb install -r android-tv/app/build/outputs/apk/release/app-release.apk
# Izinkan auto-start setelah TV dinyalakan (Android 10+):
adb shell appops set com.sentineltech.karaoketv SYSTEM_ALERT_WINDOW allow
adb shell monkey -p com.sentineltech.karaoketv 1 # buka aplikasinya
-
Aplikasi langsung membuka layar pairing (alamat server sudah terisi).
Ketik kode 6 angka dari menu TV di halaman admin.
Cara lama: tekan lama BACK untuk membuka pengaturan aplikasi, isi kode room
dan TV key (adb shell input text "$TV_KEY" untuk mengetik key dari komputer).
Tanpa adb (mis. TV tanpa Developer options): salin APK ke flashdisk, buka dengan
aplikasi file manager di TV, izinkan Install unknown apps, lalu masukkan
kode pairing dengan remote. Auto-start setelah boot butuh langkah appops di atas.
Buka pengaturan lagi: tekan lama BACK atau tekan MENU. Tombol BACK
biasa diabaikan supaya tamu tidak keluar dari timer.
Update aplikasi: naikkan versionCode di android-tv/app/build.gradle.kts,
build ulang, lalu adb install -r lagi (pengaturan di TV tetap tersimpan).
Pengembangan lokal
# Tanpa Google Sheets (data di memori, hilang saat server berhenti):
STORE=memory ADMIN_PIN=112233 \
SESSION_SECRET=dev-secret-dev-secret-dev-secret-123 \
PIN_PEPPER=dev-pepper-dev-pepper-dev-pepper-12 TV_KEY=dev-tv-key-123456 \
go run ./cmd/devserver
# Login: username admin, PIN 112233
# Staf: http://localhost:8080 TV: http://localhost:8080/tv?room=R01&key=dev-tv-key-123456
go test ./... # unit test aturan booking, auth, parsing sheet, API
vercel build # cek build Vercel secara lokal (perlu `vercel link`)
Batasan yang perlu diketahui
- Kuota Google Sheets: sekitar 60 request baca/menit per service account.
Server membaca kedua tab dalam 1 request dan menyimpan cache 5 detik per
instance. Dengan polling TV 20 detik, ±15 room masih aman. Jika room lebih
banyak, naikkan
POLL_MS di public/js/tv.js atau
pindahkan ke PostgreSQL (cukup buat implementasi booking.Store baru).
- Tidak ada transaksi di Google Sheets. Dalam satu instance, penulisan
diantre dan cek bentrok selalu membaca data terbaru. Dua staf yang menyimpan
booking ke room dan jam yang sama di detik yang sama masih bisa lolos
(sangat jarang untuk tim kecil).
- Kunci login per instance: hitungan salah PIN disimpan di memori server,
jadi berlaku per instance Vercel. Setiap gagal login juga diperlambat 1 detik.
- Sheet terus bertambah: arsipkan baris
Bookings lama (misal per tahun)
ke spreadsheet lain agar baca tetap cepat.
- Rollback: Vercel menyimpan semua deployment; pakai Instant Rollback di
dashboard. Data di Sheets punya Version history (File → Version history).
