AGENTS.md

1# AGENTS.md
2 
3## Projekti ülevaade
4 
5See on hariduslik õppekava hoidla veebiarenduse aluste õpetamiseks algajatele. Õppekava on Microsoft Cloud Advocatesi poolt välja töötatud põhjalik 12-nädalane kursus, mis sisaldab 24 praktilist õppetundi JavaScripti, CSSi ja HTMLi kohta.
6 
7### Peamised komponendid
8 
9- **Hariduslik sisu**: 24 struktureeritud õppetundi projektipõhistes moodulites
10- **Praktilised projektid**: Terrarium, Trükkimismäng, Brauserilaiendus, Kosmosemäng, Pangaäpp, Koodiredaktor ja AI vestlusassistent
11- **Interaktiivsed viktoriinid**: 48 viktoriini, igaühes 3 küsimust (enne ja pärast õppetundi hindamised)
12- **Mitmekeelne tugi**: 50+ keele automaatne tõlge GitHub Actions abil
13- **Tehnoloogiad**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (AI projektide jaoks)
14 
15### Arhitektuur
16 
17- Hariduslik hoidla õppetundide struktuuriga
18- Igas õppetunni kaustas on README, koodinäited ja lahendused
19- Eraldiseisvad projektid eraldi kataloogides (quiz-app, erinevad õppetunniprojektid)
20- Tõlkesüsteem GitHub Actions (co-op-translator) abil
21- Dokumentatsioon esitatakse Docsify kaudu ja on saadaval PDF-formaadis
22 
23## Paigaldus käsud
24 
25See hoidla on mõeldud peamiselt haridussisu tarbimiseks. Spetsiifiliste projektidega töötamiseks:
26 
27### Peamise hoidla seadistamine
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Quiz App seadistamine (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Käivita arendusserver
40npm run build      # Ehita tootmiseks
41npm run lint       # Käivita ESLint
42```
43 
44### Pangaprojekti API (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Käivita API server
50npm run lint       # Käivita ESLint
51npm run format     # Vorminda Prettieriga
52```
53 
54### Brauserilaienduse projektid
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Järgige brauserispetsiifilisi laienduse laadimise juhiseid
60```
61 
62### Kosmosemängu projektid
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Ava index.html brauseris või kasuta Live Serverit
68```
69 
70### Vestlusprojekti tagaplaan (Python)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Määra keskkonnamuutuja GITHUB_TOKEN
76python api.py
77```
78 
79## Arendustöövoog
80 
81### Sisuloomele
82 
831. **Forki hoidla** oma GitHub kontole
842. **Klooni oma fork lokaalselt**
853. **Loo uus haru** oma muudatuste jaoks
864. Tee muudatusi õppe sisu või koodinäidetes
875. Testi muudatusi vastavates projektikaustades
886. Esita pull request vastavalt panustamise juhistele
89 
90### Õppijatele
91 
921. Forki või klooni hoidla
932. Liigu õppetundide kaustades järjekorras
943. Loe iga õppetunni README faile
954. Täida eelnevad viktoriinid aadressil https://ff-quizzes.netlify.app/web/
965. Töötle läbi õppetunni koodinäited
976. Täida ülesanded ja väljakutsed
987. Tee lõppviktoriinid
99 
100### Reaalajas arendus
101 
102- **Dokumentatsioon**: käivita juurkataloogis `docsify serve` (port 3000)
103- **Quiz App**: käivita `npm run dev` quiz-app kataloogis
104- **Projektid**: kasuta VS Code Live Server laiendust HTML projektide jaoks
105- **API projektid**: käivita vastavates API kaustades `npm start`
106 
107## Testimisjuhised
108 
109### Quiz App testimine
110 
111```bash
112cd quiz-app
113npm run lint       # Kontrolli koodistiili probleeme
114npm run build      # Kontrolli, kas ehitus õnnestub
115```
116 
117### Panga API testimine
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Kontrolli koodi stiiliprobleeme
122node server.js     # Kontrolli, et server käivitub ilma vigadeta
123```
124 
125### Üldine testimisviis
126 
127- See on hariduslik hoidla ilma põhjalike automatiseeritud testideta
128- Käsitsi testimine keskendub:
129  - Koodinäited töötavad ilma vigadeta
130  - Dokumentatsiooni lingid töötavad korrektselt
131  - Projektide ehitused õnnestuvad
132  - Näited järgivad parimaid tavasid
133 
134### Enne esitamist kontroll
135 
136- Käivita kataloogides, kus on package.json, `npm run lint`
137- Kontrolli markdown linkide korrasolekut
138- Testi koodinäiteid brauseris või Node.js-s
139- Veendu, et tõlked säilitavad õige struktuuri
140 
141## Koodi stiili juhised
142 
143### JavaScript
144 
145- Kasuta kaasaegset ES6+ süntaksit
146- Järgi projektides olevaid standardseid ESLint konfiguratsioone
147- Kasuta tähenduslikke muutujate ja funktsioonide nimesid selguse huvides
148- Lisa kommentaare, mis selgitavad mõisteid õppijatele
149- Vorminda koodi Prettieriga, kus see on seadistatud
150 
151### HTML/CSS
152 
153- Semantiline HTML5 elementide kasutus
154- Reageeriv disainiprintsiip
155- Selged klassinimede reeglid
156- Kommentaarid, mis selgitavad CSS tehnikaid õppijatele
157 
158### Python
159 
160- Järgi PEP 8 stiilijuhiseid
161- Selged ja hariduslikud koodinäited
162- Kasuta tüübiviiteid, kus õppimiseks kasulik
163 
164### Markdown dokumentatsioon
165 
166- Selge pealkirjade hierarhia
167- Koodiplokid koos keelespetsifikatsiooniga
168- Lingid lisamaterjalidele
169- Ekraanipildid ja pildid `images/` kaustades
170- Piltide jaoks alternatiivtekst ligipääsetavuse tagamiseks
171 
172### Failide organiseerimine
173 
174- Õppetunnid nummerdatud järjestikku (1-getting-started-lessons, 2-js-basics jne)
175- Igal projektil on `solution/` ja sageli `start/` või `your-work/` kaustad
176- Pildid salvestatud õppetundide spetsiifilistesse `images/` kaustadesse
177- Tõlked `translations/{language-code}/` struktuuris
178 
179## Ehitamine ja juurutamine
180 
181### Quiz App juurutamine (Azure Static Web Apps)
182 
183Quiz-app on konfigureeritud Azure Static Web Apps juurutamiseks:
184 
185```bash
186cd quiz-app
187npm run build      # Loob dist/ kausta
188# Paigaldab GitHub Actions töövoo kaudu, kui tehakse push main harusse
189```
190 
191Azure Static Web Apps konfiguratsioon:
192- **Rakenduse asukoht**: `/quiz-app`
193- **Väljundasukoht**: `dist`
194- **Töövoog**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Dokumentatsiooni PDF genereerimine
197 
198```bash
199npm install                    # Paigalda docsify-to-pdf
200npm run convert               # Genereeri PDF docsist
201```
202 
203### Docsify dokumentatsioon
204 
205```bash
206npm install -g docsify-cli    # Paigalda Docsify ülemaailmselt
207docsify serve                 # Serveeri aadressil localhost:3000
208```
209 
210### Projekti-spetsiifilised ehitused
211 
212Igal projekti kaustal võib olla oma ehitusprotsess:
213- Vue projektid: `npm run build` loob tootmispaketid
214- Staatilised projektid: eraldi ehitusetappi ei ole, faile serveeritakse otse
215 
216## Pull requesti juhised
217 
218### Pealkirja formaat
219 
220Kasuta selgeid ja kirjeldavaid pealkirju, mis näitavad muudatuse valdkonda:
221- `[Quiz-app] Lisa uus viktoriin õppetunnile X`
222- `[Lesson-3] Paranda kirjaviga terrarium projekti juures`
223- `[Translation] Lisa hispaania tõlge õppetunnile 5`
224- `[Docs] Uuenda paigaldusjuhiseid`
225 
226### Nõutavad kontrollid
227 
228Enne PR-i esitamist:
229 
2301. **Koodi kvaliteet**:
231   - Käivita mõjutatud projektikaustades `npm run lint`
232   - Paranda kõik lintimise vead ja hoiatused
233 
2342. **Ehituse kontroll**:
235   - Käivita `npm run build`, kui see kehtib
236   - Veendu, et ehitus ei anna vigu
237 
2383. **Linkide kontroll**:
239   - Testi kõiki markdown linke
240   - Kontrolli pildi viidete toimimist
241 
2424. **Sisu ülevaade**:
243   - Tee õigekirja ja grammatika ülevaade
244   - Veendu, et koodinäited on korrektsed ja hariduslikud
245   - Kontrolli, et tõlked säilitavad algse tähenduse
246 
247### Panustamise nõuded
248 
249- Nõustu Microsoft CLA-ga (automaatselt esimese PR-i juures)
250- Järgi [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
251- Vaata [CONTRIBUTING.md](./CONTRIBUTING.md) üksikasjalike juhiste jaoks
252- Viita PR kirjelduses vajadusel issue numbritele
253 
254### Ülevaatusprotsess
255 
256- PR-e vaatavad läbi hoidla hooldajad ja kogukond
257- Eesmärk on haridusliku selguse tagamine
258- Koodinäited peavad järgima parimaid tänaseid tavasid
259- Tõlked üle vaadatakse täpsuse ja kultuurilise sobivuse osas
260 
261## Tõlkesüsteem
262 
263### Automaatne tõlge
264 
265- Kasutab GitHub Actions koos co-op-translator töövooga
266- Tõlgib automaatselt 50+ keelde
267- Algfailid peamistest kataloogidest
268- Tõlgitud failid `translations/{language-code}/` kataloogides
269 
270### Käsitsi tõlkete parandused
271 
2721. Leia fail `translations/{language-code}/` kataloogis
2732. Tee parandused, hoides struktuuri muutumatuna
2743. Veendu, et koodinäited jäävad toimima
2754. Testi lokaliseeritud viktoriini sisu
276 
277### Tõlke metaandmed
278 
279Tõlgitud failidel on metaandmete päis:
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## Silumine ja probleemide lahendamine
293 
294### Levinud probleemid
295 
296**Quiz app ei käivitu**:
297- Kontrolli Node.js versiooni (soovituslik v14+)
298- Kustuta `node_modules` ja `package-lock.json`, käivita uuesti `npm install`
299- Kontrolli portide konflikte (vaikimisi: Vite kasutab porti 5173)
300 
301**API server ei käivitu**:
302- Kontrolli, et Node.js versioon on minimaalne (node >=10)
303- Veendu, et port ei ole juba kasutusel
304- Kontrolli, et kõik sõltuvused on paigaldatud `npm install` abil
305 
306**Brauserilaiend ei laaditu**:
307- Kontrolli, et manifest.json on korrektselt vormindatud
308- Vaata brauseri konsooli vigade jaoks
309- Järgi brauserispetsiifilisi laienduste paigaldusjuhiseid
310 
311**Python vestlusprojekti probleemid**:
312- Veendu, et OpenAI pakett on paigaldatud: `pip install openai`
313- Kontrolli, et GITHUB_TOKEN keskkonnamuutuja on määratud
314- Vaata GitHub Models juurde pääsemise õigusi
315 
316**Docsify ei serveeri dokumente**:
317- Paigalda docsify-cli globaalset: `npm install -g docsify-cli`
318- Käivita hoidla juurkataloogist
319- Veendu, et `docs/_sidebar.md` fail on olemas
320 
321### Arenduskeskkonna nõuanded
322 
323- Kasuta VS Code Live Server laiendust HTML projektide jaoks
324- Paigalda ESLint ja Prettier laiendused konsistentseks vormindamiseks
325- Kasuta brauseri DevTools JavaScripti silumiseks
326- Vue projektide jaoks installi Vue DevTools brauserilaiendus
327 
328### Tulemuslikkuse kaalutlused
329 
330- Suur hulk tõlgitud faile (50+ keelt) teeb täielikud kloonid mahukaks
331- Kasuta sumbunud klooni, kui töötad ainult sisuga: `git clone --depth 1`
332- Väldi tõlgete otsinguid, kui töötad ingliskeelse sisuga
333- Ehitusteenused võivad esimesel käivitamisel olla aeglased (npm install, Vite build)
334 
335## Turvanõuded
336 
337### Keskkonnamuutujad
338 
339- API võtmeid ei tohi kunagi hoidlas hoida
340- Kasuta `.env` faile (mida on juba `.gitignore`-s)
341- Dokumenteeri vajalikud keskkonnamuutujad projektide README-des
342 
343### Python projektid
344 
345- Kasuta virtuaalkeskkonda: `python -m venv venv`
346- Hoia sõltuvused värskendatud
347- GitHub tokenitel peaksid olema minimaalsed õigused
348 
349### GitHub Models ligipääs
350 
351- Isiklikud ligipääsu tokenid (PAT) on vajalikud GitHub Models jaoks
352- Tokenid salvestada keskkonnamuutujatena
353- Tokenid ega mandaadid ei tohi kunagi hoidlasse jõuda
354 
355## Lisamärkused
356 
357### Sihtgrupp
358 
359- Täielikud algajad veebiarenduses
360- Õpilased ja iseseisvad õppijad
361- Õpetajad, kes kasutavad õppekava klassiruumis
362- Sisu on loodud ligipääsetavaks ja samm-sammuliseks oskuste kasvatamiseks
363 
364### Haridusfilosoofia
365 
366- Projektipõhine õppimisviis
367- Sageli teadmiste kontrollid (viktoriinid)
368- Praktiseerivad kodeerimise harjutused
369- Reaalsed näited rakendustest
370- Keskendutakse alustele enne raamistikke
371 
372### Hoidla hooldus
373 
374- Aktiivne õppijate ja panustajate kogukond
375- Regulaarne sõltuvuste ja sisu uuendamine
376- Probleemid ja arutelud hooldajate jälgimisel
377- Tõlkeuuendused automatiseeritud GitHub Actions kaudu
378 
379### Seotud ressursid
380 
381- [Microsoft Learn moodulid](https://docs.microsoft.com/learn/)
382- [Student Hub ressursid](https://docs.microsoft.com/learn/student-hub/)
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) soovitatav õppijatele
384- Täiendavad kursused: Generatiivne AI, Andmeteadus, ML, IoT õppekavad saadaval
385 
386### Töö spetsiifiliste projektidega
387 
388Detailseid juhiseid üksikute projektide jaoks leiad nende README failidest:
389- `quiz-app/README.md` - Vue 3 viktoriini rakendus
390- `7-bank-project/README.md` - Pangarakendus autentimisega
391- `5-browser-extension/README.md` - Brauserilaienduse arendus
392- `6-space-game/README.md` - Canvas-põhine mänguarendus
393- `9-chat-project/README.md` - AI vestlusassistiendi projekt
394 
395### Monorepo struktuur
396 
397Kuigi see ei ole traditsiooniline monorepo, sisaldab see hoidla mitmeid iseseisvaid projekte:
398- Iga õppetund on eraldiseisev
399- Projektid ei jaga sõltuvusi
400- Töötada saab üksikute projektidega mõjutamata teisi
401- Klooni kogu hoidla tervikliku õppekava kogemiseks
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Vastutusest loobumine**:
407See dokument on tõlgitud kasutades tehisintellekti tõlketeenust [Co-op Translator](https://github.com/Azure/co-op-translator). Kuigi me püüame täpsust, palun arvestage, et automaatsed tõlked võivad sisaldada vigu või ebatäpseid osi. Originaaldokument selle emakeeles tuleks pidada autoriteetseks allikaks. Olulise teabe puhul soovitatakse kasutada professionaalset inimtõlget. Me ei vastuta selle tõlke kasutamisest tingitud arusaamatuste ega väärarusaamade eest.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->