Panduan Kod · Bahagian 01 · Sistem OMFS

Asas & Bahasa

Untuk anda yang tidak tahu coding langsung, tetapi mahu belajar dengan membedah aplikasi sebenar ini — dari sifar. Kita mula dengan: apa itu kod, macam mana nak baca kod, 4 bahasa yang sistem ini guna, dan peta "kalau nak bina semula, mula dari mana".

🧱 HTML — rangka 🎨 CSS — solekan 🧠 TypeScript — otak 🗄️ SQL — stor 🤖 + Claude Code jadi cikgu

00 Mula

Selamat datang & cara guna panduan ini

Matlamat panduan ini bukan menghafal. Matlamatnya: selepas baca, anda boleh buka mana-mana fail dalam sistem ini dan faham apa yang berlaku — dan tahu cara bertanya bila tersangkut.

Sistem OMFS ialah aplikasi web sebenar yang digunakan di klinik. Ia bukan contoh mainan — ia ada pesakit, laporan, jadual on-call, semua. Itu kelebihan besar untuk belajar: setiap baris kod di sini ada sebab wujud. Kita belajar dengan membedah benda yang betul-betul berfungsi.

Cara terbaik membaca Baca ikut turutan (00 → 10) sekali sahaja untuk dapat gambaran besar. Jangan risau kalau tak faham 100% — itu normal. Lepas itu, barulah anda buka fail kod sebenar, dan rujuk balik bahagian yang berkaitan bila perlu.

Rahsia paling penting: anda ada seorang cikgu peribadi

Panduan kertas (seperti ini) bagus untuk memberi anda peta dan turutan belajar. Tetapi panduan kertas tidak boleh menjawab soalan susulan anda. Untuk itu, anda guna Claude Code — alat AI yang boleh baca kod ini dan terangkan apa-apa baris, pada tahap anda, dengan contoh.

Jadi sepanjang panduan ini, bila anda nampak kotak seperti di bawah, itu cadangan ayat untuk anda taip kepada Claude Code:

Tanya Claude Code Saya baru belajar coding. Terangkan fail worker/routes/hospital.ts baris demi baris, dalam bahasa mudah.

Fikirkan begini: panduan ini = silibus (apa nak belajar, ikut turutan); Claude Code = cikgu (jawab "kenapa?" dan "macam mana?"). Dua-dua bersama baru lengkap. Bahagian 09 tunjuk cara guna cikgu ini dengan betul.

Perkataan baru Claude Code — alat AI yang berjalan di komputer anda, boleh membaca seluruh kod projek dan menjawab soalan tentangnya. Silibus — senarai apa yang perlu dipelajari dan dalam susunan apa.

01 Konsep

Apa itu "kod" dan "app" sebenarnya

Kod ialah senarai arahan yang sangat teliti untuk komputer. Komputer tidak pandai meneka — ia buat tepat apa yang ditulis, tidak lebih tidak kurang.

Analogi: resipi Bayangkan resipi masakan untuk seorang tukang masak yang terlalu literal. Kalau anda tulis "masukkan telur", dia masukkan telur dengan kulit sekali — sebab anda tak kata "pecahkan dulu". Menulis kod ialah belajar memberi arahan yang cukup teliti sampai tiada ruang untuk salah faham.

App ini ada 3 bahagian besar

Hampir semua aplikasi web (termasuk yang ini) terbahagi kepada tiga bahagian. Analogi restoran paling mudah:

🍽️ Frontend

Bahagian yang anda nampak & sentuh — butang, borang, jadual. Macam kawasan makan + menu di restoran. Dibina dengan HTML, CSS, TypeScript.

👨‍🍳 Backend

Bahagian yang anda tak nampak — ia terima permintaan, semak kebenaran, kira, simpan. Macam dapur. Di sini ia ialah Cloudflare Worker (tulisan TypeScript).

🗄️ Database

