# Nota Pembelajaran — Faham SELURUH Kod Sistem OMFS (guna Claude Code)

> **Apa ini:** satu silibus boleh-tanda (checklist) untuk faham **seluruh** kod app ini,
> satu sesi pada satu masa, menggunakan **Claude Code sebagai cikgu**. Bukan untuk
> dihafal — untuk dikerjakan ikut turutan, sambil tanya soalan susulan.
>
> **Pasangan panduan:** baca dulu `PANDUAN-KOD-01-asas-bahasa.html` (asas), rujuk
> `PANDUAN-KOD-02-contoh-fail.html` (10 bentuk fail) & `PANDUAN-KOD-03-modul.html`
> (6 ciri). Fail ini ialah *pelan tindakan* yang lebih lengkap daripada ketiga-tiganya:
> ia tambah **fail-wiring, ujian, sub-sistem, ops, dan konvensyen** yang panduan HTML
> tak liputi sepenuhnya.
>
> **Cara tanda:** tukar `- [ ]` jadi `- [x]` bila siap. Minta Claude Code kemas kini fail
> ini: *"Tandakan sesi yang kita baru habis dalam `docs/LEARNING-NOTES.md`, dan tambah 1
> baris dalam Log di bawah."*
>
> **Laluan fail disahkan 2026-06-18.** Kod berubah — kalau satu fail dah berpindah, tanya
> Claude Code *"di mana sekarang fail X?"*.
>
> **Realiti jujur:** tiada dokumen statik boleh terangkan *setiap baris* (≈59,000 baris).
> Silibus ini bawa anda melalui setiap **kawasan** dan **bentuk** utama; untuk baris-baris
> khusus yang berbaki, Claude Code ialah cikgu atas-permintaan anda. Habis silibus ini =
> anda boleh buka mana-mana fail dan faham konteksnya.

---

## Falsafah (baca sekali, ingat selalu)

1. **Belajar BENTUK + WIRING, bukan setiap fail.** ~440 fail tetapi ~10 bentuk berulang,
   disambung oleh beberapa fail "wiring". Faham bentuk + wiring = faham keseluruhan.
2. **Claude Code = cikgu hidup.** Ia baca kod **terkini**, jawab pada tahap anda, tahan
   soalan bertimbun. Dokumen statik tak boleh.
3. **Faham > siap cepat.** Minta ia *terangkan* dulu; jangan biar ia terus tulis kod.
4. **Sahkan dengan buat.** Satu perubahan kecil sebenar > sepuluh penjelasan (Bahagian 11).
5. **"Seluruh kod" = bentuk + wiring + ujian + ops + konvensyen.** Lima tiang. Silibus ini
   meliputi kelima-lima, bukan hanya kod ciri.

---

## Mula setiap sesi (salin-tampal ini DULU)

```
Baca CLAUDE.md dan graphify-out/GRAPH_REPORT.md dahulu untuk faham struktur projek ini.
Saya sedang belajar coding dari sifar — anggap saya tak tahu jargon, dan terangkan dalam
bahasa mudah. Jangan ubah apa-apa kod; saya nak FAHAM dulu.
```

Kemudian jalankan **kitaran 4-langkah** untuk setiap fail/ciri:
1. **Orientasi** — minta gambaran 5-bullet sebelum masuk dalam.
2. **Dalami** — "terangkan baris demi baris".
3. **Tanya kenapa** — soalan susulan sampai faham ("terangkan macam saya 12 tahun").
4. **Generalisasi** — "tunjuk 2 fail lain yang ikut bentuk sama; apa beza?".

---

## BAHAGIAN 0 — Persediaan (sekali sahaja)

- [ ] Pasang/buka **Claude Code** + editor (VS Code). Rujuk `PANDUAN-KOD-01` §08.
- [ ] Buka folder projek di editor supaya boleh tengok fail sambil bertanya.
- [ ] Baca penuh **`PANDUAN-KOD-01-asas-bahasa.html`** sekali (00 → 10). Tak faham 100% = normal.
- [ ] **Jalankan app secara tempatan** sekali, supaya belajar terhadap benda hidup:
  ```
  Terangkan langkah demi langkah untuk jalankan app ini di komputer saya: npm install,
  npm run seed:e2e, npm run dev (port apa?), dan macam mana saya log masuk untuk uji.
  Rujuk CLAUDE.md + package.json. Saya pemula.
  ```

