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 — 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 — 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 — 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 — 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 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 kerana nombor pendaftaran unik hanya dikuatkuasakan untuk pesakit Baru.

Nombor pendaftaran & cara cegah pertembungan

Setiap pesakit Baru dapat nombor pendaftaran, & sistem tambah akhiran tahun secara automatik (cth. 123 → 123/2026). Masalahnya: dua petugas boleh cuba beri nombor sama pada masa hampir sama. Sistem hadang ini dengan dua lapisan.

Lapisan 2 ialah jaring keselamatan: walaupun dua daftar lolos serentak (perlumbaan), database sendiri ada peraturan unik (migration 0029, partial UNIQUE INDEX) yang menolak pendua. Pra-semak menjadikan kes biasa mesra (cadang nombor seterusnya); peraturan database menangkap kes jarang. Inilah kod sebenar yang menghasilkan mesej itu:

// Nombor ni dah dipakai untuk pesakit Baru?
if (dup) {
  // cari nombor terbesar tahun ni, cadang +1
  const next = (maxRow?.m ?? 0) + 1;
  throw new VisitValidationError(
    `Nombor pendaftaran ${noPendaftaran} sudah digunakan... Cuba ${next}/${year}.`
  );
}

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';

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.

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.

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

Apa yang dikira

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:

Enam langkah wizard

Langkah pertama (tukar kata laluan) wajib — sistem tak boleh dibuka dengan kata laluan provision yang dikongsi. Langkah 1–4 boleh dilangkau ("Buat nanti") & disiapkan kemudian:

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)