Tempat simpan data kekal — rekod pesakit, lawatan, pengguna. Macam stor sejuk beku yang tak hilang bila restoran tutup. Di sini ia ialah D1, dikawal dengan bahasa SQL.

Aliran biasa Anda tekan butang "Simpan" (frontend) → ia hantar mesej ke dapur (backend) → dapur semak & tulis ke stor (database) → dapur balas "siap" → frontend tunjuk tanda hijau. Itu satu kitaran lengkap. Bila anda faham kitaran ini, anda faham 80% mana-mana app.

Perkataan baru Frontend = bahagian depan yang dilihat pengguna. Backend = bahagian belakang (server) yang memproses. Database = stor data. Server = komputer yang sentiasa hidup, menunggu permintaan dan menjawabnya. (Kami kekalkan istilah ini dalam English — ia digunakan di mana-mana.)

02 Kemahiran

Cara membaca kod (simbol & tanda)

Sebelum belajar bahasa, belajar dulu tanda baca kod. Sekali anda kenal simbol ni, kod nampak jauh kurang menakutkan.

Kamus simbol asas

// ...

Komen — nota untuk manusia. Komputer abaikan terus. Selalu tulis "kenapa", bukan "apa".

( )

Kurungan — biasanya membungkus input yang diberi kepada sesuatu tindakan.

{ }

Kurungan berkemban — membungkus satu blok: "semua arahan di dalam ni pergi bersama".

" " / ' '

Tanda petik — apa di dalamnya ialah teks biasa (perkataan), bukan arahan.

=

Bukan "sama dengan" matematik. Ia bermaksud "simpan nilai sebelah kanan ke dalam nama sebelah kiri".

;

Noktah hujung satu arahan — "ayat ni habis".

.

Titik — "milik" atau "ambil sesuatu daripada". pesakit.nama = "nama milik pesakit".

Cara membaca satu baris beranotasi

Sepanjang set panduan ini, kami terangkan kod guna anak panah ←. Di sebelah kiri ialah kod sebenar; di sebelah kanan anak panah ialah maksudnya dalam bahasa biasa. Contoh:

contoh ringkas

const umur = 7;            ← buat satu nama "umur", simpan nombor 7 di dalamnya
if (umur < 12) {        ← KALAU umur kurang daripada 12, buat blok di bawah…
  papar("Kanak-kanak"); ← …tunjukkan teks "Kanak-kanak"
}                       ← tutup blok "if"

Itu sahaja. Kalau anda boleh baca contoh di atas perlahan-lahan dan faham, anda dah ada kemahiran teras membaca kod. Selebihnya cuma perbendaharaan kata yang bertambah sikit demi sikit.

Jangan terkejut Kod sebenar ada baris yang nampak "bising" — banyak simbol, kurungan bersusun. Itu normal, dan anda tidak perlu faham setiap satu serta-merta. Bila satu baris buntu, salin baris itu dan tanya Claude Code (lihat bahagian 09).

03 Bahasa 1/4

HTML — rangka / tulang

HTML menentukan apa yang ada di halaman dan susunannya: tajuk, perenggan, butang, gambar. Ia rangka — belum bersolek, belum boleh bergerak.

Analogi HTML ialah tulang badan. Ia tentukan ada kepala, tangan, kaki — dan di mana. Belum ada kulit (itu CSS), belum boleh bergerak (itu JavaScript).

HTML ditulis dalam tag — perkataan dalam kurungan tajam < >. Kebanyakan tag berpasangan: satu buka, satu tutup (tutup ada garis miring /).

contoh.html

<h1>Senarai Pesakit</h1>      ← tajuk besar; teks di tengah ialah yang dipapar
<p>Klik nama untuk lihat rekod.</p> ← satu perenggan teks biasa
<button>Simpan</button>       ← satu butang bertulis "Simpan"

<h1> bermaksud "heading 1" (tajuk paling besar), <p> = "paragraph", <button> = butang. Komputer baca tag ini dan lukis elemen yang sepadan di skrin.