> **Faham bila:** app berjalan di browser anda, dan anda boleh terangkan beza frontend /
> backend / database.

---

## BAHAGIAN 1 — Orientasi besar (2 sesi)

- [ ] **1.1 — Gambaran seni bina.**
  ```
  Guna CLAUDE.md + GRAPH_REPORT.md. Beri gambaran seni bina Sistem OMFS dalam 10 bullet:
  bahagian besar, teknologi setiap satu, dan aliran data dari pengguna tekan butang
  sampai database dan balik. Bahasa mudah.
  ```
- [ ] **1.2 — 10 bentuk fail.**
  ```
  Senaraikan ~10 "bentuk" fail dalam repo ini. Untuk setiap bentuk, beri SATU contoh fail
  sebenar paling bersih untuk belajar + satu ayat tugasnya.
  ```
- [ ] **1.3 — Peraturan & corak terlarang (baca awal, jimat masa nanti).**
  ```
  Ringkaskan CLAUDE.md bahagian "Forbidden patterns" + fail dalam .claude/rules/.
  Senaraikan peraturan utama projek ini (auth via middleware, no raw DB in routes, no
  `any`, no silent catch, role names Malay, cascade visits) dan SATU ayat kenapa setiap
  satu wujud. Saya nak elak melanggar tanpa sedar.
  ```

> **Faham bila:** anda boleh teka "ini bentuk apa" bila buka fail rawak, dan tahu 5
> perkara yang TAK boleh dibuat dalam repo ini.

---

## BAHAGIAN 2 — Backend: satu kepingan + wiring (8 sesi)

Slice menegak (contract→route→service→middleware), kemudian fail-fail **wiring** yang
menyambung semuanya.

- [ ] **2.1 — Contract (Zod).** `worker/contracts/hospital.contracts.ts`
  ```
  5-bullet overview, kemudian baris demi baris. Apa itu Zod, .min(1)/.email()/.optional(),
  z.infer? Kenapa "satu sumber kebenaran"?
  ```
- [ ] **2.2 — Route (pintu).** `worker/routes/hospital.ts`
  ```
  Baris demi baris. Beza GET vs PUT? Kenapa route tak sentuh DB terus? Apa requireRole &
  safeParse?
  ```
- [ ] **2.3 — Service (pekerja).** `worker/services/HospitalConfigService.ts`
  ```
  Apa itu class & constructor? Kenapa update() buat 3 benda bersama? Apa .bind & kenapa ia
  penting untuk keselamatan SQL?
  ```
- [ ] **2.4 — Middleware (kunci).** `worker/middleware/auth.ts`
  ```
  Apa itu middleware & next()? Beza 401 vs 403? Di mana 'jwtPayload' diletak sebelum fail
  ini membacanya?
  ```
- [ ] **2.5 — Type kongsi (jambatan front↔back).** `shared/types.ts`
  ```
  Terangkan peranan shared/types.ts. Kenapa frontend DAN backend import dari sini? Apa itu
  UserRole dan kenapa nama peranan mesti Malay (pendaftar/doktor/pentadbir/superadmin)?
  ```
- [ ] **2.6 — Utiliti teras.** `worker/core-utils.ts`
  ```
  Terangkan worker/core-utils.ts. Apa itu signJwt/verifyJwt, dan kenapa token 'system'
  hidup 30 hari tapi token peranan 12 jam? Apa pembantu ok()/bad()/unauthorized()/
  forbidden() dan kenapa setiap route guna ia?
  ```
- [ ] **2.7 — WIRING backend (fail paling penting).** `worker/index.ts`
  ```
  Terangkan worker/index.ts pada altitud tinggi dahulu, kemudian bahagian penting. Macam
  mana JWT disahkan secara pusat? Apa itu PUBLIC_PATHS & PUBLIC_GET_PATHS? Macam mana
  middleware prefix /api/admin/*, /api/superadmin/* menguatkuasakan peranan? Di mana
  semua route didaftar (mount), dan apa itu cron + app.onError?
  ```
- [ ] **2.8 — Generalisasi.**
  ```
  Saya faham slice hospital + core-utils + index.ts. Tunjuk worker/routes/oncall.ts —
  sahkan ia ikut corak sama, terangkan apa berbeza & kenapa.
  ```

> **Faham bila:** anda boleh lukis rantaian "permintaan → index.ts (sahkan JWT + gate
> prefix) → middleware route → semak Zod → service → DB → balas", dan tahu di mana
> route awam diisytihar.

