AGENTS.md

1# AGENTS.md
2 
3## Gambaran Projek
4 
5Ini adalah repositori kurikulum pendidikan untuk mengajar asas pembangunan web kepada pemula. Kurikulum ini merupakan kursus menyeluruh selama 12 minggu yang dibangunkan oleh Microsoft Cloud Advocates, menampilkan 24 pelajaran praktikal yang merangkumi JavaScript, CSS, dan HTML.
6 
7### Komponen Utama
8 
9- **Kandungan Pendidikan**: 24 pelajaran tersusun yang dianjurkan dalam modul berasaskan projek
10- **Projek Praktikal**: Terrarium, Permainan Mengetik, Sambungan Pelayar, Permainan Angkasa, Aplikasi Perbankan, Penyunting Kod, dan Pembantu Chat AI
11- **Kuis Interaktif**: 48 kuiz dengan 3 soalan setiap satu (penilaian sebelum/selepas pelajaran)
12- **Sokongan Pelbagai Bahasa**: Terjemahan automatik untuk lebih 50 bahasa melalui GitHub Actions
13- **Teknologi**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (untuk projek AI)
14 
15### Seni Bina
16 
17- Repositori pendidikan dengan struktur berasaskan pelajaran
18- Setiap folder pelajaran mengandungi README, contoh kod, dan penyelesaian
19- Projek bebas di direktori berasingan (quiz-app, pelbagai projek pelajaran)
20- Sistem terjemahan menggunakan GitHub Actions (co-op-translator)
21- Dokumentasi disajikan melalui Docsify dan tersedia dalam format PDF
22 
23## Perintah Persediaan
24 
25Repositori ini terutamanya untuk penggunaan kandungan pendidikan. Untuk bekerja dengan projek tertentu:
26 
27### Persediaan Repositori Utama
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Persediaan Aplikasi Kuis (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Mula pelayan pembangunan
40npm run build      # Bina untuk pengeluaran
41npm run lint       # Jalankan ESLint
42```
43 
44### API Projek Bank (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Mula pelayan API
50npm run lint       # Jalankan ESLint
51npm run format     # Format dengan Prettier
52```
53 
54### Projek Sambungan Pelayar
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Ikuti arahan pemuatan pelanjutan khusus pelayar
60```
61 
62### Projek Permainan Angkasa
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Buka index.html dalam pelayar atau guna Live Server
68```
69 
70### Projek Chat (Backend Python)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Tetapkan pembolehubah persekitaran GITHUB_TOKEN
76python api.py
77```
78 
79## Aliran Kerja Pembangunan
80 
81### Untuk Penyumbang Kandungan
82 
831. **Fork repositori** ke akaun GitHub anda
842. **Clone fork anda** secara lokal
853. **Buat cawangan baru** untuk perubahan anda
864. Lakukan perubahan pada kandungan pelajaran atau contoh kod
875. Uji sebarang perubahan kod dalam direktori projek berkaitan
886. Hantar pull request mengikut garis panduan sumbangan
89 
90### Untuk Pelajar
91 
921. Fork atau clone repositori
932. Navigasi ke direktori pelajaran secara berurutan
943. Baca fail README untuk setiap pelajaran
954. Selesaikan kuiz pra-pelajaran di https://ff-quizzes.netlify.app/web/
965. Kerjakan contoh kod dalam folder pelajaran
976. Selesaikan tugasan dan cabaran
987. Ambil kuiz pasca-pelajaran
99 
100### Pembangunan Langsung
101 
102- **Dokumentasi**: Jalankan `docsify serve` di root (port 3000)
103- **Aplikasi Kuis**: Jalankan `npm run dev` di direktori quiz-app
104- **Projek**: Gunakan sambungan VS Code Live Server untuk projek HTML
105- **Projek API**: Jalankan `npm start` di direktori API berkaitan
106 
107## Arahan Ujian
108 
109### Ujian Aplikasi Kuis
110 
111```bash
112cd quiz-app
113npm run lint       # Periksa isu gaya kod
114npm run build      # Sahkan pembinaan berjaya
115```
116 
117### Ujian API Bank
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Periksa isu gaya kod
122node server.js     # Sahkan pelayan bermula tanpa ralat
123```
124 
125### Pendekatan Ujian Umum
126 
127- Ini adalah repositori pendidikan tanpa ujian automatik menyeluruh
128- Ujian manual fokus pada:
129  - Contoh kod berjalan tanpa ralat
130  - Pautan dalam dokumentasi berfungsi dengan betul
131  - Pembinaan projek selesai dengan jayanya
132  - Contoh mengikuti amalan terbaik
133 
134### Semakan Pra-penghantaran
135 
136- Jalankan `npm run lint` di direktori yang mengandungi package.json
137- Sahkan pautan markdown sah
138- Uji contoh kod dalam pelayar atau Node.js
139- Periksa terjemahan mengekalkan struktur betul
140 
141## Garis Panduan Gaya Kod
142 
143### JavaScript
144 
145- Gunakan sintaks ES6+ moden
146- Ikuti konfigurasi ESLint standard yang disediakan dalam projek
147- Gunakan nama pemboleh ubah dan fungsi yang bermakna untuk kejelasan pendidikan
148- Tambah komen yang menerangkan konsep untuk pelajar
149- Format menggunakan Prettier di mana dikonfigurasi
150 
151### HTML/CSS
152 
153- Elemen HTML5 semantik
154- Prinsip reka bentuk responsif
155- Konvensyen penamaan kelas yang jelas
156- Komen menerangkan teknik CSS untuk pelajar
157 
158### Python
159 
160- Garis panduan gaya PEP 8
161- Contoh kod yang jelas dan pendidikan
162- Petunjuk jenis di mana berguna untuk pembelajaran
163 
164### Dokumentasi Markdown
165 
166- Hirarki tajuk yang jelas
167- Blok kod dengan spesifikasi bahasa
168- Pautan ke sumber tambahan
169- Tangkapan skrin dan imej dalam direktori `images/`
170- Teks alt untuk imej bagi kebolehcapaian
171 
172### Pengurusan Fail
173 
174- Pelajaran dinomborkan secara berurutan (1-getting-started-lessons, 2-js-basics, dll.)
175- Setiap projek mempunyai direktori `solution/` dan sering `start/` atau `your-work/`
176- Imej disimpan dalam folder `images/` khusus pelajaran
177- Terjemahan dalam struktur `translations/{language-code}/`
178 
179## Pembinaan dan Penghantaran
180 
181### Penghantaran Aplikasi Kuis (Azure Static Web Apps)
182 
183quiz-app dikonfigurasi untuk penghantaran Azure Static Web Apps:
184 
185```bash
186cd quiz-app
187npm run build      # Membuat folder dist/
188# Melakukan deploy melalui workflow GitHub Actions apabila ada push ke main
189```
190 
191Konfigurasi Azure Static Web Apps:
192- **Lokasi aplikasi**: `/quiz-app`
193- **Lokasi output**: `dist`
194- **Aliran kerja**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Penjanaan PDF Dokumentasi
197 
198```bash
199npm install                    # Pasang docsify-to-pdf
200npm run convert               # Hasilkan PDF daripada docs
201```
202 
203### Dokumentasi Docsify
204 
205```bash
206npm install -g docsify-cli    # Pasang Docsify secara global
207docsify serve                 # Hidangkan pada localhost:3000
208```
209 
210### Pembinaan Khusus Projek
211 
212Setiap direktori projek mungkin mempunyai proses binaan sendiri:
213- Projek Vue: `npm run build` menghasilkan bundle pengeluaran
214- Projek statik: Tiada langkah binaan, hidangkan fail secara langsung
215 
216## Garis Panduan Pull Request
217 
218### Format Tajuk
219 
220Gunakan tajuk jelas dan deskriptif yang menunjukkan bidang perubahan:
221- `[Quiz-app] Tambah kuiz baru untuk pelajaran X`
222- `[Lesson-3] Betulkan ejaan dalam projek terrarium`
223- `[Translation] Tambah terjemahan Sepanyol untuk pelajaran 5`
224- `[Docs] Kemas kini arahan persediaan`
225 
226### Semakan Diperlukan
227 
228Sebelum menghantar PR:
229 
2301. **Kualiti Kod**:
231   - Jalankan `npm run lint` di direktori projek terjejas
232   - Betulkan semua ralat dan amaran linting
233 
2342. **Pengesahan Pembinaan**:
235   - Jalankan `npm run build` jika berkaitan
236   - Pastikan tiada ralat binaan
237 
2383. **Pengesahan Pautan**:
239   - Uji semua pautan markdown
240   - Sahkan rujukan imej berfungsi
241 
2424. **Semakan Kandungan**:
243   - Semak ejaan dan tatabahasa
244   - Pastikan contoh kod tepat dan pendidikan
245   - Sahkan terjemahan mengekalkan maksud asal
246 
247### Keperluan Penyumbangan
248 
249- Setuju dengan Microsoft CLA (semakan automatik pada PR pertama)
250- Ikuti [Kod Etika Sumber Terbuka Microsoft](https://opensource.microsoft.com/codeofconduct/)
251- Lihat [CONTRIBUTING.md](./CONTRIBUTING.md) untuk garis panduan terperinci
252- Rujuk nombor isu dalam penerangan PR jika berkenaan
253 
254### Proses Semakan
255 
256- PR disemak oleh penyelenggara dan komuniti
257- Kejelasan pendidikan diutamakan
258- Contoh kod harus mengikuti amalan terbaik terkini
259- Terjemahan disemak ketepatan dan kesesuaian budaya
260 
261## Sistem Terjemahan
262 
263### Terjemahan Automatik
264 
265- Menggunakan GitHub Actions dengan aliran kerja co-op-translator
266- Menterjemah ke 50+ bahasa secara automatik
267- Fail sumber dalam direktori utama
268- Fail terjemahan dalam direktori `translations/{language-code}/`
269 
270### Menambah Penambahbaikan Terjemahan Manual
271 
2721. Cari fail dalam `translations/{language-code}/`
2732. Lakukan penambahbaikan sambil mengekalkan struktur
2743. Pastikan contoh kod kekal berfungsi
2754. Uji sebarang kandungan kuiz yang dialih bahasa
276 
277### Metadata Terjemahan
278 
279Fail terjemahan termasuk tajuk metadata:
280```markdown
281<!--
282CO_OP_TRANSLATOR_METADATA:
283{
284  "original_hash": "...",
285  "translation_date": "...",
286  "source_file": "...",
287  "language_code": "..."
288}
289-->
290```
291 
292## Pengesanan dan Penyelesaian Masalah
293 
294### Isu Biasa
295 
296**Aplikasi kuiz gagal dimulakan**:
297- Periksa versi Node.js (disyorkan v14+)
298- Padamkan `node_modules` dan `package-lock.json`, jalankan `npm install` semula
299- Semak konflik port (lalai: Vite guna port 5173)
300 
301**Pelayan API tidak mula**:
302- Sahkan versi Node.js memenuhi minimum (node >=10)
303- Periksa jika port sudah digunakan
304- Pastikan semua kebergantungan dipasang dengan `npm install`
305 
306**Sambungan pelayar tidak dimuat**:
307- Periksa manifest.json diformat dengan betul
308- Semak konsol pelayar untuk ralat
309- Ikuti arahan pemasangan sambungan khusus pelayar
310 
311**Isu projek chat Python**:
312- Pastikan pakej OpenAI dipasang: `pip install openai`
313- Sahkan pembolehubah persekitaran GITHUB_TOKEN diset
314- Periksa kebenaran akses GitHub Models
315 
316**Docsify tidak menyajikan dokumen**:
317- Pasang docsify-cli secara global: `npm install -g docsify-cli`
318- Jalankan dari direktori root repositori
319- Semak bahawa `docs/_sidebar.md` wujud
320 
321### Tips Persekitaran Pembangunan
322 
323- Gunakan VS Code dengan sambungan Live Server untuk projek HTML
324- Pasang sambungan ESLint dan Prettier untuk format konsisten
325- Gunakan DevTools pelayar untuk debug JavaScript
326- Untuk projek Vue, pasang sambungan Vue DevTools pelayar
327 
328### Pertimbangan Prestasi
329 
330- Bilangan fail terjemahan yang banyak (50+ bahasa) menyebabkan klon penuh besar
331- Gunakan clone cetek jika hanya bekerja dengan kandungan: `git clone --depth 1`
332- Kecualikan terjemahan dari carian ketika bekerja pada kandungan Inggeris
333- Proses binaan mungkin perlahan pada kali pertama (npm install, binaan Vite)
334 
335## Pertimbangan Keselamatan
336 
337### Pembolehubah Persekitaran
338 
339- Kunci API tidak boleh dimuat naik ke repositori
340- Gunakan fail `.env` (sudah disenarai dalam `.gitignore`)
341- Dokumentasikan pembolehubah persekitaran yang diperlukan dalam README projek
342 
343### Projek Python
344 
345- Gunakan persekitaran maya: `python -m venv venv`
346- Kemas kini kebergantungan secara berkala
347- Token GitHub hendaklah mempunyai kebenaran minimum diperlukan
348 
349### Akses GitHub Models
350 
351- Token Akses Peribadi (PAT) diperlukan untuk GitHub Models
352- Token disimpan sebagai pembolehubah persekitaran
353- Jangan sesekali memuat naik token atau kelayakan
354 
355## Nota Tambahan
356 
357### Sasaran Pengguna
358 
359- Pemula lengkap dalam pembangunan web
360- Pelajar dan pembelajar kendiri
361- Guru yang menggunakan kurikulum dalam bilik darjah
362- Kandungan direka untuk kebolehcapaian dan pembinaan kemahiran secara berperingkat
363 
364### Falsafah Pendidikan
365 
366- Pendekatan pembelajaran berasaskan projek
367- Pemeriksaan pengetahuan kerap (kuiz)
368- Latihan amali pengkodan
369- Contoh aplikasi dunia sebenar
370- Fokus pada asas sebelum kerangka kerja
371 
372### Penyelenggaraan Repositori
373 
374- Komuniti pelajar dan penyumbang aktif
375- Kemas kini kandungan dan kebergantungan secara berkala
376- Isu dan perbincangan dipantau oleh penyelenggara
377- Kemas kini terjemahan automatik melalui GitHub Actions
378 
379### Sumber Berkaitan
380 
381- [Modul Microsoft Learn](https://docs.microsoft.com/learn/)
382- [Sumber Pelajar Student Hub](https://docs.microsoft.com/learn/student-hub/)
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) disyorkan untuk pelajar
384- Kursus tambahan: AI Generatif, Sains Data, ML, kurikulum IoT tersedia
385 
386### Bekerja dengan Projek Tertentu
387 
388Untuk arahan terperinci projek individu, rujuk fail README di:
389- `quiz-app/README.md` - aplikasi kuiz Vue 3
390- `7-bank-project/README.md` - aplikasi perbankan dengan pengesahan
391- `5-browser-extension/README.md` - pembangunan sambungan pelayar
392- `6-space-game/README.md` - pembangunan permainan berasaskan canvas
393- `9-chat-project/README.md` - projek pembantu chat AI
394 
395### Struktur Monorepo
396 
397Walaupun bukan monorepo tradisional, repositori ini mengandungi pelbagai projek bebas:
398- Setiap pelajaran berdiri sendiri
399- Projek tidak berkongsi kebergantungan
400- Kerja pada projek individu tanpa menjejaskan yang lain
401- Clone keseluruhan repositori untuk pengalaman kurikulum penuh
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Penafian**:  
407Dokumen ini telah diterjemahkan menggunakan perkhidmatan terjemahan AI [Co-op Translator](https://github.com/Azure/co-op-translator). Walaupun kami berusaha untuk ketepatan, sila maklum bahawa terjemahan automatik mungkin mengandungi kesilapan atau ketidaktepatan. Dokumen asal dalam bahasa asalnya harus dianggap sebagai sumber yang sahih. Untuk maklumat penting, terjemahan profesional oleh manusia adalah disyorkan. Kami tidak bertanggungjawab terhadap sebarang salah faham atau salah tafsir yang timbul daripada penggunaan terjemahan ini.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->