📦 microsoft / Web-Dev-For-Beginners

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "a362efd06d64d4134a0cfe8515a86d34",
  "translation_date": "2025-10-11T11:37:15+00:00",
  "source_file": "AGENTS.md",
  "language_code": "et"
}
-->
# AGENTS.md

## Projekti Ülevaade

See on hariduslik õppekava hoidla, mis on mõeldud veebiarenduse põhialuste õpetamiseks algajatele. Õppekava on Microsoft Cloud Advocates'i poolt välja töötatud 12-nädalane kursus, mis sisaldab 24 praktilist õppetundi JavaScripti, CSS-i ja HTML-i kohta.

### Põhikomponendid

- **Hariduslik sisu**: 24 struktureeritud õppetundi, mis on organiseeritud projektipõhisteks mooduliteks
- **Praktilised projektid**: Terrarium, Klaviatuurimäng, Brauserilaiendus, Kosmosemäng, Pangarakendus, Koodiredaktor ja AI vestlusassistent
- **Interaktiivsed viktoriinid**: 48 viktoriini, igaühes 3 küsimust (enne/pärast õppetundi hindamised)
- **Mitmekeelne tugi**: Automaatne tõlkimine enam kui 50 keelde GitHub Actionsi kaudu
- **Tehnoloogiad**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (AI projektide jaoks)

### Arhitektuur

- Hariduslik hoidla õppetundide põhise struktuuriga
- Iga õppetunni kaust sisaldab README-d, koodinäiteid ja lahendusi
- Iseseisvad projektid eraldi kataloogides (quiz-app, erinevad õppetundide projektid)
- Tõlkesüsteem GitHub Actionsi abil (co-op-translator)
- Dokumentatsioon Docsify kaudu ja saadaval PDF-vormingus

## Seadistuskäsud

See hoidla on peamiselt mõeldud haridusliku sisu tarbimiseks. Konkreetsete projektidega töötamiseks:

### Peamise hoidla seadistamine

```bash
git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
cd Web-Dev-For-Beginners
```

### Viktoriinirakenduse seadistamine (Vue 3 + Vite)

```bash
cd quiz-app
npm install
npm run dev        # Start development server
npm run build      # Build for production
npm run lint       # Run ESLint
```

### Panga projekti API (Node.js + Express)

```bash
cd 7-bank-project/api
npm install
npm start          # Start API server
npm run lint       # Run ESLint
npm run format     # Format with Prettier
```

### Brauserilaienduste projektid

```bash
cd 5-browser-extension/solution
npm install
# Follow browser-specific extension loading instructions
```

### Kosmosemängu projektid

```bash
cd 6-space-game/solution
npm install
# Open index.html in browser or use Live Server
```

### Vestlusprojekt (Python tagapõhi)

```bash
cd 9-chat-project/solution/backend/python
pip install openai
# Set GITHUB_TOKEN environment variable
python api.py
```

## Arendustöövoog

### Sisu panustajatele

1. **Forki hoidla** oma GitHubi kontole
2. **Klooni oma fork** kohalikult
3. **Loo uus haru** oma muudatuste jaoks
4. Tee muudatusi õppetundide sisus või koodinäidetes
5. Testi koodimuudatusi vastavates projektikataloogides
6. Esita pull request vastavalt panustamise juhistele

### Õppijatele

1. Forki või klooni hoidla
2. Liigu järjestikku õppetundide kataloogides
3. Loe iga õppetunni README faile
4. Täida õppetunni eelsed viktoriinid aadressil https://ff-quizzes.netlify.app/web/
5. Töötle koodinäiteid õppetundide kaustades
6. Täida ülesandeid ja väljakutseid
7. Tee õppetunni järgsed viktoriinid

### Reaalajas arendus

- **Dokumentatsioon**: Käivita `docsify serve` juurkataloogis (port 3000)
- **Viktoriinirakendus**: Käivita `npm run dev` quiz-app kataloogis
- **Projektid**: Kasuta VS Code Live Server laiendust HTML projektide jaoks
- **API projektid**: Käivita `npm start` vastavates API kataloogides

