Panduan Developer

Untuk seseorang yang akan membaca & mengubah kod ini. Padat, tepat, dan mengandaikan anda selesa dengan TypeScript, HTTP, dan SQL. Seni bina, lapisan, kontrak, auth, database, deploy, ujian — dengan graf modul interaktif.

Mula baca kod dari sini (untuk manusia)

Turutan disyorkan untuk developer baru yang mahu faham aliran sebenar dengan pantas. Ini fail kod — bukan fail peraturan AI.

Untuk ejen AI (Claude / Cursor / Aider)

Jika anda membrief ejen AI, fail-fail ini ialah taklimat projek yang dibaca mesin — apa yang ejen patut baca dahulu (CLAUDE.md sendiri ditulis untuk ejen, bukan manusia). Sebagai manusia, anda boleh langkau ini — jadual kod di atas sudah memadai.

Setiap hospital = satu salinan Worker + satu D1 dalam akaun Cloudflare percuma mereka sendiri (lihat §09). Identiti per-instance hidup dalam jadual singleton hospital_config — tiada nama hospital ditanam keras.

Graf di bawah ialah seni bina lapisan secara interaktif. Tarik nod, hover untuk serlahkan kebergantungannya, scroll untuk zum.

📊 (Graf seni bina interaktif — buka dalam pelayar.)

Graf modul di bawah memetakan hubungan sebenar dalam kod — routes → services → contracts, enjin on-call, dan jadual D1. ~44 nod terpilih (bukan keseluruhan ~3950 — elak hairball).

📊 (Graf modul interaktif — buka dalam pelayar.)

Arahan harian

// 1. Kontrak Zod dulu (SDD) — wujud sebelum handler, jadi type FE juga
app.put('/api/hospital/config', requireRole('superadmin'), async (c) => {
  const body = UpdateHospitalConfigRequest.parse(await c.req.json());  // 400 jika salah bentuk
  const jwt = c.get('jwtPayload')!;                              // diisi oleh middleware
  const cfg = await new HospitalConfigService(c.env, jwt.sub).update(body);
  return ok(c, cfg);                                              // { success:true, data }
});

Budget saiz fail (dikuatkuasakan CI)

Hard-limit breach = CI gagal (node scripts/check-file-sizes.mjs). Nak sentuh fail yang sudah lepas hard limit → extract dulu (no-behaviour-change), commit, baru edit. Extract service bila: query sama di 3+ handler, mutasi perlu 2+ statement (withTx), atau peraturan sama dikuatkuasakan di >1 tempat.

Pintu: POST /api/login (role biasa), /api/login/superadmin, dan /api/login/oncall (pintu berasingan; role oncall dipagari hanya ke /api/oncall/*). signJwt/verifyJwt di core-utils.ts; hashPassword/verifyPassword di auth.ts (BUKAN core-utils). JWT_SECRET unik-rawak setiap instance — kunci dikongsi = pemalsuan token silang-instance.

Jadual: patients · visits · visit_doctors · diagnoses · managements · users · audit_logs · settings · appointments · messages · system_kv · hospital_config (singleton id=1).

Pemulihan: D1 menyimpan PITR (time-travel) 7 hari — wrangler d1 time-travel info/restore. Export safety dulu (wrangler d1 export --remote), restore, re-apply migrasi selepas bookmark.

Routing: react-router-dom v7 (src/main.tsx). State: zustand + React context (HospitalConfigProvider → useHospitalConfig(), dimuat dari GET /api/hospital/config yang awam — branding load sebelum auth). Borang: react-hook-form + zod. Halaman ikut role di src/pages/{admin,doctor,oncall,registrar,superadmin,shared}/.

Pecahkan komponen sebelum tambah ciri bila: >400 LOC (page) / >300 (leaf), >5 useState, >2 dialog, atau >3 domain. Helper yang di-extract pergi ke fail .ts (bukan sebelah komponen .tsx — peraturan react-refresh).

.github/workflows/deploy.yml: job ci (lint → typecheck → build → test → file-size) → job deploy (wrangler deploy, 3 retry untuk API 10013). CI merah = tiada deploy. Sahkan hijau (gh run watch) sebelum lapor "live".

Provisioning ≠ release. Provisioning = install pertama (cipta D1, migrate, set JWT_SECRET, putar kata laluan superadmin/admin yang di-seed dengan hash kongsi → bcrypt rawak baru). Release = kemas kini (tak sentuh secret; migrasi idempoten). Runbook: docs/PROVISIONING.md, docs/FLEET-OPERATIONS.md. Wizard pasang kali pertama di /setup dipagari flag settings.setup_completed.

Pemerhatian & ralat

worker/observability/alert.ts (sendAlert/dispatchAlert) hantar ke Discord — PII di-scrub + dedupe. Diwayar dalam worker/index.ts (app.onError, 4 cron catch, /api/client-errors). Opt-in melalui secret DISCORD_WEBHOOK_URL (no-op bila tak diset); env HOSPITAL_LABEL menanda instance.

Ujian

Vitest dengan @cloudflare/vitest-pool-workers — D1 Miniflare sebenar, TIADA mock D1 (sebab pernah berlaku: ujian mock lulus tapi migrasi prod gagal). E2E: Playwright (e2e/), seed via scripts/seed-e2e.sql (set setup_completed=1). Metodologi: SDD (Zod dulu) + TDD (service) + characterization (sebelum refactor legacy).

npx tsc --noEmit       # type check
npm run build          # esbuild (tangkap decl pendua yang tsc terlepas)
npm test               # vitest (D1 sebenar)
npm run lint:check     # eslint

Gotchas (footguns yang disahkan)

🟢 Sangat mudah — tukar teks / label pada skrin

🟢 Mudah — tukar warna / tema

🟡 Sederhana — tambah medan baru pada borang + simpan ke DB

1 ─ migrations/0047_patients_alergi.sql   (fail baharu — jalankan /migrate)
+ ALTER TABLE patients ADD COLUMN alergi TEXT;

2 ─ worker/contracts/patients.contracts.ts
  export const CreatePatientRequest = z.object({
    nama: z.string().min(1),
+   alergi: z.string().optional(),
  });

3 ─ worker/services/PatientService.ts   ← kolum = ? = .bind mesti kira bertiga
- INSERT INTO patients (nama)         VALUES (?)
+ INSERT INTO patients (nama, alergi)  VALUES (?, ?)
  ...
-   .bind(p.nama)
+   .bind(p.nama, p.alergi ?? null)

4 ─ shared/types.ts
  export interface Patient {
    nama: string;
+   alergi?: string;
  }

5 ─ src/pages/registrar/PatientRegistrationPage.tsx   (react-hook-form)
+ <FormField name="alergi" control={form.control} render={({ field }) => (
+   <Input placeholder="Alergi (jika ada)" {...field} />
+ )} />

🟡 Sederhana — tambah route API baru

🟠 Sukar — tambah jadual D1 baru (hujung ke hujung)

🔴 Sangat sukar — ubah algoritma keadilan on-call

Nota tajam per ciri