Di sistem ini Anda jarang nampak HTML mentah di sini, sebab sistem ini guna React (lihat bahagian 05) yang menulis HTML secara automatik dari dalam TypeScript. Tetapi konsepnya sama: tag = elemen di skrin. Fail seperti index.html di akar projek ialah rangka kosong yang React isi.

Perkataan baru HTML (HyperText Markup Language) — bahasa rangka halaman web. Tag — arahan HTML dalam < > yang menanda satu elemen (tajuk, butang, dll.). Element — satu benda di halaman (satu butang, satu perenggan).

04 Bahasa 2/4

CSS — solekan / gaya

CSS menentukan rupa: warna, saiz, jarak, susun atur. Rangka yang sama (HTML) boleh nampak buruk atau cantik — bezanya CSS.

Analogi Kalau HTML ialah tulang, CSS ialah kulit, rambut dan pakaian. Ia tidak ubah apa yang ada, cuma macam mana ia nampak.

CSS bekerja dengan: pilih sesuatu elemen, kemudian beri ia senarai "sifat: nilai".

contoh.css

button {                  ← pilih SEMUA butang…
  background: #0E6E63;     ← …warna latar hijau-teal
  color: white;          ← …warna teks putih
  border-radius: 8px;     ← …bucu bulat sedikit (8 piksel)
}                         ← tutup blok gaya

#0E6E63 ialah satu kod warna (campuran merah-hijau-biru). px bermaksud "piksel" — unit saiz di skrin. Anda boleh nampak warna teal yang sama ini di seluruh sistem OMFS — ia ditetapkan sekali di satu tempat, lalu digunakan semula.

Di sistem ini Sistem OMFS guna Tailwind CSS — satu cara menulis CSS terus di sebelah elemen guna nama pendek (cth class="bg-teal-600 text-white rounded-lg"). Hasilnya sama; cuma cara tulisnya lebih ringkas. Bila anda nampak banyak perkataan pendek dalam class="…", itu Tailwind.

Perkataan baru CSS (Cascading Style Sheets) — bahasa gaya/rupa. Property (sifat) — perkara yang anda ubah (warna, saiz…). Tailwind — alat CSS yang sistem ini guna; menulis gaya guna nama kelas pendek.

05 Bahasa 3/4

JavaScript & TypeScript — otak / aksi

Ini bahasa yang membuatkan halaman bertindak: bila butang ditekan, buat sesuatu; kira; hantar data; tukar paparan. Ini bahasa utama sistem OMFS.

Analogi HTML = tulang, CSS = kulit, JavaScript = otot dan otak. Ia yang buat benda bergerak dan bertindak balas bila anda berinteraksi.

JavaScript dulu, kemudian TypeScript

JavaScript (JS) ialah bahasa aksi asal. TypeScript (TS) ialah JavaScript tambah label keselamatan — anda boleh nyatakan "kotak ni mesti nombor", "kotak ni mesti teks". Kalau anda tersilap masukkan jenis yang salah, ia tegur sebelum program berjalan. Sistem OMFS guna TypeScript di mana-mana, untuk elak silap.

contoh.ts

function kiraUmur(tahunLahir: number) {  ← buat tindakan "kiraUmur"; ia terima 1 nombor
  const sekarang = 2026;              ← simpan tahun semasa
  return sekarang - tahunLahir;       ← pulangkan hasil tolak (umur)
}                                       ← tutup tindakan

kiraUmur(1990);  ← guna tindakan tadi dengan 1990 → hasilnya 36

function bermaksud "satu tindakan yang ada nama dan boleh diguna berulang". : number ialah label TypeScript: "input ini mesti nombor". return = "hasil yang dipulangkan balik kepada sesiapa yang panggil".

Di sistem ini: React Frontend sistem ini ditulis dengan React — satu cara menggunakan TypeScript untuk membina antara muka yang berubah secara automatik bila data berubah. Anda akan jumpa fail berakhir .tsx (TypeScript + HTML bercampur). Itu React. Kami akan bedah satu contoh penuh dalam Panduan Kod 02.

