Contoh Fail Sebenar

import { z } from 'zod';                       ← bawa masuk Zod — alat penyemak bentuk data

const ContactSchema = z.object({         ← takrif bentuk "contact": satu objek dengan…
  tel: z.string(),                       ← …medan 'tel' mesti teks (string)
  email: z.string().email().or(z.literal('')), ← e-mel: format SAH, ATAU teks kosong
});

export const HospitalIdentitySchema = z.object({ ← bentuk PENUH satu hospital…
  appName: z.string().min(1),             ← nama app: teks, sekurang-kurangnya 1 huruf
  hospitalName: z.string().min(1),        ← nama hospital: wajib ada isi
  contact: ContactSchema,                  ← guna semula bentuk 'contact' di atas
  // …medan lain (address, letterhead, logos…)
});

export type HospitalIdentityInput =       ← jana 'jenis' TypeScript automatik…
  z.infer<typeof HospitalIdentitySchema>;     ← …DARI bentuk di atas (kontrak & jenis sentiasa sepadan)

export function registerHospitalRoutes(app) {  ← fungsi yang mendaftar semua pintu hospital

  app.get('/api/hospital/config', async (c) => { ← PINTU 1 (GET = baca). c = konteks (req+res)
    const svc = new HospitalConfigService(c.env, 'system'); ← upah 'pekerja' yang sentuh DB
    const config = await svc.get();    ← suruh ia ambil tetapan; tunggu siap (await)
    return ok(c, config);             ← balas { success:true, data: config }
  });

  app.put('/api/hospital/config',        ← PINTU 2 (PUT = kemas kini)…
    requireRole('superadmin'), async (c) => { ← …tapi KUNCI dulu: superadmin sahaja (e4)
      const parsed = UpdateHospitalConfigRequest.safeParse(body); ← semak data ikut kontrak (e1)
      if (!parsed.success) return bad(c, '…'); ← bentuk salah → tolak dgn mesej ralat
      const updated = await svc.update(parsed.data); ← data sah → suruh pekerja simpan
      return ok(c, updated);
    });
}

export class HospitalConfigService {        ← 'pekerja' yang tahu baca/tulis tetapan hospital
  constructor(private env, private actorId) {} ← bila diupah, ingat: env (akses DB) + siapa buat

  async get() {                            ← tindakan: ambil tetapan
    const row = await this.env.DB.prepare( ← sedia satu arahan SQL untuk DB…
      'SELECT config FROM hospital_config WHERE id = 1', ← …ambil baris tunggal (id=1)
    ).first();                          ← jalankan, ambil baris pertama
    if (!row) return DEFAULT_HOSPITAL_IDENTITY; ← tiada baris? pulang nilai lalai (fallback)
    // …sahkan ikut kontrak (e1) sebelum pulang
  }

  async update(patch) {                     ← tindakan: kemas kini sebahagian tetapan
    const current = await this.get();   ← ambil yang sedia ada dulu
    const merged = { ...current, ...patch }; ← gabung: mula dari lama, timpa dengan baru
    const validated = HospitalIdentitySchema.parse(merged); ← sahkan hasil gabungan (kontrak e1)
    await this.env.DB.prepare(`INSERT … ON CONFLICT … DO UPDATE`) ← simpan (cipta-atau-ganti)
      .bind(JSON.stringify(validated), this.actorId).run();
    await logAction(this.env, this.actorId, 'UPDATE_HOSPITAL_CONFIG'); ← jejak audit: siapa buat apa
    return validated;
  }
}

export const requireRole = (...roles) => ← fungsi yang PULANGKAN satu penjaga…
  async (c, next) => {                ← …penjaga = fungsi yang lari SEBELUM handler
    const jwt = c.get('jwtPayload');    ← ambil 'pas masuk' pengguna (token disahkan)
    if (!jwt) return unauthorized(c); ← tiada pas → 401 (belum log masuk)
    if (!roles.includes(jwt.role)) {  ← pas ada, tapi peranan tak dibenarkan…
      return forbidden(c, '…');     ← …→ 403 (dilarang)
    }
    return next();                  ← lulus semua → teruskan ke handler pintu
  };

-- Add tarikh_lahir column to patients table   ← komen: apa migration ini buat (untuk manusia)
ALTER TABLE patients ADD COLUMN tarikh_lahir TEXT; ← tambah satu lajur baru 'tarikh_lahir' (jenis teks)

-- DROP TABLE visits cetus DELETE tersembunyi → CASCADE padam anak.
-- Maka: salin anak DULU sebelum buang ibu.

CREATE TABLE _mig0026_backup_visit_doctors AS SELECT * FROM visit_doctors; ← salin anak (selamat)
CREATE TABLE _mig0026_backup_diagnoses    AS SELECT * FROM diagnoses;
CREATE TABLE _mig0026_backup_managements  AS SELECT * FROM managements;