---

## BAHAGIAN 3 — Database & migrasi (3 sesi) ⚠️ jebakan paling bahaya

- [ ] **3.1 — Migration mudah.** `migrations/0002_add_tarikh_lahir.sql`
  ```
  Apa itu migration & kenapa bernombor? Kenapa ALTER TABLE ADD COLUMN selamat?
  ```
- [ ] **3.2 — Migration bahaya (cascade).** `migrations/0026_reten_batal_pulang_awal.sql`
  ```
  Terangkan macam saya 12 tahun. Apa ON DELETE CASCADE? Kenapa DROP TABLE visits boleh
  padam data anak (visit_doctors, diagnoses, managements)? Terangkan tarian "salin → bina
  semula → pulang".
  ```
- [ ] **3.3 — Peraturan keselamatan DB + PITR.**
  ```
  Baca .claude/rules/database.md + CLAUDE.md §5. Ringkaskan peraturan DB yang TAK BOLEH
  dilanggar (--remote, kiraan binding INSERT, cascade visits) dan macam mana pemulihan
  time-travel (PITR) berfungsi kalau data hilang.
  ```

> **Faham bila:** anda boleh terangkan kenapa bina-semula table itu bahaya, dan apa mesti
> dibuat dulu sebelum DROP TABLE visits.

---

## BAHAGIAN 4 — Frontend: bentuk + glue (7 sesi)

- [ ] **4.1 — Router (peta laluan).** `src/main.tsx`
  ```
  Terangkan bahagian router (createBrowserRouter). Apa itu JSX/path/element/children?
  Apa PrivateRoute & AppLayout yang membungkus? Apa lazy() & kenapa?
  ```
- [ ] **4.2 — Context provider + custom hook.** `src/contexts/HospitalConfigProvider.tsx`
  ```
  Baris demi baris. Apa useState/useEffect/context/custom hook (useHospitalConfig)? Kenapa
  useEffect ada [update]? Apa .catch(swallow(...))?
  ```
- [ ] **4.3 — Komponen daun.** `src/components/PrivateRoute.tsx`
  ```
  Apa itu props (children, allowedRoles)? Kenapa keselamatan frontend "tak boleh
  dipercayai" & backend yang sebenar jaga?
  ```
- [ ] **4.4 — Hook custom (ambil data).** `src/hooks/useServerTime.ts`
  ```
  Apa corak "loading state"? Kenapa ada bendera 'cancelled'? Apa try/catch/finally & fungsi
  cleanup yang useEffect pulangkan?
  ```
- [ ] **4.5 — Halaman penuh.** `src/pages/registrar/PatientRegistrationPage.tsx`
  ```
  Altitud tinggi dulu (apa ia buat), kemudian macam mana ia gabung hook + komponen +
  panggilan API. Mana borang dihantar ke backend?
  ```
- [ ] **4.6 — GLUE: api-client (macam mana frontend cakap dengan backend).** `src/lib/api-client.ts`
  ```
  Terangkan src/lib/api-client.ts. Macam mana ia lampir token Authorization? Apa berlaku
  pada respons 401, dan kenapa ia bezakan roleToken vs systemToken (ke mana ia halau
  pengguna)?
  ```
- [ ] **4.7 — GLUE: stor auth dua-peringkat.** `src/hooks/useAuth.ts`
  ```
  Terangkan src/hooks/useAuth.ts. Apa itu "store" (zustand)? Apa beza systemToken vs
  roleToken, dan tindakan loginSystem/login/logoutRole/logout? Rujuk .claude/rules/
  frontend.md "Auth tokens". Kenapa dua token, bukan satu?
  ```

> **Faham bila:** anda boleh terangkan macam mana satu klik butang jadi panggilan API
> bertoken, dan apa jadi bila sesi tamat tempoh (401).

---

## BAHAGIAN 5 — Sambung: jejak ciri hujung-ke-hujung (2 sesi)

- [ ] **5.1 — Jejak "simpan tetapan hospital".**
  ```
  Jejak SETIAP fail terlibat bila superadmin simpan tetapan hospital, dari klik butang
  sampai data masuk DB & balik. Senaraikan ikut turutan, kaitkan setiap langkah dengan
  bentuk fail yang saya dah belajar (termasuk index.ts & api-client).
  ```