Perkataan baru JavaScript — bahasa aksi web. TypeScript — JavaScript + label jenis (lebih selamat); sistem ini guna ini. Function — satu tindakan bernama yang boleh diguna berulang. React — alat untuk bina antara muka (frontend). .ts / .tsx — akhiran fail TypeScript (yang .tsx ada elemen paparan).

06 Bahasa 4/4

SQL — bercakap dengan stor

SQL ialah bahasa untuk simpan, cari, ubah dan buang data dalam database. Bila app perlu "ambil semua pesakit hari ini", ia tanya database guna SQL.

Analogi Database ialah kabinet fail yang sangat teratur, dengan banyak laci (dipanggil table). SQL ialah cara anda bercakap dengan kerani kabinet itu: "bagi saya semua fail dalam laci 'pesakit' yang umur bawah 12".

Data disimpan dalam table — seperti helaian Excel: baris (rekod) dan lajur (medan). Sistem ini ada table seperti patients, visits, users.

contoh.sql

SELECT nama, umur      ← ambil lajur "nama" dan "umur"…
FROM patients         ← …dari table "patients"…
WHERE umur < 12;      ← …tapi hanya baris yang umur bawah 12

Baca macam ayat Inggeris: "SELECT (pilih) nama dan umur FROM (dari) patients WHERE (di mana) umur kurang 12". Itu kekuatan SQL — ia hampir seperti bahasa biasa.

Gotcha penting (akan diulang nanti) Arahan SQL boleh memadam data secara kekal. Dalam sistem ini ada peraturan ketat tentang memadam table visits — silap, semua rekod klinikal boleh terhapus. Kami akan terangkan ini sepenuhnya dalam Panduan Kod 03 (database). Buat masa ini, cuma sedar: SQL berkuasa, jadi berhati-hati.

Perkataan baru SQL (Structured Query Language) — bahasa bercakap dengan database. Table — satu "laci" data (seperti satu helaian Excel). Row (baris) = satu rekod; Column (lajur) = satu medan. D1 — jenis database yang sistem ini guna (di Cloudflare). Gotcha — jebakan/perangkap halus yang mudah terlepas pandang. (Istilah ini kami kekal English.)

07 Peta

Peta bina-dari-kosong (Fasa 0→8)

Kalau anda nak bina sistem seperti ini dari sifar, inilah turutannya. Setiap fasa membina di atas yang sebelumnya — sama seperti membina rumah: tapak dulu, baru dinding, baru bumbung.

Fasa 0

Sediakan tapak (setup)

Pasang alat (lihat bahagian 08), buka folder projek kosong, mulakan projek. Belum ada ciri — cuma rangka kerja boleh dijalankan.

package.json · vite.config.ts · index.html

Fasa 1

Halaman pertama (frontend kosong)

Bina satu halaman yang papar "Hello" guna React. Belajar HTML + CSS + TypeScript bekerja bersama. Belum ada data sebenar.

src/main.tsx · src/pages/…

Fasa 2

Stor data (database)

Reka table: pesakit, lawatan, pengguna. Tulis migration — fail SQL yang membina struktur table. Ini tulang belakang data.

migrations/0001_…sql

Fasa 3

Dapur (backend / API)

Bina "pintu-pintu" (dipanggil route) yang frontend boleh panggil: "bagi senarai pesakit", "simpan lawatan baru". Setiap route bercakap dengan database.

