AGENTS.md

1# AGENTS.md
2 
3## Projekt Áttekintés
4 
5Ez egy oktatási tanterv-tárhely, amely kezdők számára tanítja a webfejlesztés alapjait. A tanterv egy átfogó, 12 hetes kurzus, amelyet a Microsoft Cloud Advocates fejlesztett ki, és 24 gyakorlati leckét tartalmaz, amelyek JavaScriptet, CSS-t és HTML-t fednek le.
6 
7### Főbb összetevők
8 
9- **Oktatási tartalom**: 24 strukturált lecke, amely projektalapú modulokba rendezett
10- **Gyakorlati projektek**: Terrárium, Gépelő játék, Böngésző kiterjesztés, Űr játék, Bank alkalmazás, Kód szerkesztő és AI chat asszisztens
11- **Interaktív kvízek**: 48 kvíz, mindegyik 3 kérdéssel (leckék előtti/utáni értékelések)
12- **Többnyelvű támogatás**: Automatikus fordítás 50+ nyelvre GitHub Actions segítségével
13- **Technológiák**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (AI projektekhez)
14 
15### Architektúra
16 
17- Oktatási tárhely leckealapú felépítéssel
18- Minden lecke mappa tartalmaz README-t, kód példákat és megoldásokat
19- Önálló projektek külön könyvtárakban (quiz-app, különféle lecke projektek)
20- Fordítási rendszer GitHub Actions használatával (co-op-translator)
21- Dokumentáció Docsify segítségével szolgálva, PDF formátumban is elérhető
22 
23## Beállítási parancsok
24 
25Ez a tárhely elsősorban oktatási tartalom fogyasztására szolgál. Specifikus projektekkel való munkához:
26 
27### Fő tárhely beállítása
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Kvíz alkalmazás beállítása (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Indítsa el a fejlesztői szervert
40npm run build      # Készítsen buildet produkcióhoz
41npm run lint       # Futtassa az ESLint-et
42```
43 
44### Bank projekt API (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Indítsa el az API szervert
50npm run lint       # Futtassa az ESLint-et
51npm run format     # Formázás Prettier-rel
52```
53 
54### Böngésző kiterjesztés projektek
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Kövesse a böngésző-specifikus bővítmény betöltési utasításait
60```
61 
62### Űr játék projektek
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Nyisd meg az index.html fájlt a böngészőben vagy használd a Live Servert
68```
69 
70### Chat projekt (Python háttér)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Állítsa be a GITHUB_TOKEN környezeti változót
76python api.py
77```
78 
79## Fejlesztési munkafolyamat
80 
81### Tartalom hozzájárulók számára
82 
831. **Forkoljuk a tárhelyet** a saját GitHub fiókunkba
842. **Klonoljuk a forkot** helyileg
853. **Hozzunk létre új ágat** a változtatásokhoz
864. Végezzen változtatásokat a lecke tartalmában vagy kód példákban
875. Teszteljük a kódváltozásokat a kapcsolódó projekt könyvtárakban
886. Küldjünk be pull requesteket a hozzájárulási irányelvek szerint
89 
90### Tanulók számára
91 
921. Forkoljuk vagy klonoljuk a tárhelyet
932. Lépjünk végig sorban a lecke könyvtárakon
943. Olvassuk el az egyes leckék README fájljait
954. Töltsük ki a lecke előtti kvízeket a https://ff-quizzes.netlify.app/web/ oldalon
965. Dolgozzunk a lecke mappákban lévő kód példákon
976. Teljesítsük a feladatokat és kihívásokat
987. Írjuk meg a lecke utáni kvízeket
99 
100### Élő fejlesztés
101 
102- **Dokumentáció**: Fussuk a `docsify serve` parancsot a gyökérben (3000-es port)
103- **Kvíz alkalmazás**: Fussuk az `npm run dev` parancsot a quiz-app könyvtárban
104- **Projektek**: Használjuk a VS Code Live Server bővítményét HTML projektekhez
105- **API projektek**: Fussuk az `npm start` parancsot az adott API könyvtárakban
106 
107## Tesztelési útmutató
108 
109### Kvíz alkalmazás tesztelése
110 
111```bash
112cd quiz-app
113npm run lint       # Ellenőrizze a kódstílus problémákat
114npm run build      # Ellenőrizze, hogy a build sikeres legyen
115```
116 
117### Bank API tesztelése
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Ellenőrizze a kód stílusproblémáit
122node server.js     # Ellenőrizze, hogy a szerver hibák nélkül elindul-e
123```
124 
125### Általános tesztelési megközelítés
126 
127- Ez egy oktatási tárhely átfogó automatizált tesztek nélkül
128- Manuális tesztelés a következőkre fókuszál:
129  - Kód példák hibamentes futtatása
130  - Dokumentációban lévő linkek helyes működése
131  - Projektek sikeres buildelése
132  - Példák legjobb gyakorlati elvek szerinti követése
133 
134### Benyújtás előtti ellenőrzések
135 
136- Futtassuk az `npm run lint` parancsot azokban a könyvtárakban, ahol van package.json
137- Ellenőrizzük a markdown linkek érvényességét
138- Teszteljük a kód példákat böngészőben vagy Node.js-ben
139- Ellenőrizzük, hogy a fordítások megőrzik a helyes struktúrát
140 
141## Kódstílus irányelvek
142 
143### JavaScript
144 
145- Használj modern ES6+ szintaxist
146- Kövesd a projektekben megadott ESLint konfigurációkat
147- Használj érthető változó- és függvénynév- megnevezéseket a tanulási cél érdekében
148- Adj hozzászólásokat a fogalmak magyarázatához
149- Használj Prettier-t a formázáshoz ahol konfigurálva van
150 
151### HTML/CSS
152 
153- Szemantikus HTML5 elemek
154- Reszponzív tervezési elvek
155- Egyértelmű osztálynevek használata
156- Kommentárok magyarázzák a CSS technikákat a tanulók számára
157 
158### Python
159 
160- PEP 8 stílusirányelvek
161- Tiszta, oktatási célú kód példák
162- Típus annotációk, ahol hasznos a tanuláshoz
163 
164### Markdown dokumentáció
165 
166- Tiszta címsor hierarchia
167- Kódblokkok nyelvi megjelöléssel
168- Hivatkozások további erőforrásokra
169- Képernyőképek és képek az `images/` könyvtárakban
170- Alt szövegek a képekhez az akadálymentesség érdekében
171 
172### Fájl szervezés
173 
174- A leckék számozva, sorban (1-getting-started-lessons, 2-js-basics, stb.)
175- Minden projekt tartalmaz `solution/` és gyakran `start/` vagy `your-work/` mappákat
176- Képek a lecke specifikus `images/` mappákban tárolva
177- Fordítások `translations/{language-code}/` struktúrában találhatók
178 
179## Build és Telepítés
180 
181### Kvíz alkalmazás telepítése (Azure Static Web Apps)
182 
183A quiz-app konfigurálva van Azure Static Web Apps telepítésére:
184 
185```bash
186cd quiz-app
187npm run build      # Létrehozza a dist/ mappát
188# Közzéteszi a GitHub Actions munkafolyamattal push esetén a main ágra
189```
190 
191Azure Static Web Apps beállítás:
192- **App hely**: `/quiz-app`
193- **Kimeneti mappa**: `dist`
194- **Munkafolyamat**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Dokumentáció PDF generálás
197 
198```bash
199npm install                    # docsify-to-pdf telepítése
200npm run convert               # PDF generálása a dokumentációból
201```
202 
203### Docsify Dokumentáció
204 
205```bash
206npm install -g docsify-cli    # Telepítsd a Docsify-t globálisan
207docsify serve                 # Szolgáltasd a localhost:3000 címen
208```
209 
210### Projekt-specifikus buildelések
211 
212Minden projekt könyvtár saját build folyamatot tartalmazhat:
213- Vue projektek: `npm run build` létrehozza a gyártási csomagokat
214- Statikus projektek: nincs build lépés, fájlok közvetlen kiszolgálása
215 
216## Pull Request irányelvek
217 
218### Cím formátuma
219 
220Használjunk világos, leíró címeket, amelyek jelzik a változtatás területét:
221- `[Quiz-app] Új lecke kvíz hozzáadása X`
222- `[Lesson-3] Elírás javítása a terrárium projektben`
223- `[Translation] Spanyol fordítás hozzáadása az 5. leckéhez`
224- `[Docs] Frissített beállítási utasítások`
225 
226### Kötelező ellenőrzések
227 
228PR benyújtása előtt:
229 
2301. **Kódminőség**:
231   - Futtassuk az `npm run lint` parancsot az érintett projekt könyvtárakban
232   - Javítsuk az összes lint hibát és figyelmeztetést
233 
2342. **Build ellenőrzés**:
235   - Futtassuk az `npm run build` parancsot, ha alkalmazható
236   - Biztosítsuk, hogy ne legyen build hiba
237 
2383. **Linkek érvényessége**:
239   - Teszteljük az összes markdown linket
240   - Ellenőrizzük a kép hivatkozások működését
241 
2424. **Tartalom felülvizsgálat**:
243   - Ellenőrizzük helyesírást és nyelvtant
244   - Győződjünk meg a kód példák helyességéről és oktató jellegéről
245   - Validáljuk, hogy a fordítások megőrzik az eredeti jelentést
246 
247### Hozzájárulási feltételek
248 
249- Elfogadás a Microsoft CLA-t (automatikus ellenőrzés az első PR-nél)
250- Kövessük a [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) irányelveit
251- Részletes útmutató a [CONTRIBUTING.md](./CONTRIBUTING.md) fájlban
252- Hivatkozzunk issue számokra a PR leírásában, ha vonatkozik
253 
254### Áttekintési folyamat
255 
256- PR-eket a karbantartók és a közösség átnézi
257- Oktatási érthetőség elsődleges szempont
258- Kód példák kövessék a legjobb aktuális gyakorlatokat
259- Fordítások pontosságát és kulturális megfelelősségét ellenőrzik
260 
261## Fordítási rendszer
262 
263### Automatikus fordítás
264 
265- GitHub Actions használ co-op-translator munkafolyamatot
266- Több mint 50 nyelvre fordít automatikusan
267- Forrásfájlok a fő könyvtárakban vannak
268- Fordított fájlok a `translations/{language-code}/` könyvtárakban
269 
270### Kézi fordítási fejlesztések hozzáadása
271 
2721. Keressük meg a fájlt a `translations/{language-code}/` mappában
2732. Végezzük el a fejlesztéseket, megőrizve a struktúrát
2743. Biztosítsuk, hogy a kód példák működőképesek maradjanak
2754. Teszteljük a lokalizált kvíz tartalmat
276 
277### Fordítási metaadatok
278 
279A fordított fájlok tartalmaznak metaadat fejlécet:
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## Hibakeresés és problémamegoldás
293 
294### Gyakori problémák
295 
296**Kvíz alkalmazás nem indul el**:
297- Ellenőrizzük a Node.js verziót (v14+ ajánlott)
298- Töröljük a `node_modules` és `package-lock.json` fájlokat, majd futtassuk újra az `npm install`-t
299- Ellenőrizzük, hogy nincs-e port konfliktus (alapértelmezett: Vite a 5173-as portot használja)
300 
301**API szerver nem indul**:
302- Győződjünk meg, hogy a Node.js verzió megfelel (node >=10)
303- Ellenőrizzük, nincs-e használatban a port
304- Biztosítsuk, hogy minden függőség telepítve van az `npm install` lefuttatásával
305 
306**Böngésző kiterjesztés nem töltődik be**:
307- Ellenőrizzük a manifest.json helyes formátumát
308- Nézzük meg a böngésző konzolt hibákért
309- Kövessük a böngésző-specifikus kiterjesztés telepítési utasításait
310 
311**Python chat projekt problémák**:
312- Győződjünk meg, hogy az OpenAI csomag telepítve van: `pip install openai`
313- Ellenőrizzük a GITHUB_TOKEN környezeti változó beállítását
314- Nézzük meg a GitHub Modellek elérési engedélyeit
315 
316**Docsify nem szolgál ki dokumentációt**:
317- Telepítsük globálisan a docsify-cli-t: `npm install -g docsify-cli`
318- Futassuk a repository gyökérkönyvtárából
319- Ellenőrizzük, hogy létezik-e a `docs/_sidebar.md`
320 
321### Fejlesztői környezet tippek
322 
323- Használjuk a VS Code-ot Live Server bővítménnyel HTML projektekhez
324- Telepítsük az ESLint és Prettier bővítményeket az egységes formázáshoz
325- Használjuk a böngésző fejlesztői eszközeit JavaScript hibakereséshez
326- Vue projektekhez telepítsük a Vue DevTools böngésző bővítményt
327 
328### Teljesítmény szempontok
329 
330- Nagyszámú fordított fájl (50+ nyelv) miatt a teljes klón nagy méretű
331- Használjuk a sekély klónozást, ha csak tartalmon dolgozunk: `git clone --depth 1`
332- Kizárhatjuk a fordításokat a keresésekből, ha csak angol tartalmat dolgozunk
333- Build folyamatok lassúak lehetnek első futtatáskor (npm install, Vite build)
334 
335## Biztonsági megfontolások
336 
337### Környezeti változók
338 
339- API kulcsokat soha ne tegyünk be a tárhelybe
340- Használjunk `.env` fájlokat (már benne vannak `.gitignore`-ban)
341- Dokumentáljuk a szükséges környezeti változókat a projekt README-kben
342 
343### Python projektek
344 
345- Virtuális környezet használata: `python -m venv venv`
346- Függőségek naprakészen tartása
347- GitHub tokenek minimális szükséges jogosultsággal
348 
349### GitHub Modellek elérés
350 
351- Személyes hozzáférési tokeneket (PAT) igényel a GitHub Modellek használata
352- A tokeneket környezeti változóként kell tárolni
353- Soha ne kerüljön be token vagy hitelesítő adat a forrásba
354 
355## További megjegyzések
356 
357### Célközönség
358 
359- Teljesen kezdők a webfejlesztésben
360- Diákok és önálló tanulók
361- Tanárok, akik az oktatási anyagot osztályokban használják
362- A tartalom akadálymentesített és fokozatos képességfejlesztésre tervezett
363 
364### Oktatási filozófia
365 
366- Projektalapú tanulási módszer
367- Gyakori tudásellenőrzések (kvízek)
368- Gyakorlati kódolási feladatok
369- Valós példák alkalmazása
370- Az alapokra fókuszál a keretrendszerek előtt
371 
372### Tárhely karbantartás
373 
374- Aktív tanuló és hozzájáruló közösség
375- Függőségek és tartalom rendszeres frissítése
376- Issue-k és megbeszélések folyamatos követése a karbantartók által
377- Fordítás frissítések automatizáltan GitHub Actions segítségével
378 
379### Kapcsolódó források
380 
381- [Microsoft Learn modulok](https://docs.microsoft.com/learn/)
382- [Student Hub források](https://docs.microsoft.com/learn/student-hub/)
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) ajánlott tanulóknak
384- Egyéb kurzusok: Generatív AI, Adattudomány, ML, IoT tananyagok elérhetők
385 
386### Specifikus projektek kezelése
387 
388Részletes utasítások az egyes projektekhez a README fájlokban:
389- `quiz-app/README.md` - Vue 3 kvíz alkalmazás
390- `7-bank-project/README.md` - Bank alkalmazás hitelesítéssel
391- `5-browser-extension/README.md` - Böngésző kiterjesztés fejlesztés
392- `6-space-game/README.md` - Vászon alapú játék fejlesztés
393- `9-chat-project/README.md` - AI chat asszisztens projekt
394 
395### Monorepo struktúra
396 
397Habár nem hagyományos monorepo, ez a tárhely több önálló projektet tartalmaz:
398- Minden lecke önálló
399- Projektek nem osztanak meg függőségeket
400- Egyedi projektek fejlesztése anélkül, hogy másokat befolyásolnánk
401- Teljes tanterv élményéhez a teljes tárhely klónozása ajánlott
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Nyilatkozat**:
407Ez a dokumentum az AI fordítási szolgáltatás, a [Co-op Translator](https://github.com/Azure/co-op-translator) segítségével készült. Bár törekszünk a pontosságra, kérjük, vegye figyelembe, hogy az automatikus fordítások hibákat vagy pontatlanságokat tartalmazhatnak. Az eredeti dokumentum az anyanyelvén tekintendő hiteles forrásnak. Kritikus információk esetén javasolt a professzionális emberi fordítás. Nem vállalunk felelősséget ezen fordítás használatából eredő félreértésekért vagy félreértelmezésekért.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->