Fahami Sistem OMFS
& Belajar Coding dari A hingga Z

Satu sistem hospital sebenar, dibedah perlahan-lahan dalam bahasa harian, tanpa jargon yang memeningkan. Walaupun anda tak pernah menulis satu baris kod, selepas baca panduan ini anda akan faham bagaimana sistem ini hidup dan boleh mula belajar membina perisian sendiri.

Siapa yang guna? (peranan)

Sistem ini tahu siapa anda dan hanya benarkan anda buat kerja anda. Ini dipanggil peranan (role). Nama peranan disimpan dalam Bahasa Melayu:

Mindmap: seluruh sistem dalam satu pandangan

Sebelum mula: bahasa & simbol yang anda akan nampak

Kod sistem ini ditulis terutamanya dalam bahasa bernama TypeScript (sepupu rapat JavaScript, bahasa yang menggerakkan hampir semua laman web). Untuk bahagian lain ada juga HTML & CSS (rupa skrin) dan SQL (bercakap dengan database). Anda tak perlu hafal apa-apa di bawah. Cuma kenali corak berulang ini dan setiap kotak kod selepas ini akan terbaca macam ayat biasa.

1 · Pemboleh ubah (variable): bekas berlabel

Pemboleh ubah ialah bekas yang ada nama, untuk simpan satu maklumat. Macam bekas dapur bertulis "Gula". Dalam kod kita guna const (nilai tetap) atau let (nilai boleh tukar).

// "bekas" bernama namaHospital, isinya satu ayat teks
const namaHospital = "Hospital Slim River";

// "bekas" bernama umurPesakit, isinya nombor
let umurPesakit = 34;
umurPesakit = 35; // boleh tukar sebab guna 'let'

2 · Fungsi (function): mesin kecil yang buat satu kerja

Fungsi ialah satu set langkah yang dibungkus dan diberi nama, supaya boleh diguna berulang kali. Masuk sesuatu (bahan), keluar sesuatu (hasil), macam pengisar: masuk buah, tekan butang, keluar jus.

// fungsi bernama 'kira umur', terima tahun lahir, pulangkan umur
function kiraUmur(tahunLahir) {
  const tahunSekarang = 2026;
  return tahunSekarang - tahunLahir; // hasil yang dipulangkan
}

kiraUmur(1990); // hasilnya 36

3 · Syarat (if / else): buat keputusan

Komputer boleh pilih jalan: "kalau ... maka ... jika tidak ...". Macam staf kaunter: kalau pesakit warga emas, beri keutamaan; jika tidak, ikut giliran biasa.

if (umurPesakit >= 60) {
  beriKeutamaan();           // kalau 60 ke atas
} else {
  ikutGiliranBiasa();        // jika tidak
}

4 · Ulangan (loop): buat kerja sama banyak kali

Daripada tulis arahan yang sama 100 kali, kita suruh komputer ulang. Macam: "untuk setiap pesakit dalam senarai, cetak namanya."

for (const pesakit of senaraiPesakit) {
  cetak(pesakit.nama); // ulang untuk setiap seorang
}

Baca begini: "untuk setiap" (itulah for … of) pesakit di dalam senarai senaraiPesakit, buat apa yang ada dalam kurungan besar { }, iaitu cetak namanya. Senarai 5 orang? Ia ulang 5 kali. Senarai 500? 500 kali. Anda tulis arahan itu sekali sahaja.

5 · Objek (object): satu rekod dengan banyak medan

Objek ialah satu kad maklumat lengkap, iaitu satu benda yang ada banyak butiran berlabel. Macam kad pesakit: ada nama, umur, jantina, alamat, semua dalam satu kad.

const pesakit = {
  nama: "Ahmad bin Ali",
  umur: 34,
  jantina: "Lelaki",
  telefon: "012-3456789",
};

pesakit.nama; // ambil medan 'nama' → "Ahmad bin Ali"

Bagaimana ketiga-tiganya bercakap

Skrin tak boleh terus sentuh Ingatan, sebab itu bahaya (bayangkan pelanggan masuk dapur ambil sendiri). Skrin minta kepada Otak melalui satu "tetingkap pesanan" yang dipanggil API. Otak periksa permintaan, ambil/ubah data di Ingatan, lepas itu hantar balik jawapan ke Skrin.

Kod sebenar dari sistem ini