- [ ] **5.2 — Jejak "daftar pesakit baru".**
  ```
  Jejak aliran penuh "daftar pesakit baru": PatientRegistrationPage → api-client → index.ts
  → route → contract → service → DB → balas. Apa validation di setiap lapisan? Di mana
  jejak audit ditulis?
  ```

> **Faham bila:** diberi mana-mana butang, anda boleh teka fail mana terlibat & susunannya.

---

## BAHAGIAN 6 — Ciri penuh (6 sesi ringan)

Baca `PANDUAN-KOD-03-modul.html` dahulu, kemudian dalami pada kod. Pilih ikut minat.

- [ ] **6.1 — Laporan PG201/PG211.** `src/lib/xlsx-utils.ts` (barrel) → `xlsx-pg211.ts`
  ```
  Macam mana xlsx-pg211.ts isi borang PG211 dari template public/templates/? Apa itu
  "barrel"? Apa isDoNotFill() & 4 peraturan MOH?
  ```
- [ ] **6.2 — Eksport & muat turun.** `src/pages/admin/ReportingPage.tsx`
  ```
  Jejak jana laporan dari klik sampai fail Excel turun. Kenapa fail dibina dalam browser?
  ```
- [ ] **6.3 — Hantar e-mel.** `worker/email.ts`
  ```
  Baris demi baris. Apa jadi kalau RESEND_API_KEY tak diset (graceful fallback)? Apa itu
  "secret" & kenapa rahsia tak boleh dalam kod?
  ```
- [ ] **6.4 — Pengendalian ralat.** `src/lib/swallow.ts` · `errorReporter.ts` · `worker/db/rows.ts`
  ```
  Beza swallow('reason') vs .catch kosong? Macam mana errorReporter.ts hantar ralat ke
  pemilik? Apa guna rows<T>() vs 'as any[]'? Kenapa "gagal senyap" dilarang?
  ```
- [ ] **6.5 — Pembantu AI.** `src/components/panduan/ai-chat/useAiChat.ts`
  ```
  Macam mana ia simpan & muat sesi perbualan? Di mana sejarah disimpan & bila dibuang (TTL,
  MAX_SESSIONS)?
  ```
- [ ] **6.6 — Enjin keadilan on-call.** `worker/oncall/fairness.ts`
  ```
  Terangkan strategi macam saya bukan coder. Apa "pure function" & kenapa mudah diuji? Apa
  "skor keadilan", kenapa orang yang kerja semalam tak boleh dipilih (R16)? Apa jadi kalau
  slot tiada calon sah?
  ```

> **Faham bila:** untuk satu ciri, anda boleh sebut fail terlibat & gotcha utamanya.

---

## BAHAGIAN 6B — Ciri lain (variasi bentuk yang dah dipelajari)

Ciri-ciri ini bukan bentuk baru — ia gabungan page + route + service + hook yang anda dah
kenal. Satu prompt setiap satu; guna bila anda perlukannya.

- [ ] **6B.1 — Temu janji (appointments).** `src/pages/shared/AppointmentPage.tsx`
  ```
  Terangkan ciri temu janji: AppointmentPage.tsx + route/service backendnya. Bentuk apa
  setiap fail ikut? Siapa boleh CRUD temu janji (rujuk .claude/rules/api.md)?
  ```
- [ ] **6B.2 — Mesej (inbox dalaman).** `src/pages/.../MessagesPage` (path `mesej`)
  ```
  Terangkan ciri Mesej: macam mana mesej dihantar & dibaca, jadual DB messages, dan macam
  mana swap on-call drop mesej ke inbox pengurus.
  ```
- [ ] **6B.3 — Pemapar log audit.** `src/pages/admin/AuditLogPage.tsx`
  ```
  Terangkan AuditLogPage.tsx & jadual audit_logs. Apa yang dilog (logAction), dan kenapa
  actor mesti dari jwt.sub bukan dari badan permintaan?
  ```
- [ ] **6B.4 — Import pesakit (pukal).** `src/pages/admin/ImportPesakitPage.tsx`
  ```
  Terangkan aliran import pesakit pukal: baca fail, sahkan, masuk DB. Apa risiko & semakan
  yang perlu untuk import pukal?
  ```
