cr

Penerangan Sistem — Papan Panggilan Acara

Dokumen ini menerangkan cara sistem berfungsi, bukan cara pasang (rujuk SISTEM.md untuk tutorial GitHub + Firebase).

---

1. Apa sistem ini buat

Sistem ini menggantikan cara manual (kertas/pengumuman suara) untuk pengurusan bilik panggilan (call room) dalam kejohanan olahraga, dengan 3 skrin berasingan yang saling berhubung secara masa-nyata:

Skrin	Untuk siapa	Fungsi
Papan TV (call-room-board.html)	Penonton/atlet/jurulatih — dipaparkan pada TV/projektor	Papar sahaja, tiada kawalan
Panel Admin (call-room-admin.html)	Pegawai bilik panggilan	Tambah, urus, tukar status acara
Setting (call-room-settings.html)	Pegawai penyelaras	Tetapkan nama kejohanan, hari semasa, tempoh countdown

Bila pegawai buat perubahan di Admin, Papan TV automatik kemas kini dalam masa 3-6 saat — tiada siapa perlu refresh manual.

---

2. Bagaimana data mengalir (arkitektur)

   Panel Admin  ──┐
                  │        ┌─────────────────────┐
   Setting     ───┼───────▶│  Firebase Realtime   │
                  │        │      Database         │
   Papan TV    ◀──┘        └─────────────────────┘
   (baca sahaja, poll setiap 3 saat)

• Firebase Realtime Database bertindak sebagai “storan pusat” di awan
• Admin/Setting menulis data ke Firebase bila pegawai buat perubahan
• Papan TV hanya membaca data dari Firebase setiap 3 saat (poll), tidak pernah menulis
• Semua peranti (admin di telefon, TV di stadium) boleh berlainan lokasi — asalkan ada Internet, semuanya sync

Dua “kunci” data disimpan dalam Firebase:

• call-board:events — senarai semua acara
• call-board:settings — tetapan program (nama kejohanan, hari, tempoh countdown)

---

3. Status & keadaan acara

Setiap acara ada satu status yang menentukan lajur mana ia dipaparkan:

Status	Lajur di Papan TV	Bila digunakan
upcoming (Belum Buka / Menunggu)	Panggilan Akan Datang	Acara belum dipanggil lagi
live (Live)	Panggilan Semasa	Pegawai baru sahaja tekan “Live” — countdown bermula
done (Selesai)	Panggilan Tamat	Acara sudah diserahkan ke pegawai trek/padang

Dalam status upcoming, ada 2 sub-keadaan (tag):

• Belum Buka — panggilan belum dibuka lagi
• Menunggu — panggilan sudah dibuka, tunggu atlet melapor diri

Kesemua 4 butang keadaan (Belum Buka / Menunggu / Live / Selesai) dalam Admin adalah satu klik — tekan mana-mana terus tukar keadaan acara tanpa langkah tambahan.

---

4. Countdown automatik

Bila pegawai tekan butang Live:

1. Sistem simpan masa sebenar (calledAt) acara itu jadi live
2. Papan TV & Admin kira baki masa secara automatik: Tempoh Live (dari Setting) − masa berlalu
3. Countdown dipaparkan sebagai MM:SS berbaki, kemas kini setiap saat

Tempoh lalai 30 minit, boleh ditukar dalam Setting (Tempoh Live selepas Panggil) — perubahan ini terpakai untuk semua acara baharu yang di-“Live”-kan selepas itu.

---

5. Penapisan ikut Hari

Kejohanan selalunya berlangsung berhari-hari. Supaya admin tak perlu upload CSV berulang setiap hari:

1. Semua acara (Hari 01–05) diimport sekali sahaja, dengan lajur hari diisi ikut hari sebenar setiap acara
2. Dalam Setting, pegawai tetapkan “Hari” yang aktif sekarang
3. Admin & Papan TV automatik hanya papar acara yang sepadan dengan hari tersebut
4. Acara dengan hari kosong akan sentiasa dipaparkan setiap hari (sesuai untuk acara istimewa/upacara pembukaan)
5. Esok, pegawai just tukar “Hari” dalam Setting — tiada upload semula diperlukan

Dalam Panel Admin ada checkbox “Papar semua hari (semakan sahaja)” — membolehkan pegawai semak/edit acara hari lain tanpa menjejaskan apa yang dipaparkan di TV.

---

6. Medan data setiap acara

Medan	Maksud	Wajib?
no_acara	Nombor rasmi acara dalam buku program (cth: A101)	Tidak
kategori	Kod kategori (cth: BPL12)	Tidak
nama_acara	Nama acara (cth: 100m)	Ya
status	upcoming / live / done	Tidak (default upcoming)
bilik	Bilik panggilan (cth: CR1)	Tidak
pusingan	Peringkat (Saringan/Separuh Akhir/Akhir)	Tidak
catatan	Nota bebas untuk pegawai	Tidak
hari	Hari kejohanan (01–05) — kosong = setiap hari	Tidak

---

7. Import CSV vs Tambah Manual

• Tambah manual (borang dalam Admin) — sesuai untuk tambah satu-satu acara secara ad-hoc semasa kejohanan berjalan
• Import CSV — sesuai untuk masukkan puluhan/ratusan acara sekali gus di awal kejohanan (rujuk templat-acara.csv untuk contoh format)

Kedua-dua cara boleh digunakan serentak — data akan digabungkan dalam senarai yang sama.

---

8. Had & batasan sistem

• Tiada log sejarah — bila acara ditukar status, keadaan sebelumnya tidak direkod (tiada “undo” automatik, hanya boleh tukar balik manual)
• Tiada kawalan akses — sesiapa yang ada pautan Admin boleh buat perubahan (rujuk SISTEM.md bahagian keselamatan Firebase Rules)
• Tiada had automatik “satu acara live pada satu masa” — pegawai perlu pastikan sendiri tidak menjadikan >1 acara Live serentak jika itu bukan situasi sebenar (contohnya trek & padang berjalan serentak memang sah ada 2 live)
• Data tidak disulitkan untuk kegunaan sensitif — jangan simpan maklumat peribadi atlet (IC, no. telefon) dalam medan catatan atau lain-lain

---

9. Susunan fail dalam repo

callroom-mssd/
├── call-room-board.html       ← Papan TV (baca sahaja)
├── call-room-admin.html       ← Panel Admin (tulis/urus)
├── call-room-settings.html    ← Setting program
├── firebase-config.js         ← Kredential Firebase (perlu diisi sekali)
├── storage.js                 ← Lapisan storan (jangan edit)
├── templat-acara.csv          ← Contoh fail CSV untuk import
├── SISTEM.md                  ← Tutorial pasang (GitHub + Firebase)
└── README.md                  ← Dokumen ini