AGENTS.md

1# AGENTS.md
2 
3## Projektin yleiskatsaus
4 
5Tämä on opetussisältöjen arkisto, joka on tarkoitettu web-kehityksen perusteiden opettamiseen aloittelijoille. Oppimateriaali on kattava 12 viikon kurssi, jonka ovat kehittäneet Microsoft Cloud Advocates -tiimin jäsenet. Kurssi koostuu 24 käytännönlähtöisestä oppitunnista, jotka käsittelevät JavaScriptiä, CSS:ää ja HTML:ää.
6 
7### Keskeiset osat
8 
9- **Opetussisältö**: 24 jäsenneltyä oppituntia, jotka on järjestetty projektipohjaisiksi moduuleiksi
10- **Käytännön projektit**: Terrarium, Typing Game, selainlaajennus, Space Game, Banking App, Code Editor ja AI Chat Assistant
11- **Interaktiiviset tietovisat**: 48 tietovisaa, joissa on 3 kysymystä kukin (ennen ja jälkeen oppitunnin arvioinnit)
12- **Monikielinen tuki**: Automaattiset käännökset yli 50 kielelle GitHub Actionsin avulla
13- **Teknologiat**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (tekoälyprojekteissa)
14 
15### Arkkitehtuuri
16 
17- Opetussisältöön perustuva arkisto oppituntirakenteella
18- Jokaisessa oppitunnin kansiossa on README, koodiesimerkkejä ja ratkaisumalleja
19- Itsenäiset projektit omissa hakemistoissaan (quiz-app, eri oppituntiprojektit)
20- Käännösjärjestelmä käyttää GitHub Actionsia (co-op-translator)
21- Dokumentaatio näytetään Docsifylla ja on saatavilla PDF-muodossa
22 
23## Asennuskomennot
24 
25Tätä arkistoa käytetään ensisijaisesti opetussisältöjen lukemiseen. Työskennellessäsi tiettyjen projektien parissa:
26 
27### Pääarkiston asennus
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Quiz-sovelluksen asennus (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Käynnistä kehityspalvelin
40npm run build      # Rakenna tuotantoon
41npm run lint       # Suorita ESLint
42```
43 
44### Bank-projektin API (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Käynnistä API-palvelin
50npm run lint       # Suorita ESLint
51npm run format     # Muotoile Prettierilla
52```
53 
54### Selainlaajennusprojektit
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Noudata selaimen erityisiä laajennusten latausohjeita
60```
61 
62### Space Game -projektit
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Avaa index.html selaimessa tai käytä Live Serveriä
68```
69 
70### Chat-projekti (Python Backend)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Aseta GITHUB_TOKEN-ympäristömuuttuja
76python api.py
77```
78 
79## Kehityskäytännöt
80 
81### Sisällöntuottajille
82 
831. **Forkkaa arkisto** omaan GitHub-tiliisi
842. **Kloonaa fork** paikallisesti
853. **Luo uusi haara** muutoksillesi
864. Tee muutoksia oppimateriaalin sisältöön tai koodiesimerkkeihin
875. Testaa muutoksia liittyvissä projektihakemistoissa
886. Lähetä pull-pyyntöjä ohjeiden mukaisesti
89 
90### Oppijoille
91 
921. Forkkaa tai kloonaa arkisto
932. Siirry oppituntien hakemistoihin peräjälkeen
943. Lue kunkin oppitunnin README-tiedostot
954. Suorita ennen oppituntia tehtävät tietovisat osoitteessa https://ff-quizzes.netlify.app/web/
965. Kokeile koodiesimerkkejä oppituntikansioissa
976. Tee annettuja tehtäviä ja haasteita
987. Suorita oppitunnin jälkeiset tietovisat
99 
100### Live-kehitys
101 
102- **Dokumentaatio**: Aja `docsify serve` juurihakemistosta (portti 3000)
103- **Quiz-sovellus**: Aja `npm run dev` quiz-app kansiossa
104- **Projektit**: Käytä VS Code Live Server -laajennusta HTML-projekteissa
105- **API-projektit**: Aja `npm start` vastaavissa API-kansioissa
106 
107## Testausohjeet
108 
109### Quiz-sovelluksen testaus
110 
111```bash
112cd quiz-app
113npm run lint       # Tarkista koodityyliongelmat
114npm run build      # Varmista, että käännös onnistuu
115```
116 
117### Bank-API:n testaus
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Tarkista koodityylin ongelmat
122node server.js     # Varmista, että palvelin käynnistyy ilman virheitä
123```
124 
125### Yleinen testauslähestymistapa
126 
127- Tämä on opetussisältöarkisto, jossa ei ole kattavia automaattisia testejä
128- Manuaalinen testaus keskittyy:
129  - Koodiesimerkkien toimivuuteen ilman virheitä
130  - Dokumentaation linkkien toimivuuteen
131  - Projektien kääntöjen onnistumiseen
132  - Esimerkkien noudattavan hyviä käytäntöjä
133 
134### Ennen lähettämistä tarkistettavaa
135 
136- Aja `npm run lint` kaikissa package.json-hakemistoissa
137- Tarkista markdown-linkkien toimivuus
138- Testaa koodiesimerkit selaimessa tai Node.js:ssä
139- Varmista, että käännökset säilyttävät oikean rakenteen
140 
141## Koodityyliohjeet
142 
143### JavaScript
144 
145- Käytä modernia ES6+ syntaksia
146- Noudata ESLintin standardikonfiguraatioita projekteissa
147- Käytä merkityksellisiä muuttujien ja funktioiden nimiä opetustarkoituksiin
148- Lisää kommentteja, jotka selittävät käsitteitä oppijoille
149- Muotoile koodi Prettierillä, kun se on asetettu
150 
151### HTML/CSS
152 
153- Semanttiset HTML5-elementit
154- Responsiivisen suunnittelun periaatteet
155- Selkeät luokkien nimeämiskäytännöt
156- Kommentit, jotka selittävät CSS-tekniikoita oppijoille
157 
158### Python
159 
160- Noudata PEP 8 -tyyliohjeita
161- Selkeät, opetukselliset koodiesimerkit
162- Käytä tyyppivihjeitä, kun ne auttavat oppimista
163 
164### Markdown-dokumentaatio
165 
166- Selkeä otsikkohierarkia
167- Koodilohkot kielellä merkattuina
168- Linkit lisäresursseihin
169- Kuvakaappaukset ja kuvat `images/` kansioissa
170- Kuvien alt-tekstit saavutettavuutta varten
171 
172### Tiedostojen järjestely
173 
174- Oppitunnit numeroitu järjestyksessä (1-getting-started-lessons, 2-js-basics jne.)
175- Jokaisella projektilla on `solution/` ja usein myös `start/` tai `your-work/` kansiot
176- Kuvat tallennettu oppituntikohtaisiin `images/` kansioihin
177- Käännökset rakenteessa `translations/{language-code}/`
178 
179## Käännös- ja julkaisuohjeet
180 
181### Quiz-sovelluksen julkaisu (Azure Static Web Apps)
182 
183Quiz-sovellus on konfiguroitu julkaistavaksi Azure Static Web Apps -palveluun:
184 
185```bash
186cd quiz-app
187npm run build      # Luo dist/ -kansion
188# Ottaa käyttöön GitHub Actions -työnkulun push-tapahtumassa main-haaraan
189```
190 
191Azure Static Web Apps -konfiguraatio:
192- **Sovelluksen sijainti**: `/quiz-app`
193- **Tulostuskansio**: `dist`
194- **Työnkulku**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Dokumentaation PDF:n luonti
197 
198```bash
199npm install                    # Asenna docsify-to-pdf
200npm run convert               # Luo PDF docsista
201```
202 
203### Docsify-dokumentaatio
204 
205```bash
206npm install -g docsify-cli    # Asenna Docsify globaalisti
207docsify serve                 # Palvele localhost:3000:ssa
208```
209 
210### Projektikohtaiset buildit
211 
212Jokaisella projekti-hakemistolla voi olla oma build-prosessinsa:
213- Vue-projektit: `npm run build` luo tuotantokokoelmat
214- Staattiset projektit: Ei build-vaihetta, tiedostot palvelimelle sellaisenaan
215 
216## Pull request -ohjeet
217 
218### Otsikkomuoto
219 
220Käytä selkeitä ja kuvaavia otsikoita, jotka kertovat muutoksen kohteen:
221- `[Quiz-app] Lisää uusi tietovisa oppitunnille X`
222- `[Lesson-3] Korjaa kirjoitusvirhe terrarium-projektissa`
223- `[Translation] Lisää espanjankielinen käännös oppitunnille 5`
224- `[Docs] Päivitä asennusohjeet`
225 
226### Pakolliset tarkistukset
227 
228Ennen PR:n lähettämistä:
229 
2301. **Koodin laatu**:
231   - Aja `npm run lint` asianomaisissa projektihakemistoissa
232   - Korjaa kaikki lint-virheet ja varoitukset
233 
2342. **Buildin toimivuus**:
235   - Aja `npm run build`, jos sovellettavissa
236   - Varmista, ettei build-virheitä ilmene
237 
2383. **Linkkien toimivuus**:
239   - Testaa kaikki markdown-linkit
240   - Varmista kuvaviitteiden toimivuus
241 
2424. **Sisällön tarkistus**:
243   - Tarkista oikeinkirjoitus ja kielioppi
244   - Varmista koodiesimerkkien oikeellisuus ja opetuksellisuus
245   - Tarkista, että käännökset säilyttävät alkuperäisen merkityksen
246 
247### Osallistumisvaatimukset
248 
249- Hyväksy Microsoft CLA (automaattinen tarkistus ensimmäisen PR:n yhteydessä)
250- Noudata [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/) -käyttäytymissääntöjä
251- Katso tarkemmat ohjeet [CONTRIBUTING.md](./CONTRIBUTING.md) -tiedostosta
252- Viittaa tarvittaessa issue-numeroihin PR-kuvauksessa
253 
254### Arviointiprosessi
255 
256- PR:t katselmoidaan ylläpitäjien ja yhteisön toimesta
257- Painotus opetuksellisessa selkeydessä
258- Koodiesimerkkien tulee noudattaa ajantasaisia hyviä käytäntöjä
259- Käännökset tarkistetaan paikkansapitävyyden ja kulttuurisen sopivuuden osalta
260 
261## Käännösjärjestelmä
262 
263### Automaattinen käännös
264 
265- Käyttää GitHub Actionsia ja co-op-translator -työnkulkua
266- Kääntää automaattisesti yli 50 kielelle
267- Lähdetiedostot ovat pääkansioissa
268- Käännetyt tiedostot löytyvät `translations/{language-code}/` -hakemistoista
269 
270### Manuaalisten parannusten lisääminen
271 
2721. Etsi tiedosto `translations/{language-code}/` -hakemistosta
2732. Tee parannuksia säilyttäen rakenne
2743. Varmista, että koodiesimerkit toimivat edelleen
2754. Testaa mahdolliset paikallistetut tietovisa-aiheet
276 
277### Käännösmetadata
278 
279Käännetyissä tiedostoissa on mukana metadataotsikko:
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## Virheenkorjaus ja vianetsintä
293 
294### Yleisiä ongelmia
295 
296**Quiz-sovellus ei käynnisty**:
297- Tarkista Node.js:n versio (v14+ suositeltu)
298- Poista `node_modules` ja `package-lock.json`, suorita `npm install` uudelleen
299- Tarkista, ettei portti ole käytössä (oletus: Vite käyttää porttia 5173)
300 
301**API-palvelin ei käynnisty**:
302- Varmista, että Node.js-versio täyttää vähimmäisvaatimuksen (node >=10)
303- Tarkista portin vapautuminen
304- Varmista, että kaikki riippuvuudet on asennettu komennolla `npm install`
305 
306**Selainlaajennus ei lataudu**:
307- Tarkista, että manifest.json on oikein muotoiltu
308- Katso selaimen konsolista virheilmoituksia
309- Noudata selaimen erityisohjeita laajennuksen asennukseen
310 
311**Python chat -projektin ongelmat**:
312- Varmista, että OpenAI-paketti on asennettu: `pip install openai`
313- Tarkista, että GITHUB_TOKEN-ympäristömuuttuja on määritelty
314- Tarkista GitHub Models -käyttöoikeudet
315 
316**Docsify ei tarjoile dokumentaatiota**:
317- Asenna docsify-cli globaalisti: `npm install -g docsify-cli`
318- Aja komento arkiston juurihakemistosta
319- Varmista, että `docs/_sidebar.md` on olemassa
320 
321### Kehitysympäristövinkit
322 
323- Käytä VS Codea Live Server -laajennuksen kanssa HTML-projekteissa
324- Asenna ESLint ja Prettier -laajennukset yhdenmukaisen muotoilun varmistamiseksi
325- Käytä selaimen DevTools-työkaluja JavaScriptin debuggaamiseen
326- Vue-projekteissa asenna Vue DevTools selaimen laajennus
327 
328### Suorituskyky
329 
330- Valtava määrä käännettyjä tiedostoja (yli 50 kieltä) tekee kokonaisklooneista suuria
331- Käytä pinnallista kloonausta, jos työskentelet vain sisällön parissa: `git clone --depth 1`
332- Poista käännökset hausta, kun työskentelet englanninkielisen sisällön kanssa
333- Build-prosessit voivat olla hitaita ensimmäisellä ajokerralla (npm install, Vite build)
334 
335## Turvakäytännöt
336 
337### Ympäristömuuttujat
338 
339- API-avaimia ei koskaan saa tallentaa arkistoon
340- Käytä `.env`-tiedostoja (sisältyvät jo `.gitignore`-tiedostoon)
341- Dokumentoi vaaditut ympäristömuuttujat projektien READMEssa
342 
343### Python-projektit
344 
345- Käytä virtuaaliympäristöjä: `python -m venv venv`
346- Pidä riippuvuudet ajan tasalla
347- GitHub-tokenit tulee rajoittaa minimitason käyttöoikeuksiin
348 
349### GitHub Models -käyttö
350 
351- Tarvitaan henkilökohtaiset käyttöoikeustokenit (PAT)
352- Tokenit tulee tallentaa ympäristömuuttujiksi
353- Älä koskaan tallenna tokeneita tai tunnuksia arkistoon
354 
355## Lisätietoja
356 
357### Kohdeyleisö
358 
359- Täysin aloittelijat web-kehityksessä
360- Opiskelijat ja itseopiskelijat
361- Opettajat, jotka käyttävät opetussuunnitelmaa luokkahuoneissa
362- Sisältö on suunniteltu saavutettavaksi ja asteittaisen taitojen kehittämisen mahdollistavaksi
363 
364### Opetussuunnitelman filosofia
365 
366- Projektipohjainen oppimismenetelmä
367- Tiheät tietovisat oppimisen tarkistamiseen
368- Käytännön ohjelmointiharjoitukset
369- Käytännön esimerkit todellisesta maailmasta
370- Perusteiden korostaminen ennen kehysten opettelua
371 
372### Arkiston ylläpito
373 
374- Aktiivinen oppijoiden ja avustajien yhteisö
375- Riittävä päivitystahti riippuvuuksille ja sisällölle
376- Ylläpitäjät seuraavat ongelmia ja keskusteluja
377- Käännösten päivitys on automatisoitu GitHub Actionsilla
378 
379### Liittyvät resurssit
380 
381- [Microsoft Learn -moduulit](https://docs.microsoft.com/learn/)
382- [Student Hubin materiaalit](https://docs.microsoft.com/learn/student-hub/)
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) suositellaan oppijoille
384- Lisäkursseja: Generative AI, Data Science, ML, IoT -opetussuunnitelmat ovat saatavilla
385 
386### Työskentely tietyissä projekteissa
387 
388Yksityiskohtaiset ohjeet eri projekteihin löytyvät niihin liittyvistä README-tiedostoista:
389- `quiz-app/README.md` - Vue 3 tietovisasovellus
390- `7-bank-project/README.md` - Pankkisovellus autentikoinnilla
391- `5-browser-extension/README.md` - Selainlaajennuksen kehitys
392- `6-space-game/README.md` - Canvas-pohjainen peli
393- `9-chat-project/README.md` - AI chat assistant -projekti
394 
395### Monorepo-rakenne
396 
397Vaikka tämä ei ole perinteinen monorepo, arkisto sisältää useita itsenäisiä projekteja:
398- Jokainen oppitunti on itsenäinen kokonaisuus
399- Projektit eivät jaa riippuvuuksia keskenään
400- Työskentele yksittäisten projektien parissa vaikuttamatta muihin
401- Kloonaa koko repositorio saadaksesi täyden opetussuunnitelman kokemuksen
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Vastuuvapauslauseke**:
407Tämä asiakirja on käännetty käyttämällä tekoälypohjaista käännöspalvelua [Co-op Translator](https://github.com/Azure/co-op-translator). Vaikka pyrimme tarkkuuteen, ota huomioon, että automaattikäännöksissä saattaa esiintyä virheitä tai epätarkkuuksia. Alkuperäistä asiakirjaa sen alkuperäisellä kielellä pidetään auktoritatiivisena lähteenä. Tärkeiden tietojen osalta suositellaan ammattimaista ihmiskäännöstä. Emme ole vastuussa tämän käännöksen käytöstä aiheutuvista väärinymmärryksistä tai virhetulkinnoista.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->