## Testimisjuhised

### Viktoriinirakenduse testimine

```bash
cd quiz-app
npm run lint       # Check for code style issues
npm run build      # Verify build succeeds
```

### Panga API testimine

```bash
cd 7-bank-project/api
npm run lint       # Check for code style issues
node server.js     # Verify server starts without errors
```

### Üldine testimisviis

- See on hariduslik hoidla, millel puuduvad ulatuslikud automaatsed testid
- Käsitsi testimine keskendub:
  - Koodinäited töötavad ilma vigadeta
  - Dokumentatsiooni lingid töötavad korrektselt
  - Projektide ehitamine õnnestub
  - Näited järgivad parimaid praktikaid

### Enne esitust kontrollid

- Käivita `npm run lint` kataloogides, kus on package.json
- Kontrolli markdowni linkide kehtivust
- Testi koodinäiteid brauseris või Node.js-is
- Veendu, et tõlked säilitavad õige struktuuri

## Koodistiili juhised

### JavaScript

- Kasuta kaasaegset ES6+ süntaksit
- Järgi projektides pakutud standardseid ESLint konfiguratsioone
- Kasuta tähenduslikke muutujate ja funktsioonide nimesid haridusliku selguse huvides
- Lisa kommentaare, mis selgitavad õppijatele mõisteid
- Vorminda Prettieriga, kui see on seadistatud

### HTML/CSS

- Semantilised HTML5 elemendid
- Responsiivse disaini põhimõtted
- Selged klassinimede konventsioonid
- Kommentaarid, mis selgitavad CSS-i tehnikaid õppijatele

### Python

- PEP 8 stiilijuhised
- Selged, hariduslikud koodinäited
- Tüübiviited, kus need on õppimise jaoks kasulikud

### Markdown dokumentatsioon

- Selge pealkirjade hierarhia
- Koodiplokid keele spetsifikatsiooniga
- Lingid lisamaterjalidele
- Ekraanipildid ja pildid kataloogis `images/`
- Piltide alt-tekst ligipääsetavuse jaoks

### Failide organiseerimine

- Õppetunnid nummerdatud järjestikku (1-getting-started-lessons, 2-js-basics jne)
- Igal projektil on `solution/` ja sageli `start/` või `your-work/` kataloogid
- Pildid salvestatud õppetundide spetsiifilistesse `images/` kaustadesse
- Tõlked kataloogis `translations/{language-code}/` struktuuriga

## Ehitus ja juurutamine

### Viktoriinirakenduse juurutamine (Azure Static Web Apps)

Viktoriinirakendus on konfigureeritud Azure Static Web Apps juurutamiseks:

```bash
cd quiz-app
npm run build      # Creates dist/ folder
# Deploys via GitHub Actions workflow on push to main
```

