AGENTS.md

1# AGENTS.md
2 
3## Přehled projektu
4 
5Toto je vzdělávací repozitář kurikula pro výuku základů webového vývoje pro začátečníky. Kurikulum je komplexní 12týdenní kurz vyvinutý týmem Microsoft Cloud Advocates, obsahující 24 praktických lekcí pokrývajících JavaScript, CSS a HTML.
6 
7### Klíčové komponenty
8 
9- **Vzdělávací obsah**: 24 strukturovaných lekcí uspořádaných do modulů založených na projektech
10- **Praktické projekty**: Terrárium, Hra na psaní, Prodlžek prohlížeče, Hra ve vesmíru, Bankovní aplikace, Kódový editor a AI chatovací asistent
11- **Interaktivní kvízy**: 48 kvízů po 3 otázkách (testy před a po lekci)
12- **Podpora více jazyků**: Automatizované překlady do více než 50 jazyků pomocí GitHub Actions
13- **Technologie**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (pro AI projekty)
14 
15### Architektura
16 
17- Vzdělávací repozitář se strukturou založenou na lekcích
18- Každá složka lekce obsahuje README, příklady kódu a řešení
19- Samostatné projekty v oddělených adresářích (quiz-app, různé projektové lekce)
20- Překladový systém využívající GitHub Actions (co-op-translator)
21- Dokumentace podávaná přes Docsify a dostupná jako PDF
22 
23## Příkazy k nastavení
24 
25Tento repozitář je primárně určen pro konzumaci vzdělávacího obsahu. Pro práci s konkrétními projekty:
26 
27### Nastavení hlavního repozitáře
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Nastavení Quiz App (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Spustit vývojový server
40npm run build      # Sestavit pro produkci
41npm run lint       # Spustit ESLint
42```
43 
44### Bankovní API projekt (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Spusťte API server
50npm run lint       # Spusťte ESLint
51npm run format     # Naformátujte pomocí Prettier
52```
53 
54### Projekty pro prodloužení prohlížeče
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Postupujte podle pokynů pro načítání rozšíření specifických pro prohlížeč
60```
61 
62### Projekty hry ve vesmíru
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Otevřete index.html v prohlížeči nebo použijte Live Server
68```
69 
70### Chatovací projekt (Python Backend)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Nastavte proměnnou prostředí GITHUB_TOKEN
76python api.py
77```
78 
79## Vývojový pracovní postup
80 
81### Pro přispěvatele obsahu
82 
831. **Vytvořte fork** repozitáře do svého GitHub účtu
842. **Klonujte svůj fork** lokálně
853. **Vytvořte novou větev** pro své změny
864. Proveďte změny ve vzdělávacím obsahu nebo příkladech kódu
875. Otestujte jakékoliv změny kódu v příslušných adresářích projektů
886. Odešlete pull requesty dle pokynů pro přispívání
89 
90### Pro studenty
91 
921. Vytvořte fork nebo klonujte repozitář
932. Procházejte adresáře lekcí postupně
943. Čtěte README soubory ke každé lekci
954. Dokončete kvízy před lekcí na https://ff-quizzes.netlify.app/web/
965. Procházejte příklady kódu v adresářích lekcí
976. Splňte úkoly a výzvy
987. Dokončete kvízy po lekci
99 
100### Živý vývoj
101 
102- **Dokumentace**: Spusťte `docsify serve` v kořenovém adresáři (port 3000)
103- **Quiz App**: Spusťte `npm run dev` v adresáři quiz-app
104- **Projekty**: Použijte rozšíření VS Code Live Server pro HTML projekty
105- **API projekty**: Spusťte `npm start` v příslušných API adresářích
106 
107## Pokyny k testování
108 
109### Testování Quiz App
110 
111```bash
112cd quiz-app
113npm run lint       # Zkontrolujte problémy se stylem kódu
114npm run build      # Ověřte, zda sestavení proběhne úspěšně
115```
116 
117### Testování Bank API
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Zkontrolujte problémy se stylem kódu
122node server.js     # Ověřte, že server startuje bez chyb
123```
124 
125### Obecný přístup k testování
126 
127- Jedná se o vzdělávací repozitář bez komplexních automatizovaných testů
128- Manuální testování se zaměřuje na:
129  - Příklady kódu bez chyb při spuštění
130  - Funkčnost odkazů v dokumentaci
131  - Úspěšné dokončení buildů projektů
132  - Dodržování osvědčených postupů v příkladech
133 
134### Kontroly před odesláním PR
135 
136- Spusťte `npm run lint` v adresářích s package.json
137- Ověřte platnost markdown odkazů
138- Testujte příklady kódu v prohlížeči nebo Node.js
139- Zkontrolujte správnou strukturu překladů
140 
141## Směrnice pro styl kódu
142 
143### JavaScript
144 
145- Používejte moderní syntax ES6+
146- Dodržujte standardní konfigurace ESLint v projektech
147- Používejte srozumitelné názvy proměnných a funkcí pro vzdělávací přehlednost
148- Přidávejte komentáře vysvětlující koncepty studentům
149- Formátujte pomocí Prettier tam, kde je nastaven
150 
151### HTML/CSS
152 
153- Sémantické HTML5 prvky
154- Principy responzivního designu
155- Jasné konvence pojmenování tříd
156- Komentáře vysvětlující CSS techniky pro studenty
157 
158### Python
159 
160- Dodržujte PEP 8 styl
161- Jasné, vzdělávací příklady kódu
162- Používejte typové nápovědy, kde to pomáhá učení
163 
164### Dokumentace v Markdown
165 
166- Přehledná hierarchie nadpisů
167- Kódové bloky s uvedením jazyka
168- Odkazy na další zdroje
169- Snímky obrazovky a obrázky v adresářích `images/`
170- Alternativní text obrázků pro přístupnost
171 
172### Organizace souborů
173 
174- Lekce číslované sekvenčně (1-getting-started-lessons, 2-js-basics, atd.)
175- Každý projekt má adresáře `solution/` a často `start/` nebo `your-work/`
176- Obrázky uložené ve složkách `images/` specifických pro lekce
177- Překlady v adresářové struktuře `translations/{language-code}/`
178 
179## Sestavení a nasazení
180 
181### Nasazení Quiz App (Azure Static Web Apps)
182 
183Quiz-app je nakonfigurován pro nasazení pomocí Azure Static Web Apps:
184 
185```bash
186cd quiz-app
187npm run build      # Vytváří složku dist/
188# Nasazuje pomocí workflow GitHub Actions při push na main
189```
190 
191Konfigurace Azure Static Web Apps:
192- **Umístění aplikace**: `/quiz-app`
193- **Výstupní umístění**: `dist`
194- **Workflow**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Generování PDF dokumentace
197 
198```bash
199npm install                    # Nainstalujte docsify-to-pdf
200npm run convert               # Vytvořte PDF z docs
201```
202 
203### Dokumentace přes Docsify
204 
205```bash
206npm install -g docsify-cli    # Nainstalujte Docsify globálně
207docsify serve                 # Spusťte na localhost:3000
208```
209 
210### Sestavení specifická pro projekt
211 
212Každý projekt může mít vlastní build proces:
213- Vue projekty: `npm run build` vytváří produkční balíčky
214- Statické projekty: Žádný build, soubory se podávají přímo
215 
216## Směrnice pro pull requesty
217 
218### Formát názvu
219 
220Používejte jasné, popisné názvy uvádějící oblast změny:
221- `[Quiz-app] Přidat nový kvíz pro lekci X`
222- `[Lesson-3] Opravit překlep v projektu terrárium`
223- `[Translation] Přidat španělský překlad pro lekci 5`
224- `[Docs] Aktualizovat instrukce k nastavení`
225 
226### Požadované kontroly
227 
228Před odesláním PR:
229 
2301. **Kvalita kódu**:
231   - Spusťte `npm run lint` v dotčených projektech
232   - Opravte všechny lintovací chyby a varování
233 
2342. **Ověření buildů**:
235   - Spusťte `npm run build` pokud je relevantní
236   - Ujistěte se, že build proběhl bez chyb
237 
2383. **Kontrola odkazů**:
239   - Otestujte všechny markdown odkazy
240   - Ověřte pracovní odkazy na obrázky
241 
2424. **Kontrola obsahu**:
243   - Korektura pravopisu a gramatiky
244   - Zajištění správnosti a vzdělávací hodnoty příkladů kódu
245   - Ověření správnosti překladů
246 
247### Požadavky na přispívání
248 
249- Souhlas s Microsoft CLA (automatická kontrola při prvním PR)
250- Dodržování [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
251- Viz [CONTRIBUTING.md](./CONTRIBUTING.md) pro podrobné pokyny
252- Uvádějte čísla issue v popisu PR, pokud jsou relevantní
253 
254### Proces revize
255 
256- PR kontrolují správci a komunita
257- Upřednostňuje se vzdělávací jasnost
258- Příklady kódu by měly odpovídat současným osvědčeným postupům
259- Překlady se kontrolují na přesnost a kulturní vhodnost
260 
261## Překladový systém
262 
263### Automatický překlad
264 
265- Používá GitHub Actions s workflow co-op-translator
266- Automaticky překládá do více než 50 jazyků
267- Zdrojové soubory v hlavních adresářích
268- Přeložené soubory v adresářích `translations/{language-code}/`
269 
270### Přidání ručních vylepšení překladu
271 
2721. Najděte soubor v `translations/{language-code}/`
2732. Proveďte vylepšení při zachování struktury
2743. Zajistěte funkčnost příkladů kódu
2754. Otestujte případný lokalizovaný kvízový obsah
276 
277### Metadata překladu
278 
279Přeložené soubory obsahují hlavičku s metadaty:
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## Ladění a řešení problémů
293 
294### Běžné problémy
295 
296**Quiz app se nespustí**:
297- Zkontrolujte verzi Node.js (doporučeno v14+)
298- Odstraňte `node_modules` a `package-lock.json`, spusťte `npm install` znovu
299- Zkontrolujte konflikty portů (výchozí: Vite používá port 5173)
300 
301**API server se nespustí**:
302- Ověřte minimální verzi Node.js (node >=10)
303- Zkontrolujte, zda port není obsazen
304- Ujistěte se, že všechny závislosti jsou nainstalovány pomocí `npm install`
305 
306**Prodlžek prohlížeče se nenačítá**:
307- Zkontrolujte, že manifest.json je správně formátován
308- Prohlédněte konzoli prohlížeče kvůli chybám
309- Postupujte podle specifických instrukcí pro instalaci prodlužků v prohlížeči
310 
311**Problémy s Python chat projektem**:
312- Ujistěte se, že je nainstalován balík OpenAI: `pip install openai`
313- Zkontrolujte, že je nastavena proměnná prostředí GITHUB_TOKEN
314- Prověřte oprávnění přístupu k GitHub Models
315 
316**Docsify nedoručuje dokumenty**:
317- Globálně nainstalujte docsify-cli: `npm install -g docsify-cli`
318- Spusťte ze základního adresáře repozitáře
319- Ověřte, že existuje `docs/_sidebar.md`
320 
321### Tipy pro vývojové prostředí
322 
323- Používejte VS Code s rozšířením Live Server pro HTML projekty
324- Nainstalujte rozšíření ESLint a Prettier pro konzistentní formátování
325- Používejte DevTools prohlížeče pro ladění JavaScriptu
326- Pro Vue projekty použijte Vue DevTools rozšíření do prohlížeče
327 
328### Výkonnostní úvahy
329 
330- Velké množství přeložených souborů (50+ jazyků) znamená, že plné klony jsou rozsáhlé
331- Použijte shallow clone, pokud pracujete jen s obsahem: `git clone --depth 1`
332- Při práci s angličtinou vylučte překlady z hledání
333- Build procesy mohou být pomalé při prvním spuštění (npm install, Vite build)
334 
335## Bezpečnostní aspekty
336 
337### Proměnné prostředí
338 
339- API klíče nikdy nesmí být commitovány do repozitáře
340- Používejte `.env` soubory (jsou v `.gitignore`)
341- Dokumentujte požadované proměnné prostředí v README projektů
342 
343### Python projekty
344 
345- Používejte virtuální prostředí: `python -m venv venv`
346- Udržujte závislosti aktuální
347- GitHub tokeny by měly mít minimální potřebná oprávnění
348 
349### Přístup k GitHub Models
350 
351- Pro GitHub Models jsou vyžadovány Personal Access Tokens (PAT)
352- Tokeny ukládejte jako proměnné prostředí
353- Nikdy nesdílejte tokeny ani přihlašovací údaje v repozitáři
354 
355## Další poznámky
356 
357### Cílové publikum
358 
359- Absolutní začátečníci ve webovém vývoji
360- Studenti a samouci
361- Učitelé používající kurikulum ve třídách
362- Obsah je navržen pro přístupnost a postupné budování dovedností
363 
364### Vzdělávací filozofie
365 
366- Přístup založený na projektech
367- Časté kontroly znalostí (kvízy)
368- Praktické kódovací cvičení
369- Příklady aplikací z reálného světa
370- Zaměření na základy před frameworky
371 
372### Údržba repozitáře
373 
374- Aktivní komunita studentů a přispěvatelů
375- Pravidelné aktualizace závislostí a obsahu
376- Problémy a diskuse spravovány správci
377- Aktualizace překladů automatizovány přes GitHub Actions
378 
379### Související 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) doporučen pro studenty
384- Další kurzy: Generativní AI, Data Science, ML, IoT dostupné kurikula
385 
386### Práce s konkrétními projekty
387 
388Pro detailní instrukce u jednotlivých projektů nahlédněte do README souborů:
389- `quiz-app/README.md` - Vue 3 aplikace kvízu
390- `7-bank-project/README.md` - Bankovní aplikace s autentizací
391- `5-browser-extension/README.md` - Vývoj prodlužků prohlížeče
392- `6-space-game/README.md` - Vývoj hry na canvasu
393- `9-chat-project/README.md` - Projekt AI chat asistenta
394 
395### Struktura monorepa
396 
397I když nejde o tradiční monorepo, tento repozitář obsahuje několik nezávislých projektů:
398- Každá lekce je samostatná
399- Projekty nesdílí závislosti
400- Práce na jednotlivých projektech neovlivňuje ostatní
401- Naklonujte celý repozitář pro plný zážitek kurikula
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Prohlášení o vyloučení odpovědnosti**:
407Tento dokument byl přeložen pomocí AI překladatelské služby [Co-op Translator](https://github.com/Azure/co-op-translator). I když usilujeme o přesnost, mějte prosím na paměti, že automatické překlady mohou obsahovat chyby nebo nepřesnosti. Původní dokument v jeho rodném jazyce by měl být považován za autoritativní zdroj. Pro důležité informace se doporučuje profesionální lidský překlad. Nejsme zodpovědní za jakákoliv nedorozumění nebo nesprávné výklady vyplývající z použití tohoto překladu.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->