- [ ] **6B.5 — Kemas kini PWA.** `src/components/PwaUpdatePrompt.tsx`
  ```
  Terangkan PwaUpdatePrompt.tsx. Apa itu PWA & service worker? Macam mana app tahu ada
  versi baru, dan kenapa registerType kekal 'prompt' bukan 'autoUpdate'? (Rujuk gotcha PWA.)
  ```
- [ ] **6B.6 — PG101B / Google Sheets.** `worker/google-sheets.ts` · `src/lib/xlsx-pg101b.ts`
  ```
  Terangkan ciri PG101B: macam mana data dihantar ke Google Sheets (worker/google-sheets.ts)
  dan/atau dijana sebagai Excel (xlsx-pg101b.ts). Route mana mencetuskannya?
  ```
- [ ] **6B.7 — Laporan pesakit komprehensif.** `src/pages/admin/ComprehensivePatientReportingPage.tsx`
  ```
  Terangkan ComprehensivePatientReportingPage.tsx — macam mana ia berbeza dari ReportingPage,
  dan bentuk fail mana ia ikut.
  ```

> **Faham bila:** anda nampak ciri-ciri ini hanyalah gabungan bentuk yang sama — dan anda
> boleh fahamkan mana-mana ciri baru dengan kaedah yang sama tanpa panduan khas.

---

## BAHAGIAN 7 — Sub-sistem & lapisan besar (3 sesi)

Kawasan besar yang panduan HTML hanya sentuh ringan. Faham bentuknya, bukan setiap baris.

- [ ] **7.1 — Sub-sistem on-call (penuh).** `worker/routes/oncall.ts` · `src/pages/oncall/*`
  ```
  Beri peta sub-sistem on-call: routes (worker/routes/oncall.ts), halaman awam vs pengurus
  (OncallPublicPage / OncallManagerPage), dan "auth dua-pintu" (POST /api/login/oncall).
  Kenapa on-call ada token sendiri berasingan dari auth utama?
  ```
- [ ] **7.2 — Multi-hospital & config + setup wizard.** `migrations/0045_hospital_config.sql` · `src/pages/superadmin/setup/SetupWizardPage.tsx`
  ```
  Terangkan lapisan multi-hospital: jadual hospital_config (singleton), kenapa GET
  /api/hospital/config PUBLIC, dan macam mana setup wizard (settings.setup_completed)
  jalan untuk hospital baru. Rujuk CLAUDE.md bahagian M5.
  ```
- [ ] **7.3 — Provisioning & fleet (edaran).** `scripts/provision-hospital.mjs` · `scripts/release-all.mjs`
  ```
  Terangkan macam mana hospital baru distand-up (provision-hospital.mjs + docs/
  PROVISIONING.md) dan macam mana satu kemas kini dihantar ke semua hospital (release-all
  .mjs + docs/FLEET-OPERATIONS.md). Kenapa setiap hospital ada akaun Cloudflare sendiri?
  ```

> **Faham bila:** anda boleh terangkan macam mana app yang sama melayani banyak hospital
> tanpa kod dikeraskan (hardcode) untuk satu hospital.

---

## BAHAGIAN 8 — Ujian (tests) — tiang yang sering dilupakan (3 sesi)

- [ ] **8.1 — Ujian contract/unit.** `worker/__tests__/hospital-config-contracts.test.ts`
  ```
  Terangkan worker/__tests__/hospital-config-contracts.test.ts baris demi baris. Apa itu
  test/expect? Apa yang ujian ini sebenarnya semak, dan kenapa contract diuji?
  ```
- [ ] **8.2 — Ujian integrasi (D1 sebenar).** `worker/__tests__/auth.test.ts`
  ```
  Terangkan auth.test.ts. Kenapa projek ini guna D1 SEBENAR (Miniflare) dalam ujian dan
  BUKAN mock? (Rujuk CLAUDE.md "Mocking D1 in tests" — ada insiden lampau.) Macam mana
  saya jalankan satu fail ujian: npm test -- <nama>?
  ```
- [ ] **8.3 — Ujian e2e (browser).** `e2e/logout-redirect.spec.ts`
  ```
  Terangkan e2e/logout-redirect.spec.ts. Apa itu Playwright & "e2e"? Macam mana ia memandu
  browser sebenar untuk uji aliran log keluar? Bila guna e2e vs unit test?
  ```

> **Faham bila:** anda boleh baca satu ujian dan kata apa ia lindungi, dan jalankan ujian
> berkaitan sebelum & selepas perubahan.

---