Azure Static Web Apps konfiguratsioon:
- **Rakenduse asukoht**: `/quiz-app`
- **Väljundi asukoht**: `dist`
- **Töövoog**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`

### Dokumentatsiooni PDF-i genereerimine

```bash
npm install                    # Install docsify-to-pdf
npm run convert               # Generate PDF from docs
```

### Docsify dokumentatsioon

```bash
npm install -g docsify-cli    # Install Docsify globally
docsify serve                 # Serve on localhost:3000
```

### Projektispetsiifilised ehitused

Igal projektikataloogil võib olla oma ehitusprotsess:
- Vue projektid: `npm run build` loob tootmisvalmis paketid
- Staatilised projektid: Ehitusetapp puudub, serveeri failid otse

## Pull Request juhised

### Pealkirja formaat

Kasuta selgeid, kirjeldavaid pealkirju, mis viitavad muudatuste valdkonnale:
- `[Quiz-app] Lisa uus viktoriin õppetunni X jaoks`
- `[Lesson-3] Paranda kirjaviga terrariumi projektis`
- `[Translation] Lisa hispaania keele tõlge õppetunnile 5`
- `[Docs] Uuenda seadistusjuhiseid`

### Nõutavad kontrollid

Enne PR-i esitamist:

1. **Koodi kvaliteet**:
   - Käivita `npm run lint` mõjutatud projektikataloogides
   - Paranda kõik lintingu vead ja hoiatused

2. **Ehitus kinnitamine**:
   - Käivita `npm run build`, kui see on asjakohane
   - Veendu, et ehitusvead puuduvad

3. **Linkide valideerimine**:
   - Testi kõiki markdowni linke
   - Kontrolli, et pildiviited töötavad

4. **Sisu ülevaatus**:
   - Kontrolli õigekirja ja grammatikat
   - Veendu, et koodinäited on korrektsed ja hariduslikud
   - Kontrolli, et tõlked säilitavad algse tähenduse

### Panustamise nõuded

- Nõustu Microsoft CLA-ga (automaatne kontroll esimesel PR-il)
- Järgi [Microsofti avatud lähtekoodi käitumisjuhendit](https://opensource.microsoft.com/codeofconduct/)
- Vaata [CONTRIBUTING.md](./CONTRIBUTING.md) üksikasjalike juhiste jaoks
- Viita probleemide numbritele PR-i kirjelduses, kui see on asjakohane

### Ülevaatusprotsess

- PR-e vaatavad üle haldajad ja kogukond
- Hariduslik selgus on prioriteet
- Koodinäited peaksid järgima praeguseid parimaid praktikaid
- Tõlked vaadatakse üle täpsuse ja kultuurilise sobivuse osas

## Tõlkesüsteem

### Automaatne tõlkimine

- Kasutab GitHub Actionsi koos co-op-translator töövooga
- Tõlgib automaatselt enam kui 50 keelde
- Algfailid peamistes kataloogides
- Tõlgitud failid kataloogis `translations/{language-code}/`

### Käsitsi tõlke paranduste lisamine

1. Leia fail kataloogist `translations/{language-code}/`
2. Tee parandusi, säilitades struktuuri
3. Veendu, et koodinäited jäävad funktsionaalseks
4. Testi lokaliseeritud viktoriinisisu

### Tõlke metaandmed

Tõlgitud failid sisaldavad metaandmete päist:
```markdown
<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "...",
  "translation_date": "...",
  "source_file": "...",
  "language_code": "..."
}
-->
```

## Silumine ja tõrkeotsing

### Levinud probleemid

**Viktoriinirakendus ei käivitu**:
- Kontrolli Node.js versiooni (soovitatav v14+)
- Kustuta `node_modules` ja `package-lock.json`, käivita uuesti `npm install`
- Kontrolli porti konflikte (vaikimisi: Vite kasutab porti 5173)

**API server ei käivitu**:
- Veendu, et Node.js versioon vastab miinimumile (node >=10)
- Kontrolli, kas port on juba kasutusel
- Veendu, et kõik sõltuvused on paigaldatud `npm install` abil

**Brauserilaiendus ei laadi**:
- Kontrolli, et manifest.json on korrektselt vormindatud
- Kontrolli brauseri konsooli vigade osas
- Järgi brauserispetsiifilisi laienduse paigaldamise juhiseid

**Python vestlusprojekti probleemid**:
- Veendu, et OpenAI pakett on paigaldatud: `pip install openai`
- Kontrolli, et GITHUB_TOKEN keskkonnamuutuja on seadistatud
- Kontrolli GitHub Models juurdepääsuõigusi

**Docsify ei serveeri dokumente**:
- Paigalda docsify-cli globaalselt: `npm install -g docsify-cli`
- Käivita hoidla juurkataloogist
- Kontrolli, et `docs/_sidebar.md` eksisteerib

### Arenduskeskkonna näpunäited

- Kasuta VS Code'i koos Live Server laiendusega HTML projektide jaoks
- Paigalda ESLint ja Prettier laiendused ühtlaseks vormindamiseks
- Kasuta brauseri DevTools'i JavaScripti silumiseks
- Vue projektide jaoks paigalda Vue DevTools brauserilaiendus

### Jõudluse kaalutlused

- Suur hulk tõlgitud faile (50+ keelt) tähendab, et täielikud kloonid on mahukad
- Kasuta madalat klooni, kui töötad ainult sisuga: `git clone --depth 1`
- Välista tõlked otsingutest, kui töötad ingliskeelse sisuga
- Ehituse protsessid võivad esmakordsel käivitamisel olla aeglased (npm install, Vite build)

## Turvalisuse kaalutlused

### Keskkonnamuutujad

- API võtmeid ei tohiks kunagi hoidlasse lisada
- Kasuta `.env` faile (juba `.gitignore`-is)
- Dokumenteeri nõutavad keskkonnamuutujad projekti README-des

### Python projektid

- Kasuta virtuaalset keskkonda: `python -m venv venv`
- Hoia sõltuvused ajakohased
- GitHubi tokenid peaksid omama minimaalset vajalikku õigust

### GitHub Models juurdepääs

- Isiklikud juurdepääsutokenid (PAT) on vajalikud GitHub Models jaoks
- Tokenid tuleks salvestada keskkonnamuutujatena
- Ära kunagi lisa tokenit või mandaate hoidlasse

## Täiendavad märkused

### Sihtgrupp

- Täielikud algajad veebiarenduses
- Õpilased ja iseseisvad õppijad
- Õpetajad, kes kasutavad õppekava klassiruumis
- Sisu on loodud ligipääsetavuse ja järkjärgulise oskuste arendamise jaoks

### Haridusfilosoofia

- Projektipõhine õppe lähenemine
- Sagedased teadmiste kontrollid (viktoriinid)
- Praktilised koodiharjutused
- Päriselu rakenduste näited
- Keskendumine põhialustele enne raamistikke

### Hoidla hooldus

- Aktiivne õppijate ja panustajate kogukond
- Regulaarne sõltuvuste ja sisu uuendamine
- Probleemide ja arutelude jälgimine haldajate poolt
- Tõlkeuuendused automatiseeritud GitHub Actionsi kaudu

### Seotud ressursid

- [Microsoft Learn moodulid](https://docs.microsoft.com/learn/)
- [Student Hub ressursid](https://docs.microsoft.com/learn/student-hub/)
- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) soovitatav õppijatele
- Täiendavad kursused: Generatiivne AI, Andmeteadus, ML, IoT õppekavad saadaval

### Konkreetsete projektidega töötamine

Üksikasjalike juhiste jaoks individuaalsete projektide kohta vaata README faile:
- `quiz-app/README.md` - Vue 3 viktoriinirakendus
- `7-bank-project/README.md` - Pangarakendus autentimisega
- `5-browser-extension/README.md` - Brauserilaienduse arendus
- `6-space-game/README.md` - Canvas-põhine mänguarendus
- `9-chat-project/README.md` - AI vestlusassistendi projekt

### Monorepo struktuur

Kuigi mitte traditsiooniline monorepo, sisaldab see hoidla mitmeid iseseisvaid projekte:
- Iga õppetund on iseseisev
- Projektid ei jaga sõltuvusi
- Töötage individuaalsete projektidega, mõjutamata teisi
- Klooni kogu hoidla täieliku õppekava kogemuse jaoks

---

**Lahtiütlus**:  
See dokument on tõlgitud AI tõlketeenuse [Co-op Translator](https://github.com/Azure/co-op-translator) abil. Kuigi püüame tagada täpsust, palume arvestada, et automaatsed tõlked võivad sisaldada vigu või ebatäpsusi. Algne dokument selle algses keeles tuleks pidada autoriteetseks allikaks. Olulise teabe puhul soovitame kasutada professionaalset inimtõlget. Me ei vastuta selle tõlke kasutamisest tulenevate arusaamatuste või valesti tõlgenduste eest.