Mari tengok satu contoh betul-betul dari sistem OMFS: bahagian Otak yang melayan permintaan "beri saya tetapan hospital". Jangan risau setiap simbol. Baca komen (teks selepas //) dan penerangan di bawah.

// Bila skrin minta GET /api/hospital/config ...
app.get('/api/hospital/config', async (c) => {
  const svc = new HospitalConfigService(c.env, 'system');
  const config = await svc.get();   // pergi ambil dari Ingatan
  return ok(c, config);          // pulang balik ke Skrin
});

Baca macam ayat biasa: "Bila ada permintaan ambil tetapan hospital, panggil pekerja khas (service), suruh dia get() data, lepas itu pulangkan." Itu sahaja. Otak tak simpan data sendiri. Ia minta "pekerja" (service) uruskan urusan database. Kita jumpa pekerja itu sebentar lagi.

Perkataan baru di sini:  app = "Otak" kita (pelayan yang menerima permintaan).  app.get('/api/...') = "bila ada permintaan jenis ambil (GET) ke alamat ini, buat langkah berikut".  async + await = kerja ini pergi ke Ingatan (ambil masa sedikit), jadi "tunggu siap dahulu".  new HospitalConfigService(...) = "panggil seorang pekerja khas".  Corak lain — const, (c) =>, { }, return — semua ada dalam jadual simbol tadi.

Jenis "Type": kenapa TypeScript penting

Ingat objek kad pesakit tadi? Dalam sistem ini, bentuk kad itu ditakrifkan sekali, supaya Skrin dan Otak sama-sama setuju apa itu "Pesakit". Ini kod sebenar:

interface Patient {
  id: string;
  nama: string;
  umur: number;
  jantina: 'Lelaki' | 'Perempuan';  // hanya dua nilai ini sah
  alamat: string;
  telefon: string;
  emel?: string;   // tanda ? = pilihan, boleh tiada
}

Sekarang kalau ada kod cuba letak jantina: "Kucing", TypeScript akan menjerit awal-awal sebelum sistem dilancarkan. Silap ditangkap di meja, bukan di hadapan pesakit. Itulah nilai "type".

Tengok "pekerja" itu dalam kod

Inilah HospitalConfigService sebenar, iaitu pekerja yang uruskan database supaya Otak tak perlu kotorkan tangan dengan SQL. Fokus pada komen:

class HospitalConfigService {
  // terima 'env' (alat sistem) + 'actorId' (siapa buat kerja)
  constructor(private env, private actorId) {}

  // baca tetapan dari database
  async get() {
    const row = await this.env.DB
      .prepare('SELECT config FROM hospital_config WHERE id = 1')
      .first();
    if (!row) return DEFAULT_HOSPITAL_IDENTITY; // belum disetel? guna lalai
    return JSON.parse(row.config);
  }

  async update(patch) {
    const current = await this.get();      // ambil yang lama
    const merged = { ...current, ...patch };  // gabung perubahan
    // ... sahkan, tulis ke DB dan catat audit ...
    await logAction(this.env, this.actorId, 'UPDATE_HOSPITAL_CONFIG');
  }
}

Perkataan baru:  class = "acuan untuk membina pekerja" (kumpul fungsi berkaitan dalam satu tempat).  this = "pekerja ini sendiri".  SELECT … FROM … ialah SQL, iaitu bahasa khas untuk bercakap dengan database ("ambil lajur config dari jadual hospital_config").  { ...current, ...patch } = "salin semua yang lama, kemudian timpa dengan yang baru" (gabung).  Selebihnya — async, await, const, if, return — anda sudah kenal.

Peta hidup: main & sentuh sendiri

Senarai di atas statik. Ini peta yang sama tetapi hidup: setiap bulatan ialah satu bahagian sistem, dan garisan menyambung bahagian yang bekerja bersama. Tarik bulatan untuk gerakkannya, hover (atau sentuh) untuk serlahkan jirannya, dan guna roda tetikus untuk zum.

📊 (Di sini ada graf interaktif bahagian sistem — buka fail ini dalam pelayar untuk meneroka; ia disembunyikan dalam cetakan PDF.)

Jadual, baris, lajur

Database jenis ini (SQLite) menyimpan data dalam jadual — sama persis macam helaian spreadsheet. Setiap baris ialah satu rekod (satu pesakit), setiap lajur ialah satu butiran (nama, umur). Setiap baris ada id unik — macam nombor pendaftaran yang tak berulang.

Inilah jadual patients. Mudah, bukan? Sebuah database cuma banyak jadual macam ini yang saling berhubung.

Hubungan: induk & anak (yang paling penting)

Seorang pesakit boleh datang banyak kali. Setiap lawatan ialah satu baris dalam jadual visits, dan setiap lawatan boleh ada banyak diagnosis & rawatan. Ini hubungan satu-ke-banyak (induk → anak).

Bagaimana anak tahu siapa induknya? Setiap baris visits menyimpan patient_id — "rujukan" yang menunjuk balik ke baris pesakit. Inilah foreign key (kunci asing).

Migration — pelan pengubahsuaian database

Kita tak ubah struktur database secara rawak. Setiap perubahan ditulis dalam fail migration bernombor (cth. 0045_hospital_config.sql). Sistem ingat migration mana telah dijalankan, jadi ia takkan ulang. Macam pelan pengubahsuaian bangunan bernombor: setiap pindaan direkod ikut turutan, boleh dijejak.

-- bina jadual untuk simpan identiti hospital
CREATE TABLE hospital_config (
  id INTEGER PRIMARY KEY,   -- nombor unik baris
  config TEXT,              -- data tetapan (nama, logo, ...)
  updated_at TEXT,
  updated_by TEXT
);

Komponen — blok Lego skrin

Daripada membina satu halaman gergasi, React memecahkannya kepada komponen kecil yang boleh diguna semula: satu butang, satu kad pesakit, satu baris jadual. Halaman besar ialah komponen kecil yang disusun.

Props — "tetapan" yang dihantar ke komponen

Komponen yang sama boleh dipakai berkali-kali dengan data berbeza. Kita "hantar" data masuk melalui props — macam argumen pada fungsi. Satu komponen KadPesakit, dipakai untuk semua pesakit, cuma props-nya berlainan.

// komponen terima 'props': satu objek pesakit
function KadPesakit({ pesakit }) {
  return (
    <div className="kad">
      <h3>{pesakit.nama}</h3>
      <p>Umur: {pesakit.umur}</p>
    </div>
  );
}

// dipakai dua kali, props berbeza
<KadPesakit pesakit={ahmad} />
<KadPesakit pesakit={siti} />

Bahagian yang nampak macam HTML di dalam kod itu dipanggil JSX — cara React membenarkan kita tulis rupa skrin terus di dalam kod.

State — ingatan sementara yang membuat skrin "hidup"

Inilah keajaiban React. State ialah data sementara komponen. Apabila state berubah, React melukis semula bahagian skrin itu secara automatik — tanpa anda menyentuh skrin secara manual.

const [carian, setCarian] = useState('');
// 'carian' = nilai semasa, 'setCarian' = cara ubahnya

// bila pengguna taip, kita ubah state → senarai auto-ditapis
<input onChange={(e) => setCarian(e.target.value)} />

Perkataan baru:  useState('') = "minta React simpan satu ingatan kecil, mula dengan kosong". Ia pulangkan dua benda sekali — [carian, setCarian] = nilai semasa + cara mengubahnya.  onChange = "bila kandungan kotak taip berubah, buat ini".  e.target.value = "apa yang pengguna taip sekarang". Jadi: taip → setCarian ubah ingatan → React lukis semula senarai yang ditapis. Itulah "papan skor" tadi.

Kata kerja HTTP — niat permintaan

Setiap permintaan ke Otak membawa satu kata kerja yang menyatakan niatnya:

Alamat (endpoint) & format data (JSON)

Setiap pintu ada alamat: /api/hospital/config. Data yang dihantar pergi-balik ditulis dalam format JSON — senarai "label: nilai" yang kemas & mudah dibaca manusia mahupun mesin.

{
  "success": true,
  "data": {
    "hospitalName": "Hospital Slim River",
    "address": { "negeri": "Perak" }
  }
}

Kod status — jawapan ringkas Otak

Setiap jawapan datang dengan satu nombor status yang memberitahu apa berlaku:

Masalah sebenar

Setiap hari ada doktor yang perlu bersedia dipanggil (on-call), termasuk hujung minggu & cuti umum yang "berat". Buat secara manual, mudah jadi berat sebelah — ada yang kena banyak, ada yang terlepas. Orang rasa tak adil. Sistem ini membina jadual secara automatik dengan keadilan boleh dikira.

Bagaimana "keadilan" dikira

Ciri-ciri penting modul ini

Tiga tingkat panggilan (mulai Oktober 2026)

Hospital menetapkan sendiri berapa tingkat panggilan yang dijalankan di Urus On-Call → Tetapan Rotasi → Tingkat Panggilan. HSR menjalankan tiga:

• Panggilan Pertama — pegawai untuk kes baru, satu kolam gabungan (OMFS + Dental Paeds + Primer) Isnin hingga Ahad, dipilih secara adil oleh sistem. Tagger kekal dalam tingkat ini.
• Panggilan Kedua — pegawai untuk pesakit dalam wad. Bagi OMFS, ia mengikut pusingan wad klinik (kitaran tetap 6 minggu, blok Isnin–Ahad) dan sistem mengiranya sendiri. Bagi Dental Paeds, tiada kitaran tetap — nama diisi dengan tangan, sama ada oleh YM pada Jadual Bulanan atau oleh pegawai sendiri di kiosk. Setiap hospital memilih caranya di Tetapan Rotasi: satu minggu penuh (seorang pegang Isnin hingga Ahad) atau ikut tarikh (pegawai ambil mana-mana hari yang dia mahu, seperti Tagger). Dental Paeds HSR menggunakan cara ikut tarikh, kerana mereka mengatur giliran mengikut cuti masing-masing.
• Panggilan Ketiga — pakar tetap (tidak berubah).

Peraturan penting: pemegang Panggilan Kedua tidak akan dipilih untuk Panggilan Pertama sepanjang tempoh yang dia pegang. Bagi peranan satu minggu penuh, itu bermakna seminggu Isnin hingga Ahad, bukan hari yang sama sahaja. Bagi peranan ikut tarikh, ia hanya hari yang dia ambil, dan hari lain dalam minggu itu dia bebas seperti biasa. Jika pegawai itu bercuti, mereka bertukar dengan rakan seperti biasa (sistem tidak mengganti sendiri) dan sistem menolak pertukaran yang akan meletakkan seseorang dalam tempoh di mana dia sudah memegang Panggilan Pertama. Peraturan ini untuk pegawai sahaja; giliran PPP tidak berubah. Butang Terbitkan akan bertanya dahulu jika ada tarikh yang masih kosong. Surat on-call turut memaparkan dua lajur baharu "Pegawai Pergigian (Panggilan Kedua)".

Apa yang berlaku bila jadual dijana semula

"Jana Semula" bermaksud kira semula seluruh bulan dari kosong. Ia bukan betulkan satu dua hari. Dalam ujian sistem, mengisi satu tarikh panggilan kedua sudah cukup untuk mengubah 27 daripada 31 hari panggilan pertama. Hari unit KPSR dan KPTM turut berubah, kerana unit ialah calon biasa dalam senarai yang sama dengan doktor.

Sebab itu urutan kerja ini penting:

1. Masukkan dahulu semua cuti, locum OT, tarikh panggilan kedua dan kakitangan baharu.
2. Barulah Jana Jadual.
3. Lepas itu barulah unit isi nama doktor, dan barulah buka pertukaran.
4. Bila jadual sudah betul, tekan Terbitkan. Bulan yang diterbitkan tidak boleh dijana semula melainkan dibuka semula, dan itulah perlindungan terbaik.

Kotak pengesahan sebelum Jana Semula kini memberitahu berapa pertukaran akan dipadam (termasuk yang sudah dipersetujui dan menunggu kelulusan), dan selepas jana ia menyenaraikan tarikh yang namanya gugur supaya boleh diisi semula. Nama yang diisi sendiri dikekalkan hanya jika harinya masih sama.

Superadmin boleh menghidupkan Tunggu peranan ini penuh sebelum unit isi nama pada mana-mana peranan di Tetapan Rotasi. Bila dihidupkan, unit tidak boleh isi nama sehingga peranan itu lengkap. Ini menghalang seorang pegawai daripada memegang panggilan pertama dan kedua pada hari yang sama.

Tajuk pada surat, dan PPP di muka surat sendiri

Surat on-call kini dicetak dalam dua jadual. Muka surat pertama membawa pegawai dan pakar; PPP dicetak pada muka surat sendiri dengan tajuknya sendiri. Sebabnya mudah: sepuluh lajur pada kertas A4 menegak menjadikan setiap lajur terlalu sempit sehingga nama berpecah tiga baris. Dengan pemisahan ini setiap lajur mendapat ruang sebenar.

Tajuk setiap lajur boleh ditaip sendiri di Tetapan Rotasi → Tajuk Pada Surat. Sistem menyediakan tajuk lalai, dan anda hanya menaip jika hospital anda menggunakan istilah lain. Contohnya HSR tiada panggilan ketiga (panggilan ketiga bermaksud pakar perunding), jadi lajur pakar ditulis "Pakar On-call" supaya ia tidak dibaca sebagai panggilan ketiga. Hospital lain yang memang mempunyai pakar perunding boleh mengekalkan tiga tingkat seperti biasa. Biarkan medan kosong untuk kekal dengan tajuk lalai.

Pada kalendar, Panggilan Kedua pegawai dipaparkan terus di bawah Pegawai Bertugas, iaitu di atas PPP Panggilan Kedua, dengan warnanya sendiri dalam petunjuk warna di atas jadual. Kad pengisian manual (bertajuk Blok Manual atau Tarikh Manual, mengikut cara yang dipilih) hanya muncul bagi bulan yang sudah dijana dengan peranan ini, jadi ia tidak akan keluar pada bulan sebelum Oktober 2026. Menukar cara pengisian selamat pada bila-bila masa: jadual yang sudah dijana tidak terjejas dan nama yang sudah diisi kekal, cuma cara memilih tarikh yang berubah.

Pesakit Dikongsi — bila dua doktor rawat pesakit yang sama

Kadang satu lawatan dirawat oleh lebih daripada seorang doktor (kotak "Rawatan Dibuat oleh Operator Lain Juga" ditanda dalam Rekod Klinikal). Panel "Pesakit Dikongsi" menunjukkan pesakit-pesakit ini & bagaimana kerja dibahagikan: bagi setiap pesakit, ia senaraikan setiap doktor yang terlibat dengan bilangan lawatan dikongsi, diagnosis, & rawatan yang doktor itu sendiri buat.

• Pentadbir/Superadmin nampak panel ini di halaman Penjanaan Laporan (seluruh fasiliti).
• Doktor nampak versi sendiri di halaman Rekod Pegawai — hanya pesakit yang doktor itu kongsi dengan rakan.

Tiga jenis pengenalan

Bukan semua pesakit ada MyKad. Sistem terima tiga jenis pengenalan utama, & ia membersihkan (canonicalize) nombor itu sebelum simpan supaya carian kemudian sentiasa jumpa pesakit yang betul.

Logik ini hidup dalam worker/patient-identification.ts (fungsi canonicalIdentificationForStorage) & worker/nombor-pesara.ts. Sebab disimpan "bersih": supaya bila petugas taip 000907-08-0222 atau 000907080222, kedua-duanya jumpa pesakit yang sama.

Walk-in, temu janji, atau on-call?

Setiap lawatan ditanda jenis kedatangannya. Ini cuma tiga "suis" pada rekod lawatan (visits) — penting untuk laporan & aliran kerja.

Sistem juga membezakan pesakit Baru vs Ulangan (jenis_kehadiran) — penting untuk laporan. (Dahulu keunikan nombor pendaftaran hanya disemak untuk pesakit Baru; sejak 24 Ogos 2026 ia disemak untuk semua lawatan — dua pertembungan sebenar tahun ini berlaku pada baris Ulangan.)

Nombor pendaftaran & cara cegah pertembungan

Kaunter menaip sendiri nombor pendaftaran pesakit Baru, mengikut daftar kaunter yang sedia ada. Daftar bertulis itulah rujukan sebenar bagi tahun ini. (Antara 11 Julai dan 24 Ogos 2026 sistem pernah memberi nombor secara automatik. Ia telah ditarik balik: satu nombor luar jangkaan yang dimasukkan pada 24 Julai menyebabkan kiraan automatik melompat jauh, dan kaunter terpaksa membetulkan nombor secara manual hampir setiap hari. Nombor yang terjejas telah dibetulkan.) Pesakit Ulangan kekal guna nombor tahun semasa mereka (diisi automatik selepas "Muatkan Maklumat"). Satu pesakit = satu nombor bagi satu tahun. Sejak 24 Ogos 2026 peraturan itu bukan lagi sekadar amalan — ia disimpan dalam daftar nombor di dalam database sendiri (jadual patient_registration_numbers), jadi database yang menolak kesilapan, bukan hanya kod.

Cari Pesakit — cari orang, bukan tarikh (Ogos 2026)

Halaman Cari Pesakit ada pada semua peranan (Kaunter, Doktor, Pentadbir, Superadmin) di menu sebelah kiri. Ia menjawab soalan yang senarai lawatan tak boleh jawab: pesakit ini pernah datang tak, dan apa nombor dia tahun ini?

• Tiada julat tarikh langsung. Senarai lawatan perlu tarikh; kalau pesakit terakhir datang lapan bulan lepas, anda takkan jumpa dia di situ. Halaman ini cari orang, jadi tarikh tak relevan.
• Buka terus papar semua pesakit ikut nama A–Z — boleh belek, bukan wajib menaip.
• Cari ikut nama, no. kad pengenalan, no. telefon, atau no. pendaftaran tahun ini. Taip lebih banyak perkataan untuk tapis lebih halus.
• Klik satu baris — barulah sistem ambil 3 lawatan terkini pesakit itu. Sebelum diklik, sejarah tak dimuatkan langsung; itu yang buat halaman ini ringan.
• Bulatan jantina: biru = Lelaki, merah jambu = Perempuan. Kalau jantina yang tersimpan tak sepadan dengan kad pengenalan, bulatan bertukar kuning dan sistem beritahu terus di baris itu.
• Lencana Baru bermaksud pesakit belum pernah datang tahun ini; Ulangan bermaksud sudah pernah. Ia mengira kedatangan, bukan sama ada dia sudah ada nombor.

Analitik pesakit — pada halaman profil

Buka profil mana-mana pesakit: di atas ada jalur ringkas (jumlah lawatan · lawatan pertama · lawatan terakhir · temu janji akan datang), dan tab baharu Analitik memaparkan kategori diagnosis dan rawatan pesakit itu sepanjang masa.

Di tab Lawatan, antara dua kad lawatan kini tertulis jarak masa antaranya — contoh "Jarak 3 bulan dari lawatan sebelum". Itu yang menunjukkan pesakit yang sepatutnya datang semula dua minggu tetapi baru muncul tujuh bulan kemudian.

Nombor pendaftaran automatik — ada, tetapi belum dihidupkan

Sejak 24 Ogos 2026 sistem ada kaunter nombor mengikut tahun. Ia berbeza sama sekali daripada percubaan Julai yang ditarik balik: nombor kini disimpan dalam barisnya sendiri, bukan dikira daripada nombor lawatan yang boleh disunting kerani. Itu yang menyebabkan masalah Julai dahulu.

Ia belum dihidupkan untuk mana-mana tahun. Tahun 2026 kekal manual — kaunter menaip nombor dari daftar bertulis, sama seperti hari ini. Superadmin boleh menghidupkannya untuk tahun baharu di Penyelenggaraan Sistem → Nombor pendaftaran automatik. Bila dihidupkan, kaunter bermula selepas nombor tertinggi yang sudah digunakan tahun itu, jadi tiada nombor dalam daftar bertulis akan diberi dua kali. Siri huruf (contoh A1/2026) tidak diurus oleh kaunter ini — ia kekal ditaip oleh kerani.

Lapisan 2 ialah jaring keselamatan di dalam database sendiri. Daftar nombor itu menyimpan satu baris sahaja bagi setiap pesakit + tahun, dan satu nombor hanya boleh dimiliki oleh seorang pesakit dalam tahun yang sama. Jadi walaupun dua kaunter menyimpan serentak (perlumbaan), database menolak yang kedua — bukan bergantung pada kod semata-mata. Semua laluan yang menulis nombor pendaftaran (pendaftaran kaunter, borang kemaskini, dan import CSV) melalui daftar yang sama.

Tiga perkara yang petugas akan perasan di kaunter:

• Nombor sudah dipakai orang lain — sistem tolak dan menyebut nama pesakit yang memegangnya, supaya kaunter boleh semak daftar bertulis. Sistem tidak lagi mencadangkan "cuba nombor seterusnya": daftar bertulis kaunter itulah rujukan sebenar, bukan kiraan komputer.
• Pesakit Ulangan — jika nombor yang terisi automatik tidak sama dengan nombor sebenar pesakit itu bagi tahun ini, sistem terus guna nombor sebenar dan pendaftaran diteruskan. Petugas tidak tersekat di ruangan yang memang tidak boleh ditaip.
• Betulkan nombor — bila nombor dibetulkan melalui borang kemaskini, semua lawatan pesakit itu bagi tahun sama berubah sekali, dalam satu simpanan. Dahulu bahagian ini dilangkau apabila bulan itu sudah dikunci — itulah puncanya seorang pesakit boleh memegang dua nombor merentas tujuh lawatan.

Apa ada dalam satu lawatan

Satu lawatan (visits) boleh mengandungi banyak diagnosis & banyak rawatan — hubungan induk→anak yang kita belajar di Bahagian 07. Setiap diagnosis/rawatan juga tahu doktor mana yang catat (operator_id).

Status reten: kitaran hidup satu lawatan

Setiap lawatan ada satu status reten — ringkasnya, "rekod ini sudah siap untuk dikira dalam laporan atau belum". Hanya tiga keadaan yang sah:

export type RetenStatus =
  'BELUM_SELESAI' | 'SELESAI' | 'BATAL';

Rawatan belum dituntut — peringatan kurang tuntut

PG201 sendiri tidak mempunyai peraturan "rawatan mesti sepadan dengan diagnosis"; ini penambahbaikan jabatan untuk mengelakkan kurang tuntut. Sistem menyemak setiap diagnosis dalam tempoh reten yang masih terbuka dan memaparkan kad kuning "Rawatan belum dituntut" di papan pemuka doktor (pesakit sendiri), pentadbir dan superadmin apabila:

• diagnosis itu belum ada rawatan berpasangan pada pesakit yang sama — rawatan pada lawatan kemudian, walaupun bulan berikutnya, dikira; bilangan rawatan boleh melebihi diagnosis (tiga laserasi = satu diagnosis, tiga rawatan), dan bilangan yang kurang hanya dicatat sebagai nota; atau
• pesakit itu tiada sebarang pengimejan pada mana-mana lawatan — satu rekod pengimejan pada mana-mana lawatan sudah memadai.

Reten yang masih diisi diberi tempoh 7 hari sebelum diperingatkan, kecuali reten itu sudah Selesai. Setiap baris ada butang Buka reten (lawatan yang membawa diagnosis) dan Abaikan dengan sebab (dirujuk ke pusat lain, pesakit menolak, tidak hadir) — sebab itu direkod dalam log audit dan peringatan itu tidak dipaparkan lagi.

Di mana rawatan direkod: pada lawatan ia dilakukan. Hari yang sama dengan diagnosis — tambah pada reten asal. Hari lain (klinik, wad atau dewan bedah) — kaunter mendaftarkan hari itu sebagai lawatan (Ulangan) dan doktor merekod rawatan pada reten hari itu. PG201 mengira prosedur pada bulan ia dilakukan, jadi pembedahan September yang ditulis pada reten Ogos akan masuk laporan bulan yang salah.

Senarai rawatan yang dikira untuk setiap diagnosis disimpan dalam katalog, bukan dalam kod. Superadmin boleh melihat dan mengubahnya di Katalog (/superadmin/katalog) — lihat Bahagian "Cara edit Katalog" di bawah.

Kunci rekod — elak dua doktor tulis serentak

Bila seorang doktor membuka satu rekod untuk diubah, sistem mengunci rekod itu (locked_by, locked_at). Doktor lain nampak ia sedang dikunci & oleh siapa. Selain itu ada kunci sistem (system_locked) — bulan lama yang sudah dilaporkan tak boleh diubah lagi.

Baru (Julai 2026): selepas bulan lama dikunci, halaman senarai lawatan (kini dipanggil Semua Lawatan, semua peranan) secara automatik memaparkan julat tarikh selepas tarikh kunci sehingga hari ini — iaitu tempoh reten yang masih terbuka. Papan pemuka pula menunjukkan kad amaran kuning "Reten belum selesai" untuk tempoh yang sama, supaya doktor dan pentadbir sedar reten tertunggak sebelum tutup reten hujung bulan. Nama doktor yang telah dinyahaktifkan juga tidak lagi muncul dalam penapis doktor di halaman laporan dan senarai.

Bar "perubahan belum disimpan" — bila ia muncul, bila ia senyap

Sistem ada satu bar terapung di bawah skrin yang muncul apabila ada suntingan belum disimpan, dengan dua butang: Set Semula & Simpan Perubahan. Ia dikongsi oleh semua borang — tiada halaman membina bar sendiri.

Peraturan bila ia muncul mudah, dan ia sengaja: bar ini untuk mengubah sesuatu yang sudah tersimpan, bukan untuk mencipta sesuatu yang baharu.

Setiap borang ini tetap ada butang Simpan sendiri di dalam borang (contoh: Simpan Rekod, Daftar Pesakit). Itulah yang menyimpan rekod baharu apabila bar tidak muncul — jadi tiada apa yang tersekat.

Kitaran hidup satu mesej

Setiap mesej (messages) ada penghantar, penerima, & isi. Ia boleh dikaitkan dengan seorang pesakit (patient_id) supaya konteks jelas. Satu mesej boleh dihantar ke beberapa penerima sekaligus (to_user_ids).

Mesej vs temu janji

Apa yang dikongsi vs apa yang berbeza

Identiti hospital — satu suis tetapan

Setiap hospital simpan identitinya dalam satu baris tunggal (hospital_config, migration 0045). Tetapan ini dibaca oleh laluan awam GET /api/hospital/config — sebab itu logo & nama hospital boleh dipaparkan sebelum sesiapa log masuk.

interface HospitalIdentity {
  appName: string;        // "Sistem OMFS"
  hospitalName: string;   // nama penuh hospital
  address: { ... };           // alamat
  contact: { tel, fax, email, web };
  letterhead: { ... };        // kepala surat + penandatangan
  logos: { ... };             // logo (base64)
  itSupport?: { ... };        // IT tempatan (pilihan)
}

Pasang baharu vs kemas kini semua

Ada dua kerja berbeza, dua skrip berbeza:

Lima peranan

Penting: sistem simpan nama peranan dalam Bahasa Melayu — guna nama Inggeris (registrar/doctor/admin) takkan padan.

Konsep "dua pintu"

Ada satu peranan sementara, system (mod kiosk), yang macam pintu utama berkunci kata laluan sistem. Selepas masuk pintu utama, barulah pengguna pilih peranan sebenar mereka (kerani/doktor/pentadbir). On-call pula ada pintu berasingan sepenuhnya — supaya orang yang urus jadual on-call tak perlu (dan tak boleh) masuk sistem klinikal.

Token: tanda pengenalan sementara

Selepas log masuk, sistem beri pengguna satu token (JWT) — macam pas pelawat bercap masa. Setiap permintaan ke pelayan bawa token ini; pelayan semak ia sah & belum luput. Tempoh sah dipilih ikut peranan:

Sumber: worker/core-utils.ts (signJwt). Kata laluan disimpan ditatah (bcrypt, 10 pusingan) — tak pernah disimpan teks biasa. Kata laluan lama (format SHA-256) ditatah semula automatik kepada bcrypt bila pengguna log masuk.

Tiga kategori pesakit

Sistem mengelaskan setiap lawatan ke salah satu daripada tiga kategori — ini menentukan bagaimana ia muncul dalam laporan:

Ada satu peraturan halus: jika lawatan ber-e-GL tetapi ditanda tanggungan kakitangan kerajaan, ia dikira balik sebagai Orang Awam — bukan e-GL. Logik ini hidup dalam worker/routes/registrar/bayaran.ts.

Nombor e-GL: tak perlu taip semula

Nombor surat jaminan berbentuk 6786/GL/1994626-2026-00001. Bahagian depan — kod hospital dan nombor pengenalan pesakit — tidak pernah berubah untuk pesakit yang sama. Hanya lima digit di hujung naik, dan itu pun cuma apabila GL baharu dikeluarkan.

Sebab itu, apabila pesakit kakitangan kerajaan mendaftar berulang dan kerani menanda kotak e-GL, sistem terus mengisi nombor dari lawatan terakhir dan menunjukkan tarikh lawatan itu:

"Diisi dari lawatan 12/03/2026. Sahkan nombor berjalan 00001 — GL baharu akan menaikkannya."

Tiga perkara yang kerani perlu tahu:

• Semak lima digit terakhir. Kalau pesakit datang dengan GL baharu, tukar bahagian itu sahaja — bahagian depan kekal.
• Nombor hanya masuk selepas kotak e-GL ditanda. Lawatan yang bukan tuntutan GL tidak akan tersimpan dengan nombor GL.
• Amaran kuning bukan sekatan. Kalau nombor tidak menepati format biasa, sistem beri peringatan tetapi tetap membenarkan pendaftaran diteruskan — kerani tidak akan tersekat di kaunter.

Kenapa ini penting: semakan data pada Ogos 2026 mendapati 10 daripada 25 pesakit e-GL berulang membawa sekurang-kurangnya satu nombor tersalah taip (digit tertukar, GL jadi DG, garis miring hilang). Punca ralat itu ialah menaip semula, bukan GL yang bertukar.

Bahagian tetap nombor e-GL dalam profil pesakit

Profil pesakit kini memaparkan bahagian nombor e-GL yang tidak pernah berubah — kod hospital dan nombor pengenalan pesakit — contohnya 6786/GL/1994626. Dua bahagian yang berubah dipapar dalam warna kuning sebagai -TTTT-NNNNN: TTTT ialah tahun dan NNNNN ialah nombor berjalan.

Ia sengaja dipapar begitu supaya tiada siapa tersilap menyalinnya sebagai nombor penuh. Dua bahagian kuning itu mesti diambil dari surat GL yang asal setiap kali.

Bahagian tetap ini tidak perlu ditaip atau dikemas kini sesiapa — sistem mengambilnya sendiri daripada nombor e-GL yang kerani simpan. Semasa pendaftaran ulangan, ia terus mengisi sehingga tahun, tinggal nombor berjalan sahaja untuk ditaip.

Senarai "Nombor e-GL / OKU tidak sepadan"

Bila nombor seorang pesakit berbeza antara dua lawatan, salah satunya mesti salah. Sistem mengesan sendiri keadaan ini dan memaparkannya sebagai kad pada papan pemuka — termasuk papan pemuka Kaunter. Klik kad itu untuk membuka senarai penuh.

Setiap baris menunjukkan nama pesakit, sebab percanggahan, dan setiap nombor yang direkodkan berserta tarikh lawatannya. Butang Kemaskini membawa terus ke rekod pesakit itu — tidak perlu mencari.

• Senarai membersih sendiri. Sebaik nombor dibetulkan, pesakit itu hilang dari senarai. Tiada siapa perlu memadam apa-apa.
• GL baharu pun disenaraikan. Sistem tidak boleh membezakan GL baharu daripada salah taip — hanya surat asal boleh. Kalau semakan mendapati nombor itu memang betul, biarkan sahaja; ia akan kekal di senarai sehingga kedua-dua lawatan menggunakan nombor yang sama.
• Kad hilang bila senarai kosong, jadi ia hanya muncul bila ada kerja.

// Tentukan kategori setiap lawatan
const kat = r.egl
  ? (r.tanggungan_kakitangan_kerajaan ? 'awam' : 'egl')
  : (r.etnik === 'BUKAN WARGANEGARA' ? 'asing' : 'awam');

Apa yang dikira

Jadual Lampiran C di dalam skrin

Halaman Laporan Bayaran memaparkan satu jadual yang disusun sama seperti borang kertas — ‘LAMPIRAN C’ Laporan Bulanan Kutipan Hasil — supaya angka di skrin boleh dibandingkan terus dengan borang yang ditandatangan dan dihantar. Tiga kategori (A Kakitangan Kerajaan, B Orang Awam, C Warganegara Asing), setiap satu dengan tiga baris bernombor: (i) Pesakit Luar, (ii) Pemeriksaan Perubatan, (iii) Lain-lain kutipan (gigi palsu).

Peraturan kiraan: Cara A (keputusan PKPD, 14/08/2026)

Satu lawatan dikira dalam SATU lajur sahaja. Kalau ada apa-apa bayaran dikutip — pendaftaran atau rawatan — lawatan itu dikira Membayar, walaupun sebahagian caj dikecualikan. Hanya lawatan yang tiada bayaran langsung dikira di lajur Percuma / Dikecualikan. Kerana itu jumlah bilangan sentiasa padan dengan jumlah pesakit.

Muat turun atau e-mel borang Lampiran C

Butang Jana Lampiran C di penjuru halaman Laporan Bayaran mengeluarkan borang itu sebagai fail Excel. Ia terbuka kepada Kaunter, Pentadbir dan Superadmin — ketiga-tiganya memang sudah ada halaman Laporan Bayaran. Kaunter juga boleh sampai ke tempat yang sama melalui kad Lampiran C di halaman Jana Laporan.

Dalam kotak yang terbuka, pilih julat tarikh dahulu, kemudian pilih fail yang dikehendaki:

• Borang Lampiran C — borang rasmi yang ditandatangani, bagi julat tarikh yang dipilih, dalam bentuk fail PDF. Angkanya adalah angka yang sama seperti jadual di skrin, termasuk tanda sengkang pada baris yang sistem tiada rekod.
• Lejar harian — buku kerja harian bagi julat yang sama: satu baris setiap hari, dan satu tab bagi setiap bulan yang disentuh julat itu. Ini buku kerja, bukan borang yang dihantar.

Kenapa "prompt", bukan "auto"

Alat PWA (workbox) ada dua mod: autoUpdate (reload sendiri) & prompt (tunggu izin). Sistem ini sengaja guna prompt — kerana autoUpdate boleh reload di tengah kerja klinikal & hilangkan data yang belum disimpan.

VitePWA({
  // 'prompt' (bukan 'autoUpdate'): workbox TAK reload sendiri.
  // autoUpdate salah di sini sebab ia BOLEH hilangkan data pesakit.
  registerType: 'prompt',
})

Polisi kemas kini hibrid

Bila versi baru tersedia, masa ia dipasang bergantung pada keadaan pengguna — tiga senario:

Kawalan ini hidup dalam src/components/PwaUpdatePrompt.tsx. Bila tiba masanya, app hantar isyarat SKIP_WAITING kepada service worker, kemudian baru muat semula — versi baru dipasang tanpa kejutan.

Tiga jenis amaran

Sistem mengelaskan ralat kepada tiga peringkat — setiap satu warna berbeza dalam saluran amaran, supaya penyelenggara nampak sekali pandang mana yang paling kritikal:

Perjalanan satu amaran

Sebelum mesej amaran keluar dari sistem, ia melalui dua "pintu pelindung" penting: buang maklumat pesakit, kemudian tapis ulangan. Barulah ia sampai ke saluran hospital.

Pintu pelindung 1: buang maklumat pesakit

Ini sistem kesihatan — satu mesej ralat tak boleh sekali-kali membawa nombor IC, telefon, atau emel pesakit keluar dari pelayan. Sebelum apa-apa dihantar, sistem menyapu bersih corak ini dahulu & gantikan dengan label kosong. Lebih baik tersilap buang terlalu banyak daripada terlepas satu:

// IC Malaysia 991231-14-5678 → [IC]
.replace(/\b\d{6}-\d{2}-\d{4}\b/g, '[IC]')
// Emel → [EMAIL], telefon → [PHONE]
.replace(/\b[\w.+-]+@[\w-]+\.[\w.-]+\b/g, '[EMAIL]')

Pintu pelindung 2: tapis ulangan

Kalau satu kerosakan menyebabkan ralat pada setiap permintaan, sistem boleh hantar beratus mesej dalam seminit — membanjiri saluran sehingga tak berguna. Sebab itu amaran yang sama hanya dihantar sekali setiap seminit. Tujuannya kawalan banjir, bukan kira tepat.

Apa yang dicatat

Setiap baris audit menyimpan empat perkara sahaja — ringkas, tetapi cukup untuk menjawab "siapa, buat apa, bila":

Bagaimana satu catatan dibuat

await env.DB.prepare(
  'INSERT INTO audit_logs (id, user_id, action, created_at) VALUES (?, ?, ?, ?)'
).bind(log_id, userId, action, new Date().toISOString()).run();

Penjaga pintu: satu suis

Satu suis tunggal dalam pangkalan data — settings.setup_completed — menentukan sama ada wizard perlu dijalankan. Ia bermula pada 0 (belum siap) untuk setiap pemasangan baharu. Selagi ia 0, "penjaga pintu" (SetupGate) mengalihkan pengguna ke /setup:

Tujuh langkah wizard

Langkah pertama (tukar kata laluan) wajib — sistem tak boleh dibuka dengan kata laluan provision yang dikongsi. Langkah Identiti (nama hospital) juga wajib — ia dicetak pada borang rasmi PG201/PG211, jadi ia tidak boleh dilangkau. Langkah lain boleh dilangkau ("Buat nanti") & disiapkan kemudian — kecuali pilihan jabatan, yang kekal selepas wizard selesai:

Pasang untuk jabatan lain (bukan OMFS)

Secara lalai sistem ini ialah pemasangan OMFS — ia mengeluarkan borang kebangsaan PG201/PG211. Tetapi rangka kerja yang sama boleh dipasang untuk jabatan lain: pada Langkah 1 wizard ("Pilih Jabatan"), pilih "Jabatan lain". Ini menukar pakej laporan sahaja — pendaftaran pesakit, peranan pengguna, dan jadual on-call kekal sama.

Apa yang berubah bila jabatan = "lain":

Selepas wizard, bahagian yang boleh diubah berada di halaman superadmin "Tetapan Jabatan" (/superadmin/tetapan-jabatan) — nama paparan jabatan & teks panduan AI. Katalog disunting di /superadmin/katalog, di mana butang "Mula dari templat" muncul hanya untuk jabatan bukan OMFS.

Status persediaan: laluan terbuka

Skrin perlu tahu sama ada wizard sudah siap sebelum sesiapa log masuk — jadi pemeriksaan status ialah laluan awam (tiada token diperlukan), tetapi menyiapkan wizard tetap memerlukan superadmin:

// PUBLIC — frontend boleh semak sebelum log masuk
app.get('/api/setup/status', async (c) => {
  const row = await c.env.DB.prepare(
    'SELECT setup_completed FROM settings WHERE id = ?'
  ).bind('default').first();
  return ok(c, { setupCompleted: (row?.setup_completed ?? 0) === 1 });
});

Pintu pemeriksaan sebelum terbit

Ujian ditulis dahulu (TDD)

Untuk logik penting, jurutera kadang-kadang menulis ujian dahulu, sebelum kod sebenar — menyatakan "hasil yang betul sepatutnya begini", barulah menulis kod sehingga ujian lulus. Macam menetapkan jawapan peperiksaan dahulu, kemudian memastikan kerja anda menepatinya.

Cerita istimewa: satu sistem, banyak hospital

Sistem ini direka untuk diberi kepada banyak hospital. Setiap hospital mendapat salinan dalam akaun awan percuma mereka sendiri, dengan nama, logo, jadual on-call, & tetapan tersendiri. Pemilik menyimpan satu set "skrip" untuk memasang hospital baru dan mengemas kini semua hospital ke versi sama dengan satu arahan. Inilah sebab seni bina berlapis & "tiada nama ditanam keras" itu penting — ia membolehkan sistem berkembang tanpa menulis semula.

Boleh ubah TANPA kod (dalam aplikasi)

Perlu sentuh kod (minta bantuan AI + uji dahulu)

Untuk yang ini, ingat peta fail di Bahagian 06: src/ = Skrin, worker/ = Otak, migrations/ = struktur Ingatan.

App tunjuk ralat kepada pengguna

Tersilap padam data

Cloudflare D1 ada "mesin masa" 7 hari (PITR). Langkah selamat:

# 1. Cari titik masa SEBELUM kerosakan
npx wrangler d1 time-travel info omfs-database --timestamp "2026-06-15T00:30:00Z"

# 2. Backup keadaan SEKARANG dulu (selamat)
npx wrangler d1 export omfs-database --remote --output=./backup.sql

# 3. Pulihkan ke titik tadi
npx wrangler d1 time-travel restore omfs-database --bookmark "<id-dari-langkah-1>"

Deploy rosak — app jadi tak berfungsi

Database tiba-tiba lambat

Biasanya kerana "index" hilang. Jalankan EXPLAIN QUERY PLAN SELECT …; jika ia kata SCAN TABLE, buat migration baru dengan CREATE INDEX.

Fail rujukan dalam projek (untuk dibaca bila bersedia)