AGENTS.md

1# AGENTS.md
2 
3## Prehľad projektu
4 
5Toto je vzdelávací repozitár pre výučbu základov webového vývoja pre začiatočníkov. Kurz je komplexný 12-týždňový program vyvinutý Microsoft Cloud Advocates, obsahujúci 24 praktických lekcií pokrývajúcich JavaScript, CSS a HTML.
6 
7### Kľúčové komponenty
8 
9- **Vzdelávací obsah**: 24 štruktúrovaných lekcií usporiadaných do modulov založených na projektoch
10- **Praktické projekty**: Terrárium, Hra na písanie, Rozšírenie prehliadača, Vesmírna hra, Banková aplikácia, Code Editor a AI Chat Asistent
11- **Interaktívne kvízy**: 48 kvízov s 3 otázkami v každom (pred/po lekcii)
12- **Podpora viacerých jazykov**: Automatizované preklady do 50+ jazykov cez GitHub Actions
13- **Technológie**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (pre AI projekty)
14 
15### Architektúra
16 
17- Vzdelávací repozitár so štruktúrou založenou na lekciách
18- Každý priečinok lekcie obsahuje README, ukážky kódu a riešenia
19- Samostatné projekty v oddelených adresároch (quiz-app, rôzne projekty lekcií)
20- Prekladový systém využívajúci GitHub Actions (co-op-translator)
21- Dokumentácia podávaná cez Docsify a dostupná ako PDF
22 
23## Príkazy na nastavenie
24 
25Tento repozitár je primárne na konzumáciu vzdelávacieho obsahu. Pre prácu s konkrétnymi projektmi:
26 
27### Nastavenie hlavného repozitára
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Nastavenie Quiz App (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Spustiť vývojový server
40npm run build      # Vytvoriť pre produkciu
41npm run lint       # Spustiť ESLint
42```
43 
44### API Bankového projektu (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Spustiť API server
50npm run lint       # Spustiť ESLint
51npm run format     # Naformátovať pomocou Prettier
52```
53 
54### Projekty rozšírenia prehliadača
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Postupujte podľa pokynov na načítanie rozšírenia špecifických pre prehliadač
60```
61 
62### Projekty vesmírnej hry
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Otvorte index.html v prehliadači alebo použite Live Server
68```
69 
70### Projekt Chat (Python Backend)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Nastavte premennú prostredia GITHUB_TOKEN
76python api.py
77```
78 
79## Vývojový proces
80 
81### Pre prispievateľov obsahu
82 
831. **Forknite repozitár** do svojho GitHub účtu
842. **Skloňujte svoj fork** lokálne
853. **Vytvorte novú vetvu** pre svoje zmeny
864. Robte zmeny v obsahu lekcií alebo príkladoch kódu
875. Testujte akékoľvek zmeny kódu v relevantných projektových adresároch
886. Podajte pull request podľa pravidiel prispievania
89 
90### Pre študentov
91 
921. Forknite alebo naklonujte repozitár
932. Postupne prechádzajte adresáre lekcií
943. Čítajte README súbory pre každú lekciu
954. Vyplňte pre-lekčné kvízy na https://ff-quizzes.netlify.app/web/
965. Prejdite si príklady kódu v adresároch lekcií
976. Dokončite úlohy a výzvy
987. Absolvujte po-lekčné kvízy
99 
100### Živý vývoj
101 
102- **Dokumentácia**: Spustite `docsify serve` v koreňovom adresári (port 3000)
103- **Quiz App**: Spustite `npm run dev` v adresári quiz-app
104- **Projekty**: Použite VS Code Live Server rozšírenie pre HTML projekty
105- **API projekty**: Spustite `npm start` v príslušných API adresároch
106 
107## Inštrukcie na testovanie
108 
109### Testovanie Quiz App
110 
111```bash
112cd quiz-app
113npm run lint       # Skontrolujte problémy so štýlom kódu
114npm run build      # Overte, či zostavenie prebehne úspešne
115```
116 
117### Testovanie Bank API
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Skontrolujte problémy so štýlom kódu
122node server.js     # Overte, či server štartuje bez chýb
123```
124 
125### Všeobecný prístup k testovaniu
126 
127- Ide o vzdelávací repozitár bez komplexných automatizovaných testov
128- Manuálne testovanie sa zameriava na:
129  - Príklady kódu bez chýb
130  - Funkčnosť odkazov v dokumentácii
131  - Úspešnosť buildov projektov
132  - Dodržiavanie najlepších praktík v príkladoch
133 
134### Kontroly pred odoslaním
135 
136- Spustite `npm run lint` v adresároch s package.json
137- Overte platnosť markdown odkazov
138- Testujte príklady kódu v prehliadači alebo Node.js
139- Skontrolujte, či preklady zachovávajú správnu štruktúru
140 
141## Pravidlá štýlu kódu
142 
143### JavaScript
144 
145- Používajte moderný ES6+ syntax
146- Dodržiavajte štandardné ESLint konfigurácie v projektoch
147- Používajte zrozumiteľné názvy premenných a funkcií pre vzdelávaciu jasnosť
148- Pridávajte komentáre vysvetľujúce koncepty pre študentov
149- Formátujte kód pomocou Prettier kde je nastavený
150 
151### HTML/CSS
152 
153- Semantické HTML5 prvky
154- Principy responzívneho dizajnu
155- Čisté pomenovanie tried
156- Komentáre vysvetľujúce CSS techniky pre študentov
157 
158### Python
159 
160- Štýlové pravidlá PEP 8
161- Jasné, vzdelávacie príklady kódu
162- Typové anotácie tam, kde pomáhajú pri učení
163 
164### Markdown dokumentácia
165 
166- Jasná hierarchia nadpisov
167- Kódové bloky s určením jazyka
168- Odkazy na doplnkové zdroje
169- Snímky obrazovky a obrázky v adresároch `images/`
170- Alt text pre obrázky pre prístupnosť
171 
172### Organizácia súborov
173 
174- Lekcie číslované postupne (1-getting-started-lessons, 2-js-basics, atď.)
175- Každý projekt má adresáre `solution/` a často `start/` alebo `your-work/`
176- Obrázky uložené v špecifických priečinkoch lekcií `images/`
177- Preklady v štruktúre `translations/{language-code}/`
178 
179## Build a nasadenie
180 
181### Nasadenie Quiz App (Azure Static Web Apps)
182 
183quiz-app je nakonfigurovaný pre nasadenie na Azure Static Web Apps:
184 
185```bash
186cd quiz-app
187npm run build      # Vytvára priečinok dist/
188# Nasadzuje cez GitHub Actions workflow pri push do main
189```
190 
191Konfigurácia Azure Static Web Apps:
192- **Umiestnenie aplikácie**: `/quiz-app`
193- **Výstupné miesto**: `dist`
194- **Workflow**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Generovanie PDF dokumentácie
197 
198```bash
199npm install                    # Inštalujte docsify-to-pdf
200npm run convert               # Vygenerujte PDF z docs
201```
202 
203### Dokumentácia cez Docsify
204 
205```bash
206npm install -g docsify-cli    # Nainštalujte Docsify globálne
207docsify serve                 # Spustite na localhost:3000
208```
209 
210### Buildy špecifické pre projekt
211 
212Každý projektový adresár môže mať svoj vlastný build proces:
213- Vue projekty: `npm run build` vytvára produkčné balíky
214- Statické projekty: žiadny build krok, súbory sa servujú priamo
215 
216## Pravidlá pre pull requesty
217 
218### Formát názvov
219 
220Používajte jasné a popisné názvy, ktoré indikujú oblasť zmeny:
221- `[Quiz-app] Pridanie nového kvízu pre lekciu X`
222- `[Lesson-3] Oprava preklepu v projekte terrarium`
223- `[Translation] Pridanie španielskeho prekladu pre lekciu 5`
224- `[Docs] Aktualizácia inštrukcií na nastavenie`
225 
226### Povinné kontroly
227 
228Pred podaním PR:
229 
2301. **Kvalita kódu**:
231   - Spustite `npm run lint` v dotknutých projektových adresároch
232   - Opravte všetky linting chyby a varovania
233 
2342. **Overenie build procesu**:
235   - Spustite `npm run build` ak je to potrebné
236   - Zabezpečte, že neexistujú chyby pri buildovaní
237 
2383. **Validácia odkazov**:
239   - Otestujte všetky markdown odkazy
240   - Overte funkčnosť referencií obrázkov
241 
2424. **Kontrola obsahu**:
243   - Korektúra pravopisných a gramatických chýb
244   - Overte správnosť a vzdelávací charakter príkladov kódu
245   - Skontrolujte, či preklady zachovávajú pôvodný význam
246 
247### Požiadavky na príspevky
248 
249- Súhlas s Microsoft CLA (automatická kontrola pri prvom PR)
250- Dodržiavanie [Microsoft Open Source Kódexu správania](https://opensource.microsoft.com/codeofconduct/)
251- Viac informácií v [CONTRIBUTING.md](./CONTRIBUTING.md)
252- Pri PR uvádzať čísla issues, ak sú relevantné
253 
254### Proces recenzie
255 
256- PR sú kontrolované správcami a komunitou
257- Priorita na vzdelávaciu jasnosť
258- Príklady kódu musia dodržiavať aktuálne najlepšie praktiky
259- Preklady recenzované na presnosť a kultúrnu vhodnosť
260 
261## Prekladový systém
262 
263### Automatizovaný preklad
264 
265- Používa GitHub Actions s workflow co-op-translator
266- Automaticky prekladá do 50+ jazykov
267- Zdrojové súbory v hlavných adresároch
268- Preložené súbory v adresároch `translations/{language-code}/`
269 
270### Pridávanie manuálnych vylepšení prekladu
271 
2721. Nájdite súbor v `translations/{language-code}/`
2732. Vylepšujte obsah so zachovaním štruktúry
2743. Zaistite, aby príklady kódu boli funkčné
2754. Otestujte lokalizovaný kvízový obsah
276 
277### Metaúdaje prekladu
278 
279Preložené súbory obsahujú metaúdajový záhlavok:
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## Ladenie a riešenie problémov
293 
294### Bežné problémy
295 
296**Quiz app sa nespustí**:
297- Skontrolujte verziu Node.js (odporúčané v14+)
298- Vymažte `node_modules` a `package-lock.json`, znova spustite `npm install`
299- Skontrolujte konflikty portov (predvolené: Vite používa port 5173)
300 
301**API server sa nespustí**:
302- Overte, že verzia Node.js je minimálne node >=10
303- Skontrolujte, či port nie je už obsadený
304- Uistite sa, že všetky závislosti sú nainštalované cez `npm install`
305 
306**Rozšírenie prehliadača sa nenačíta**:
307- Skontrolujte správne naformátovanie manifest.json
308- Prehliadačový konzolový výstup pre chyby
309- Postupujte podľa inštrukcií inštalácie podľa prehliadača
310 
311**Problémy s Python chat projektom**:
312- Skontrolujte inštaláciu balíčka OpenAI: `pip install openai`
313- Overte nastavenie premennej prostredia GITHUB_TOKEN
314- Skontrolujte oprávnenia prístupu k GitHub modelom
315 
316**Docsify neservíruje dokumentáciu**:
317- Nainštalujte docsify-cli globálne: `npm install -g docsify-cli`
318- Spusťte príkaz v koreňovom adresári repozitára
319- Skontrolujte, že existuje `docs/_sidebar.md`
320 
321### Tipy pre vývojové prostredie
322 
323- Používajte VS Code s Live Server rozšírením pre HTML projekty
324- Nainštalujte ESLint a Prettier rozšírenia pre konzistentné formátovanie
325- Použite DevTools v prehliadači na ladenie JavaScriptu
326- Pre Vue projekty nainštalujte Vue DevTools rozšírenie prehliadača
327 
328### Výkonnostné aspekty
329 
330- Veľký počet prekladových súborov (50+ jazykov) robí kompletné klony veľkými
331- Pre prácu len s obsahom použite plytký klon: `git clone --depth 1`
332- Vylúčte preklady z vyhľadávania pri práci s anglickým obsahom
333- Build procesy môžu byť pomalé pri prvom spustení (npm install, Vite build)
334 
335## Bezpečnostné aspekty
336 
337### Premenné prostredia
338 
339- API kľúče nikdy neukladajte do repozitára
340- Používajte `.env` súbory (už zahrnuté v `.gitignore`)
341- Požadované premenné prostredia dokumentujte v README projektov
342 
343### Python projekty
344 
345- Používajte virtuálne prostredia: `python -m venv venv`
346- Udržiavajte závislosti aktuálne
347- GitHub tokeny majte s minimálnymi potrebnými právami
348 
349### Prístup k GitHub Modelom
350 
351- Vyžadujú sa osobné prístupové tokeny (PAT)
352- Tokeny ukladajte ako premenné prostredia
353- Nikdy neukladajte tokeny alebo prihlasovacie údaje do repozitára
354 
355## Doplnkové poznámky
356 
357### Cieľová skupina
358 
359- Úplní začiatočníci vo webovom vývoji
360- Študenti a samoštudenti
361- Učitelia používajúci kurz v triedach
362- Obsah je navrhnutý pre prístupnosť a postupné zlepšovanie zručností
363 
364### Vzdelávacia filozofia
365 
366- Projektovo orientované učenie
367- Časté kontrolné testy (kvízy)
368- Praktické cvičenia v písaní kódu
369- Príklady z reálneho sveta
370- Zameranie na základy pred frameworkami
371 
372### Údržba repozitára
373 
374- Aktívna komunita študentov a prispievateľov
375- Pravidelné aktualizácie závislostí a obsahu
376- Sledovanie issues a diskusií správcami
377- Automatizované aktualizácie prekladov cez GitHub Actions
378 
379### Súvisiace zdroje
380 
381- [Microsoft Learn moduly](https://docs.microsoft.com/learn/)
382- [Student Hub zdroje](https://docs.microsoft.com/learn/student-hub/)
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) odporúčaný pre študentov
384- Ďalšie kurzy: Generatívna AI, Data Science, ML, IoT dostupné
385 
386### Práca s konkrétnymi projektmi
387 
388Podrobné inštrukcie k jednotlivým projektom nájdete v README súboroch:
389- `quiz-app/README.md` - Vue 3 quiz aplikácia
390- `7-bank-project/README.md` - Banková aplikácia s autentifikáciou
391- `5-browser-extension/README.md` - Vývoj rozšírenia prehliadača
392- `6-space-game/README.md` - Vývoj hry na canvas
393- `9-chat-project/README.md` - Projekt AI chat asistenta
394 
395### Štruktúra monorepa
396 
397Aj keď nejde o tradičné monorepo, tento repozitár obsahuje viacero nezávislých projektov:
398- Každá lekcia je samostatná
399- Projekty nesdielajú závislosti
400- Pracujte na jednotlivých projektoch bez ovplyvnenia ostatných
401- Naklonujte celý repozitár pre kompletný kurzový zážitok
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Zrieknutie sa zodpovednosti**:  
407Tento dokument bol preložený pomocou služby AI prekladu [Co-op Translator](https://github.com/Azure/co-op-translator). Hoci sa snažíme o presnosť, majte, prosím, na pamäti, že automatizované preklady môžu obsahovať chyby alebo nepresnosti. Originálny dokument v jeho pôvodnom jazyku by mal byť považovaný za autoritatívny zdroj. Pre kritické informácie sa odporúča profesionálny ľudský preklad. Nie sme zodpovední za akékoľvek nepochopenia alebo nesprávne interpretácie vyplývajúce z použitia tohto prekladu.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->