## BAHAGIAN 9 — Ops: build, deploy, CI, observability (3 sesi)

- [ ] **9.1 — Push = deploy (CI/CD).** `.github/workflows/deploy.yml`
  ```
  Terangkan .github/workflows/deploy.yml. Kenapa "push ke main = deploy"? Apa job ci vs
  deploy, dan kenapa ci merah = tiada deploy? Macam mana saya sahkan deploy berjaya
  (gh run watch)? Rujuk CLAUDE.md "Deployment".
  ```
- [ ] **9.2 — Wrangler, secrets & apply migrasi.** `wrangler.jsonc`
  ```
  Terangkan peranan wrangler & wrangler.jsonc. Macam mana migrasi diapply ke produksi
  (--remote), dan macam mana "secret" (cth RESEND_API_KEY, JWT_SECRET) diset tanpa masuk
  kod? Kenapa --remote penting?
  ```
- [ ] **9.3 — Observability (amaran ralat).** `worker/observability/alert.ts`
  ```
  Terangkan worker/observability/alert.ts. Macam mana ralat dihantar ke Discord, dan macam
  mana PII di-scrub + dedup? Kenapa ia "opt-in" (no-op kalau DISCORD_WEBHOOK_URL tak diset)?
  ```

> **Faham bila:** anda boleh terangkan perjalanan satu commit dari `git push` sampai hidup
> di internet, dan di mana rahsia disimpan.

---

## BAHAGIAN 10 — Konvensyen & disiplin (1 sesi)

- [ ] **10.1 — Peraturan rumah (baca semua).**
  ```
  Untuk setiap fail dalam .claude/rules/ (api, database, frontend, services, methodology,
  naming, refactor, testing, token-budget, legacy-files), beri saya 2-bullet ringkasan apa
  ia kuatkuasakan. Mana 3 yang paling kerap saya akan langgar sebagai pemula, dan macam mana
  elak?
  ```

> **Faham bila:** anda tahu di mana cari "cara betul" buat sesuatu dalam projek ini sebelum
> menulis kod.

---

## BAHAGIAN 11 — Belajar dengan BUAT (latihan selamat) 🛠️

Rujuk `PANDUAN-DEVELOPER-OMFS.html` §12. Buat 🟢 dahulu. Selepas SETIAP perubahan:
`npx tsc --noEmit && npm run build && npm test`.

- [ ] **11.1 (🟢) — Tukar satu teks/label.**
  ```
  Apa perubahan teks paling kecil & selamat untuk belajar, yang takkan rosakkan apa-apa?
  Tunjuk fail + baris tepat + langkah lihat hasil dengan npm run dev. Terang dulu; saya buat
  sendiri.
  ```
- [ ] **11.2 (🟢) — Faham warna/tema.** `src/index.css`
  ```
  Tunjuk di mana warna teal utama ditetapkan (--color-* token) & macam mana ia diguna semula
  seluruh app. Jangan ubah — terang dulu.
  ```
- [ ] **11.3 (🟡) — Resipi "tambah satu medan" (5 fail selari).**
  ```
  Tanpa tulis kod lagi, terangkan resipi "tambah medan baru pada borang + simpan ke DB" — 5
  tempat selari (migration, contract, service, shared/types, UI). Kenapa kiraan kolum = ? =
  .bind mesti sama?
  ```
- [ ] **11.4 — Buat satu 🟢 betul-betul.** Pilih 11.1, buat, jalankan gate, lihat hasil.

> **Faham bila:** anda dah buat perubahan sebenar, nampak ia jalan, faham kenapa gate
> (tsc/build/test) penting.

---

## BAHAGIAN 12 — Tabiat berterusan (guna selamanya)

- **Guna otot navigasi Claude Code:** *"Di mana X ditakrif?"* · *"Apa memanggil Y?"* · *"Apa
  rosak kalau saya ubah ini?"* · *"Guna GRAPH_REPORT.md — fail mana berkaitan ciri Z?"*
- **Orientasi sebelum dalami** — sentiasa minta 5-bullet overview dahulu.
- **Pin tahap anda** — "saya pemula, tiada jargon".
- **Buntu satu baris** — salin, tampal, tanya "apa maksud baris ni?".
- **Catat** — *"Ringkaskan apa kita belajar dalam 5 bullet + tambah ke Log dalam
  docs/LEARNING-NOTES.md."*