CREATE TABLE visits__mig0026 ( /* …CHECK diperluas: tambah 'BATAL' */ ); ← bina visits baru
INSERT INTO visits__mig0026 SELECT * FROM visits;  ← pindah data lama ke yang baru
DROP TABLE visits;                          ← buang yang lama (CASCADE padam anak — sebab itu kita salin!)
ALTER TABLE visits__mig0026 RENAME TO visits; ← namakan yang baru jadi 'visits'

INSERT OR IGNORE INTO visit_doctors SELECT * FROM _mig0026_backup_visit_doctors; ← pulang anak dari salinan
-- …sama untuk diagnoses & managements…
DROP TABLE _mig0026_backup_visit_doctors;     ← kemas: buang salinan sementara

const router = createBrowserRouter([     ← bina 'peta': alamat URL → halaman mana
  { path: "/", element: <HomePage /> },     ← alamat '/' → tunjuk HomePage
  { path: "/oncall/jadual",            ← alamat laman on-call awam…
    element: <OncallPublicPage /> },     ← …tunjuk halaman jadual on-call
  {
    element: <AppLayout />,             ← 'bekas' kongsi (header+menu) untuk anak di bawah
    children: [                          ← halaman-halaman di dalam bekas ini…
      {
        path: "/kaunter",
        element: <PrivateRoute allowedRoles={['pendaftar']}> ← KUNCI depan: pendaftar sahaja (e10)
                   <KaunterLayout /></PrivateRoute>,
        children: [                      ← sub-halaman di bawah '/kaunter'…
          { index: true, element: <RegistrarDashboardPage /> }, ← '/kaunter' → dashboard
          { path: "daftar", element: <PatientRegistrationPage /> }, ← '/kaunter/daftar' → borang daftar
        ],
      },
    ],
  },
]);

const HospitalConfigContext = createContext(DEFAULT_HOSPITAL_IDENTITY); ← cipta 'saluran siaran' global

export function HospitalConfigProvider({ children }) {  ← komponen yang menyiarkan tetapan ke anak
  const [config, setConfig] = useState(readCache() ?? DEFAULT_HOSPITAL_IDENTITY); ← ingatan: tetapan semasa
                                          ← useState beri [nilai, caraUbahNilai]

  useEffect(() => {                       ← lepas komponen muncul, jalankan sekali…
    fetch('/api/hospital/config')         ← …ambil tetapan terkini dari backend (pintu e2)
      .then(r => r.json())
      .then(({ data }) => { if (data) update(data); }) ← dapat → kemas kini paparan
      .catch(swallow('…'));            ← gagal rangkaian → biar; guna cache/lalai
  }, [update]);                            ← senarai kebergantungan (bila perlu jalan semula)

  return (
    <HospitalConfigContext.Provider value={config}> ← siarkan 'config' ke semua anak di dalam
      {children}
    </HospitalConfigContext.Provider>
  );
}

export function useHospitalConfig() {        ← 'hook' custom: cara mudah anak baca siaran
  return useContext(HospitalConfigContext); ← mana-mana komponen panggil ini → dapat tetapan
}

export function PrivateRoute({ children, allowedRoles }) { ← komponen pembalut: jaga siapa boleh masuk
  const isAuthenticated = useAuthStore(s => s.isAuthenticated); ← baca status log masuk dari stor auth
  const role = useAuthStore(s => s.role);    ← baca peranan pengguna

  if (!isAuthenticated || !role || !allowedRoles.includes(role)) { ← belum log masuk ATAU peranan salah…
    return <Navigate to={systemToken ? '/pilih-fungsi' : '/'} replace />; ← …halau ke laman yang sesuai
  }
  return children;                       ← lulus → tunjuk kandungan yang dijaga
}

export function useServerTime() {            ← hook custom: dapatkan masa dari server
  const [data, setData] = useState(null);  ← simpan hasil (mula: belum ada)
  const [loading, setLoading] = useState(true); ← simpan status 'sedang muat'

  useEffect(() => {                       ← lepas guna kali pertama, ambil masa…
    let cancelled = false;              ← bendera: elak set data kalau komponen dah tutup
    (async () => {
      try {
        const res = await api('/api/time'); ← panggil pintu '/api/time'
        if (!cancelled) setData(res.data); ← simpan hasil (kalau masih relevan)
      } catch {
        if (!cancelled) setData(null); ← gagal → biar kosong
      } finally {
        if (!cancelled) setLoading(false); ← apa pun jadi, 'muat' tamat
      }
    })();
    return () => { cancelled = true; };  ← bila komponen tutup, tanda 'batal'
  }, []);                                  ← [] = jalankan SEKALI sahaja

  return { data, loading };               ← bagi balik kepada komponen yang guna
}