worker/index.ts · worker/routes/*.ts · worker/services/*.ts

Fasa 4

Kunci pintu (auth — log masuk)

Tambah log masuk & peranan (role): pendaftar, doktor, pentadbir. Pastikan hanya orang yang dibenarkan boleh buka pintu tertentu.

worker/middleware/auth.ts · worker/core-utils.ts

Fasa 5

Sambung depan ke belakang

Buat borang frontend benar-benar hantar data ke route backend, dan papar balik jawapannya. Sekarang ia satu app sebenar yang berfungsi.

src/lib/*-api.ts · src/contexts/*

Fasa 6

Ciri sebenar

Bina ciri yang klinik perlu: laporan PG201/PG211, jadual on-call, hantar e-mel. Setiap satu = gabungan frontend + route + database yang anda dah belajar.

src/lib/xlsx-utils.ts · worker/oncall/*

Fasa 7

Uji (test)

Tulis ujian automatik yang semak kod masih betul setiap kali diubah. Ini jaring keselamatan supaya pembaikan tidak rosakkan benda lain.

worker/__tests__/* · e2e/*

Fasa 8

Hantar ke dunia (deploy)

Naikkan app ke internet supaya orang sebenar boleh guna. Di sini, tolak kod ke main → ia auto-deploy ke Cloudflare.

.github/workflows/deploy.yml · wrangler.jsonc

Anda tidak perlu bina semula Tujuan peta ni bukan suruh anda bina semula semuanya. Ia memberi anda rangka mental: bila anda buka satu fail nanti, anda tahu ia "fasa yang mana" dan kenapa ia wujud. Itu yang buat kod masuk akal.

Perkataan baru Migration — fail arahan yang membina/ubah struktur database, satu langkah pada satu masa. Route — satu "pintu" alamat yang backend dengar (cth /api/patients). API — kumpulan route; cara frontend & backend bercakap. Auth — pengesahan log masuk & kebenaran. Role — jenis pengguna (doktor, pendaftar…). Deploy — naikkan kod supaya hidup di internet. Test — kod yang menyemak kod lain betul.

08 Alat

Alat (tools) yang anda perlukan

Untuk membaca dan mencuba kod, anda perlukan beberapa alat percuma. Anggap ini "kotak alat tukang".

Alat	Untuk apa (bahasa mudah)
Editor (VS Code)	Tempat anda buka, baca & tulis fail kod — seperti Microsoft Word, tetapi untuk kod. Percuma.
Terminal	Tetingkap hitam tempat anda taip arahan untuk komputer (cth "jalankan app"). Menakutkan pada mulanya, tapi anda cuma taip arahan yang diberi.
Node + npm	Node membolehkan TypeScript berjalan di komputer anda. npm memuat turun "alat orang lain" yang projek perlukan (cth React).
Git	"Mesin masa" untuk kod — simpan setiap versi, boleh undur bila silap. Setiap simpanan dipanggil commit.
Wrangler	Alat Cloudflare untuk deploy app & uruskan database D1.
Claude Code	Cikgu AI anda (lihat bahagian 09). Berjalan dalam terminal; boleh baca seluruh kod & jawab soalan.

Anda tak perlu pasang semua hari ini Untuk sekadar membaca & faham kod (matlamat panduan ini), anda hanya perlu satu editor untuk membuka fail, dan Claude Code untuk bertanya. Pemasangan Node/Wrangler hanya perlu bila anda mahu betul-betul menjalankan app sendiri.

Perkataan baru Editor — aplikasi untuk menulis kod (VS Code). Terminal — tetingkap arahan teks. Node — enjin yang menjalankan JavaScript/TypeScript di komputer. npm — pemuat turun pustaka (library). Git — sistem simpan-versi kod. Commit — satu simpanan bertanda dalam Git. Library — kod siap orang lain yang anda guna semula.

09 Cikgu

Guna Claude Code sebagai cikgu

Ini bahagian yang membuatkan "faham setiap baris" jadi mungkin. Daripada membaca beribu nota statik, anda bertanya secara hidup tentang fail yang anda sedang lihat — dan boleh tanya susulan.

Kenapa ini lebih baik daripada nota bertulis untuk setiap baris? Sebab dokumen statik tidak boleh menjawab soalan anda yang khusus. Claude Code boleh: ia baca kod terkini (jadi tak pernah lapuk), terangkan pada tahap anda, dan jawab "kenapa?" sebanyak yang anda mahu.

Ayat-ayat berguna untuk ditaip

Mula dengan memberitahu ia tahap anda, kemudian tanya. Contoh:

Faham satu fail Saya baru belajar coding. Terangkan fail worker/routes/hospital.ts baris demi baris, dalam bahasa mudah. Anggap saya tak tahu apa-apa.

Faham satu konsep Apa itu useState dalam React? Beri analogi mudah dan satu contoh kecil.

Soalan susulan (ini kuasanya!) Tadi awak kata "middleware". Saya masih tak faham. Boleh terangkan macam saya budak 12 tahun?

Gambaran besar Bila pengguna tekan butang "Simpan Pesakit", apa urutan fail yang terlibat dari mula sampai data masuk database? Senaraikan ikut turutan.

Belajar dengan selamat Saya nak cuba ubah satu benda kecil untuk belajar. Apa perubahan paling selamat yang takkan rosakkan apa-apa? Terangkan langkah demi langkah.

Tabiat belajar yang baik Bila satu baris atau perkataan buntu — jangan terus skip. Salin baris itu, tampal kepada Claude Code, dan tanya "apa maksud baris ni?". Setiap kali anda buat ini, perbendaharaan kata kod anda bertambah. Itulah cara "faham setiap baris" berlaku secara semula jadi.

Untuk belajar, bukan auto-pilot Claude Code boleh terus menulis kod untuk anda — tetapi kalau matlamat anda belajar, minta ia terangkan dahulu, dan cuba faham sebelum menerima. Faham > siap cepat.

10 Seterusnya

Ke mana selepas ini

Anda kini ada peta, kamus simbol, dan seorang cikgu. Inilah langkah seterusnya yang disyorkan.

1. Buka satu fail kecil & cuba baca

Cuba worker/routes/hospital.ts — ia pendek dan bersih. Baca perlahan, guna kamus simbol bahagian 02.

2. Minta Claude Code terangkannya

Guna ayat pertama dalam bahagian 09. Bandingkan penjelasannya dengan bacaan anda sendiri.

3. Baca Panduan Lengkap (bukan-coder)

Untuk gambaran besar sistem & setiap cirinya, dengan analogi & gambar rajah.

4. Panduan Kod 02 — contoh fail sebenar

Bedah 10 fail betul-betul, baris demi baris: kontrak, route, service, middleware, migration, & React. Buka Panduan Kod 02 →

Asas & Bahasa

📑 Kandungan

Selamat datang & cara guna panduan ini

Rahsia paling penting: anda ada seorang cikgu peribadi

Apa itu "kod" dan "app" sebenarnya

App ini ada 3 bahagian besar

🍽️ Frontend

👨‍🍳 Backend

🗄️ Database

Cara membaca kod (simbol & tanda)

Kamus simbol asas

Cara membaca satu baris beranotasi

HTML — rangka / tulang

CSS — solekan / gaya

JavaScript & TypeScript — otak / aksi

JavaScript dulu, kemudian TypeScript

SQL — bercakap dengan stor

Peta bina-dari-kosong (Fasa 0→8)

Sediakan tapak (setup)

Halaman pertama (frontend kosong)

Stor data (database)

Dapur (backend / API)

Kunci pintu (auth — log masuk)

Sambung depan ke belakang

Ciri sebenar

Uji (test)

Hantar ke dunia (deploy)

Alat (tools) yang anda perlukan

Guna Claude Code sebagai cikgu

Ayat-ayat berguna untuk ditaip

Ke mana selepas ini

1. Buka satu fail kecil & cuba baca

2. Minta Claude Code terangkannya

3. Baca Panduan Lengkap (bukan-coder)

4. Panduan Kod 02 — contoh fail sebenar

🔬 Panduan Kod 02 — Contoh Fail →

📘 Panduan Lengkap (bukan-coder) →

🛠️ Panduan Developer →