**Elak:** "terangkan seluruh codebase" sekaligus (cetek) · biar Claude Code *tulis* bila
matlamat *belajar* · baca ikut abjad tanpa pelan.

---

## Peta liputan (adakah saya dah faham "seluruh"?)

Tanda bila satu kawasan terasa "boleh saya baca sendiri sekarang":

- [ ] Backend: request lifecycle (index.ts → middleware → route → service → DB)
- [ ] Backend: contract (Zod) + shared/types + core-utils (JWT/helpers)
- [ ] Database: migrasi (mudah + cascade) + peraturan keselamatan
- [ ] Frontend: shapes (router/context/hook/component/page)
- [ ] Frontend: glue (api-client + auth store dua-peringkat)
- [ ] Ciri: laporan, eksport, e-mel, error-handling, AI, fairness
- [ ] Sub-sistem: on-call · multi-hospital/config · provisioning/fleet
- [ ] Ujian: unit/contract · integrasi (D1 sebenar) · e2e
- [ ] Ops: deploy/CI · wrangler/secrets · observability
- [ ] Konvensyen: .claude/rules/* + corak terlarang

> Kalau semua di atas ditanda, anda faham seni bina + setiap kawasan. Baris-baris khusus
> yang berbaki = tanya Claude Code atas-permintaan.

---

## LOG PEMBELAJARAN (Claude Code tambah di sini)

> Selepas setiap sesi: *"Tambah satu baris ke jadual Log dalam LEARNING-NOTES.md: tarikh,
> sesi, 1 perkara baru yang saya faham, 1 perkara masih kabur."*

| Tarikh | Sesi | Faham baru | Masih kabur |
|--------|------|------------|-------------|
| _(contoh)_ 2026-06-18 | 2.2 Route | route tipis; ia upah service | kenapa `async` di mana-mana |
|  |  |  |  |

---

## Senarai pantas fail rujukan (anchor setiap bentuk/kawasan)

| Kawasan / bentuk | Fail anchor |
|------------------|-------------|
| Contract (Zod) | `worker/contracts/hospital.contracts.ts` |
| Route | `worker/routes/hospital.ts` (kemudian `oncall.ts`) |
| Service | `worker/services/HospitalConfigService.ts` |
| Middleware | `worker/middleware/auth.ts` |
| Type kongsi | `shared/types.ts` |
| Utiliti teras (JWT/helpers) | `worker/core-utils.ts` |
| **Wiring backend** | `worker/index.ts` |
| Migration mudah | `migrations/0002_add_tarikh_lahir.sql` |
| Migration cascade | `migrations/0026_reten_batal_pulang_awal.sql` |
| Router | `src/main.tsx` |
| Context + hook | `src/contexts/HospitalConfigProvider.tsx` |
| Komponen daun | `src/components/PrivateRoute.tsx` |
| Hook custom | `src/hooks/useServerTime.ts` |
| Halaman | `src/pages/registrar/PatientRegistrationPage.tsx` |
| **Glue: api-client** | `src/lib/api-client.ts` |
| **Glue: auth store** | `src/hooks/useAuth.ts` |
| Laporan xlsx | `src/lib/xlsx-utils.ts` → `xlsx-pg211.ts` |
| E-mel | `worker/email.ts` |
| Error handling | `src/lib/swallow.ts` · `errorReporter.ts` · `worker/db/rows.ts` |
| Pembantu AI | `src/components/panduan/ai-chat/useAiChat.ts` |
| Fairness on-call | `worker/oncall/fairness.ts` · `swaps.ts` |
| On-call routes/pages | `worker/routes/oncall.ts` · `src/pages/oncall/*` |
| Multi-hospital/config | `migrations/0045_hospital_config.sql` · `SetupWizardPage.tsx` |
| Provisioning/fleet | `scripts/provision-hospital.mjs` · `scripts/release-all.mjs` |
| Ujian (unit/contract) | `worker/__tests__/hospital-config-contracts.test.ts` |
| Ujian (integrasi D1) | `worker/__tests__/auth.test.ts` |
| Ujian (e2e) | `e2e/logout-redirect.spec.ts` |
| Deploy/CI | `.github/workflows/deploy.yml` · `wrangler.jsonc` |
| Observability | `worker/observability/alert.ts` |
| Konvensyen | `.claude/rules/*.md` · `CLAUDE.md` |
| Peta projek | `CLAUDE.md` · `graphify-out/GRAPH_REPORT.md` |