AGENTS.md

1# AGENTS.md
2 
3## Pregled projekta
4 
5Ovo je repozitorij nastavnog programa za podučavanje osnova web razvoja početnicima. Nastavni plan i program je sveobuhvatan tečaj u trajanju od 12 tjedana koji su razvili Microsoft Cloud Advocates, a sadrži 24 praktične lekcije koje pokrivaju JavaScript, CSS i HTML.
6 
7### Ključne komponente
8 
9- **Nastavni sadržaj**: 24 strukturirane lekcije organizirane u module temeljene na projektima
10- **Praktični projekti**: Terrarij, Igra tipkanja, Proširenje za preglednik, Svemirska igra, Bankarska aplikacija, Code Editor i AI Chat asistent
11- **Interaktivni kvizovi**: 48 kvizova sa po 3 pitanja svaki (procjena prije i nakon lekcije)
12- **Višestruka podrška jezika**: Automatski prijevodi na 50+ jezika putem GitHub Actions
13- **Tehnologije**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (za AI projekte)
14 
15### Arhitektura
16 
17- Edukativni repozitorij sa strukturom baziranom na lekcijama
18- Svaka mapa lekcije sadrži README, primjere koda i rješenja
19- Samostalni projekti u posebnim direktorijima (quiz-app, razni projektni lekcijski direktoriji)
20- Sustav prevođenja pomoću GitHub Actions (co-op-translator)
21- Dokumentacija poslužena putem Docsify i dostupna kao PDF
22 
23## Komande za postavljanje
24 
25Ovaj repozitorij je primarno namijenjen za konzumaciju edukativnog sadržaja. Za rad s određenim projektima:
26 
27### Postavljanje glavnog repozitorija
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Postavljanje Quiz aplikacije (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Pokreni razvojni poslužitelj
40npm run build      # Izgradi za produkciju
41npm run lint       # Pokreni ESLint
42```
43 
44### Bankarski projekt API (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Pokreni API poslužitelj
50npm run lint       # Pokreni ESLint
51npm run format     # Formatiraj s Prettierom
52```
53 
54### Projekti proširenja za preglednik
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Slijedite upute za učitavanje ekstenzija specifičnih za preglednik
60```
61 
62### Projekti svemirske igre
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Otvorite index.html u pregledniku ili koristite Live Server
68```
69 
70### Chat projekt (Python Backend)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Postavi varijablu okoline GITHUB_TOKEN
76python api.py
77```
78 
79## Razvojni tijek rada
80 
81### Za suradnike na sadržaju
82 
831. **Forkajte repozitorij** na svoj GitHub račun
842. **Klonirajte svoj fork** lokalno
853. **Napravite novu granu** za svoje promjene
864. Izvršite promjene u sadržaju lekcija ili primjerima koda
875. Testirajte sve izmjene koda u odgovarajućim projektnim direktorijima
886. Pošaljite pull requestove u skladu s uputama za doprinose
89 
90### Za učenike
91 
921. Forkajte ili klonirajte repozitorij
932. Navigirajte kroz direktorije lekcija redom
943. Čitajte README datoteke za svaku lekciju
954. Završite kvizove prije lekcija na https://ff-quizzes.netlify.app/web/
965. Riješite primjere koda u mapama lekcija
976. Završite zadatke i izazove
987. Polažite kvizove nakon lekcija
99 
100### Živi razvoj
101 
102- **Dokumentacija**: Pokrenite `docsify serve` u rootu (port 3000)
103- **Quiz aplikacija**: Pokrenite `npm run dev` u direktoriju quiz-app
104- **Projekti**: Koristite VS Code Live Server ekstenziju za HTML projekte
105- **API projekti**: Pokrenite `npm start` u odgovarajućim API direktorijima
106 
107## Upute za testiranje
108 
109### Testiranje Quiz aplikacije
110 
111```bash
112cd quiz-app
113npm run lint       # Provjeri probleme sa stilom koda
114npm run build      # Provjeri uspješnost izgradnje
115```
116 
117### Testiranje Bank API-ja
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Provjeri probleme sa stilom koda
122node server.js     # Provjeri da li se poslužitelj pokreće bez grešaka
123```
124 
125### Opći pristup testiranju
126 
127- Ovo je edukativni repozitorij bez sveobuhvatnih automatskih testova
128- Ručno testiranje fokusira se na:
129  - Primjere koda koji se izvršavaju bez pogrešaka
130  - Ispravno funkcioniranje linkova u dokumentaciji
131  - Uspješnu gradnju projekata
132  - Slijedjenje najboljih praksi u primjerima
133 
134### Provjere prije slanja
135 
136- Pokrenite `npm run lint` u direktorijima s package.json
137- Provjerite valjanost markdown linkova
138- Testirajte primjere koda u pregledniku ili Node.js
139- Provjerite da prijevodi održavaju pravilnu strukturu
140 
141## Smjernice za stil kodiranja
142 
143### JavaScript
144 
145- Koristite modernu ES6+ sintaksu
146- Slijedite standardne ESLint konfiguracije iz projekata
147- Koristite smisleno imenovanje varijabli i funkcija radi jasnoće za učenike
148- Dodajte komentare koji objašnjavaju koncepte
149- Formatirajte kod koristeći Prettier gdje je konfigurirano
150 
151### HTML/CSS
152 
153- Semantički HTML5 elementi
154- Principi responzivnog dizajna
155- Jasne konvencije imenovanja klasa
156- Komentari koji objašnjavaju CSS tehnike za učenike
157 
158### Python
159 
160- Pridržavajte se PEP 8 smjernica
161- Jasni, edukativni primjeri koda
162- Tipizacije tamo gdje pomažu učenju
163 
164### Markdown dokumentacija
165 
166- Jasna hijerarhija naslova
167- Code blokovi s označenim jezikom
168- Linkovi na dodatne resurse
169- Screenshoti i slike u mapama `images/`
170- Alt tekst za slike radi pristupačnosti
171 
172### Organizacija datoteka
173 
174- Lekcije numerirane sekvencijalno (1-getting-started-lessons, 2-js-basics, itd.)
175- Svaki projekt ima direktorije `solution/` i često `start/` ili `your-work/`
176- Slike se nalaze u lekcijski specifičnim mapama `images/`
177- Prijevodi u strukturi `translations/{language-code}/`
178 
179## Gradnja i implementacija
180 
181### Postavljanje Quiz aplikacije (Azure Static Web Apps)
182 
183Quiz aplikacija je konfigurirana za implementaciju na Azure Static Web Apps:
184 
185```bash
186cd quiz-app
187npm run build      # Stvara mapu dist/
188# Implementira putem GitHub Actions workflow-a pri pushanju na main
189```
190 
191Konfiguracija Azure Static Web Apps:
192- **Lokacija aplikacije**: `/quiz-app`
193- **Lokacija izlaza**: `dist`
194- **Workflow**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Generiranje PDF dokumentacije
197 
198```bash
199npm install                    # Instalirajte docsify-to-pdf
200npm run convert               # Generirajte PDF iz docsa
201```
202 
203### Dokumentacija Docsify
204 
205```bash
206npm install -g docsify-cli    # Instalirajte Docsify globalno
207docsify serve                 # Poslužite na localhost:3000
208```
209 
210### Gradnje specifične za projekte
211 
212Svaki projektni direktorij može imati vlastiti proces gradnje:
213- Vue projekti: `npm run build` kreira produkcijske bundleove
214- Statički projekti: bez koraka gradnje, direktna usluga datoteka
215 
216## Smjernice za pull requestove
217 
218### Format naslova
219 
220Koristite jasne, opisne naslove koji označavaju područje promjene:
221- `[Quiz-app] Dodaj novi kviz za lekciju X`
222- `[Lesson-3] Ispravi tipfelere u terrarium projektu`
223- `[Translation] Dodaj španjolski prijevod za lekciju 5`
224- `[Docs] Ažuriraj upute za postavljanje`
225 
226### Potrebne provjere
227 
228Prije slanja PR-a:
229 
2301. **Kvaliteta koda**:
231   - Pokrenite `npm run lint` u pogođenim projektnim direktorijima
232   - Ispravite sve lint greške i upozorenja
233 
2342. **Verifikacija gradnje**:
235   - Pokrenite `npm run build` ako je primjenjivo
236   - Osigurajte da nema grešaka u gradnji
237 
2383. **Provjera linkova**:
239   - Testirajte sve markdown linkove
240   - Provjerite ispravnost referenci na slike
241 
2424. **Pregled sadržaja**:
243   - Provjerite pravopis i gramatiku
244   - Osigurajte da su primjeri koda točni i edukativni
245   - Provjerite da prijevodi čuvaju izvorno značenje
246 
247### Zahtjevi za doprinos
248 
249- Prihvatite Microsoft CLA (automatska provjera pri prvom PR-u)
250- Slijedite [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
251- Pogledajte [CONTRIBUTING.md](./CONTRIBUTING.md) za detaljne upute
252- U opisu PR-a navedite brojeve povezanih issuea ako ih ima
253 
254### Proces pregleda
255 
256- PR-ove pregledavaju održavatelji i zajednica
257- Prioritet je jasnoća edukativnog sadržaja
258- Primjeri koda trebaju slijediti trenutne najbolje prakse
259- Prijevodi se pregledavaju radi točnosti i kulturne prikladnosti
260 
261## Sustav prevođenja
262 
263### Automatizirani prijevod
264 
265- Koristi GitHub Actions s co-op-translator workflowom
266- Automatski prevodi na 50+ jezika
267- Izvorne datoteke u glavnim direktorijima
268- Prevedene datoteke u direktorijima `translations/{language-code}/`
269 
270### Dodavanje ručnih poboljšanja prijevoda
271 
2721. Pronađite datoteku u `translations/{language-code}/`
2732. Napravite poboljšanja pazeći na očuvanje strukture
2743. Osigurajte ispravnost funkcionalnosti primjera koda
2754. Testirajte eventualni lokalizirani sadržaj kvizova
276 
277### Metapodaci prijevoda
278 
279Prevedene datoteke sadrže metapodatkovni header:
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## Otklanjanje pogrešaka i rješavanje problema
293 
294### Česti problemi
295 
296**Quiz aplikacija ne želi startati**:
297- Provjerite verziju Node.js (preporučeno v14+)
298- Izbrišite `node_modules` i `package-lock.json`, pokrenite `npm install` ponovno
299- Provjerite sukobe portova (default: Vite koristi port 5173)
300 
301**API server se ne pokreće**:
302- Provjerite zadovoljava li Node.js minimalnu verziju (node >=10)
303- Provjerite je li port zauzet
304- Osigurajte da su sve ovisnosti instalirane s `npm install`
305 
306**Proširenje za preglednik se ne učitava**:
307- Provjerite ispravnost manifest.json formata
308- Provjerite konzolu preglednika za greške
309- Slijedite upute za instalaciju proširenja specifične za preglednik
310 
311**Problemi s Python chat projektom**:
312- Provjerite je li instaliran paket OpenAI: `pip install openai`
313- Provjerite je li GITHUB_TOKEN varijabla okruženja postavljena
314- Provjerite dozvole pristupa za GitHub Models
315 
316**Docsify ne poslužuje dokumente**:
317- Instalirajte docsify-cli globalno: `npm install -g docsify-cli`
318- Pokrenite iz root direktorija repozitorija
319- Provjerite postoji li `docs/_sidebar.md`
320 
321### Savjeti za razvojno okruženje
322 
323- Koristite VS Code s Live Server ekstenzijom za HTML projekte
324- Instalirajte ESLint i Prettier ekstenzije za dosljedno formatiranje
325- Koristite DevTools u pregledniku za debug JavaScripta
326- Za Vue projekte instalirajte Vue DevTools ekstenziju za preglednik
327 
328### Razmatranja performansi
329 
330- Veliki broj prevedenih datoteka (50+ jezika) uzrokuje velike klonove
331- Koristite shallow clone ako radite samo na sadržaju: `git clone --depth 1`
332- Isključite prijevode iz pretraživanja kad radite na sadržaju na engleskom
333- Procesi gradnje mogu biti spori pri prvom pokretanju (npm install, Vite build)
334 
335## Sigurnosna razmatranja
336 
337### Varijable okruženja
338 
339- API ključevi se nikad ne bi smjeli komitirati u repozitorij
340- Koristite `.env` datoteke (već navedene u `.gitignore`)
341- Dokumentirajte potrebne varijable okruženja u README-ima projekata
342 
343### Python projekti
344 
345- Koristite virtualna okruženja: `python -m venv venv`
346- Održavajte ovisnosti ažurnima
347- GitHub tokeni trebaju imati minimalne potrebne dozvole
348 
349### Pristup GitHub Models
350 
351- Potrebni su Personal Access Tokens (PAT) za GitHub modele
352- Tokeni trebaju biti pohranjeni kao varijable okruženja
353- Nikad nemojte komitirati tokene ili vjerodajnice
354 
355## Dodatne napomene
356 
357### Ciljana publika
358 
359- Potpuni početnici u web razvoju
360- Studenti i samostalni učenici
361- Nastavnici koji koriste nastavne planove u učionicama
362- Sadržaj je osmišljen za pristupačnost i postupno stjecanje vještina
363 
364### Pedagoška filozofija
365 
366- Pristup učenja baziran na projektima
367- Česte provjere znanja (kvizovi)
368- Praktične vježbe kodiranja
369- Primjeri iz stvarnog svijeta
370- Fokus na temelje prije okvira
371 
372### Održavanje repozitorija
373 
374- Aktivna zajednica učenika i suradnika
375- Redovne nadogradnje ovisnosti i sadržaja
376- Problemi i diskusije praćeni od strane održavatelja
377- Automatska ažuriranja prijevoda putem GitHub Actions
378 
379### Povezani resursi
380 
381- [Microsoft Learn moduli](https://docs.microsoft.com/learn/)
382- [Student Hub resursi](https://docs.microsoft.com/learn/student-hub/)
383- Preporučen GitHub Copilot za učenike: [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot)
384- Dodatni tečajevi: Generativni AI, Data Science, ML, IoT kurikulumi dostupni
385 
386### Rad s određenim projektima
387 
388Za detaljne upute o pojedinačnim projektima, pogledajte README datoteke u:
389- `quiz-app/README.md` - Vue 3 aplikacija kviza
390- `7-bank-project/README.md` - Bankarska aplikacija s autentikacijom
391- `5-browser-extension/README.md` - Razvoj proširenja za preglednik
392- `6-space-game/README.md` - Razvoj igre bazirane na canvasu
393- `9-chat-project/README.md` - Projekt AI chat asistenta
394 
395### Struktura Monorepo repozitorija
396 
397Iako nije tradicionalni monorepo, repozitorij sadrži više nezavisnih projekata:
398- Svaka lekcija je samostalna
399- Projekti ne dijele ovisnosti
400- Rad na pojedinačnim projektima bez utjecaja na druge
401- Klonirajte cijeli repozitorij za potpuno iskustvo nastavnog programa
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Odricanje od odgovornosti**:
407Ovaj dokument je preveden pomoću AI usluge za prijevod [Co-op Translator](https://github.com/Azure/co-op-translator). Iako težimo točnosti, molimo imajte na umu da automatski prijevodi mogu sadržavati pogreške ili netočnosti. Izvorni dokument na njegovom izvornom jeziku treba smatrati autoritativnim izvorom. Za važne informacije preporučuje se profesionalni ljudski prijevod. Ne snosimo odgovornost za bilo kakve nesporazume ili kriva tumačenja koja proizlaze iz korištenja ovog prijevoda.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->