AGENTS.md

1# AGENTS.md
2 
3## Prezentare generală a proiectului
4 
5Acesta este un depozit curricular educațional pentru predarea elementelor fundamentale ale dezvoltării web începătorilor. Curriculumul este un curs cuprinzător de 12 săptămâni, dezvoltat de Microsoft Cloud Advocates, care include 24 de lecții practice acoperind JavaScript, CSS și HTML.
6 
7### Componente cheie
8 
9- **Conținut educațional**: 24 de lecții structurate organizate în module bazate pe proiecte
10- **Proiecte practice**: Terrarium, Joc de tastare, Extensie pentru browser, Joc spațial, Aplicație bancară, Editor de cod și Asistent chat AI
11- **Chestionare interactive**: 48 de chestionare cu câte 3 întrebări fiecare (evaluări pre/post-lecție)
12- **Suport multi-limbă**: Traduceri automate pentru peste 50 de limbi prin GitHub Actions
13- **Tehnologii**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (pentru proiectele AI)
14 
15### Arhitectură
16 
17- Depozit educațional cu structură bazată pe lecții
18- Fiecare folder de lecție conține README, exemple de cod și soluții
19- Proiecte autonome în directoare separate (quiz-app, diverse proiecte din lecții)
20- Sistem de traducere folosind GitHub Actions (co-op-translator)
21- Documentația este servită prin Docsify și disponibilă ca PDF
22 
23## Comenzi de configurare
24 
25Acest depozit este destinat în principal consumului de conținut educațional. Pentru a lucra cu proiecte specifice:
26 
27### Configurare depozit principal
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Configurare Quiz App (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Pornește serverul de dezvoltare
40npm run build      # Compilează pentru producție
41npm run lint       # Rulează ESLint
42```
43 
44### API Proiect Bancar (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Pornește serverul API
50npm run lint       # Rulează ESLint
51npm run format     # Formatează cu Prettier
52```
53 
54### Proiecte Extensie de Browser
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Urmați instrucțiunile specifice browserului pentru încărcarea extensiilor
60```
61 
62### Proiecte Joc Spațial
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Deschide index.html în browser sau folosește Live Server
68```
69 
70### Proiect Chat (backend Python)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Setează variabila de mediu GITHUB_TOKEN
76python api.py
77```
78 
79## Flux de dezvoltare
80 
81### Pentru contribuitori de conținut
82 
831. **Furcați depozitul** în contul vostru GitHub
842. **Clonați furca local**
853. **Creați un nou branch** pentru modificările voastre
864. Faceți modificări la conținutul lecțiilor sau la exemplele de cod
875. Testați orice modificare de cod în directoarele relevante ale proiectului
886. Trimiteți pull request-uri respectând ghidul de contribuție
89 
90### Pentru cursanți
91 
921. Fork sau clonează depozitul
932. Navigați secvențial prin directoarele lecțiilor
943. Citiți fișierele README pentru fiecare lecție
954. Completați chestionarele pre-lecție la https://ff-quizzes.netlify.app/web/
965. Parcurgeți exemplele de cod din folderele lecțiilor
976. Finalizați temele și provocările
987. Susțineți chestionarele post-lecție
99 
100### Dezvoltare Live
101 
102- **Documentație**: Rulați `docsify serve` din rădăcină (port 3000)
103- **Quiz App**: Rulați `npm run dev` în directorul quiz-app
104- **Proiecte**: Folosiți extensia VS Code Live Server pentru proiectele HTML
105- **Proiecte API**: Rulați `npm start` în directoarele API relevante
106 
107## Instrucțiuni de testare
108 
109### Testare Quiz App
110 
111```bash
112cd quiz-app
113npm run lint       # Verifică problemele de stil ale codului
114npm run build      # Verifică dacă compilarea reușește
115```
116 
117### Testare Bank API
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Verifica problemele de stil de cod
122node server.js     # Verifică dacă serverul pornește fără erori
123```
124 
125### Abordare generală a testării
126 
127- Acesta este un depozit educațional fără teste automate complete
128- Testarea manuală se concentrează pe:
129  - Exemplele de cod să ruleze fără erori
130  - Linkurile din documentație să funcționeze corect
131  - Construirea proiectelor să fie finalizată cu succes
132  - Exemplele să respecte cele mai bune practici
133 
134### Verificări înainte de trimitere
135 
136- Rulați `npm run lint` în directoarele cu package.json
137- Verificați dacă linkurile markdown sunt valide
138- Testați exemplele de cod în browser sau în Node.js
139- Asigurați-vă că traducerile păstrează structura corectă
140 
141## Ghid de stil pentru cod
142 
143### JavaScript
144 
145- Folosiți sintaxa modernă ES6+
146- Respectați configurațiile standard ESLint oferite în proiecte
147- Utilizați nume de variabile și funcții semnificative pentru claritate educațională
148- Adăugați comentarii explicative pentru cursanți
149- Formatați folosind Prettier acolo unde este configurat
150 
151### HTML/CSS
152 
153- Elemente semantice HTML5
154- Principii de design responsive
155- Convenții clare de denumire a claselor
156- Comentarii care explică tehnicile CSS pentru cursanți
157 
158### Python
159 
160- Respectați ghidurile de stil PEP 8
161- Exemple de cod clare și educaționale
162- Indicații de tip unde sunt utile pentru învățare
163 
164### Documentație Markdown
165 
166- Ierarhie clară a titlurilor
167- Blocuri de cod cu specificație de limbaj
168- Linkuri către resurse suplimentare
169- Capturi de ecran și imagini în directoarele `images/`
170- Text alternativ pentru imagini pentru accesibilitate
171 
172### Organizarea fișierelor
173 
174- Lecțiile numerotate secvențial (1-getting-started-lessons, 2-js-basics etc.)
175- Fiecare proiect are directoare `solution/` și adesea `start/` sau `your-work/`
176- Imaginile sunt stocate în foldere specifice lecțiilor `images/`
177- Traducerile în structura `translations/{language-code}/`
178 
179## Build și implementare
180 
181### Implementarea Quiz App (Azure Static Web Apps)
182 
183quiz-app este configurat pentru implementarea pe Azure Static Web Apps:
184 
185```bash
186cd quiz-app
187npm run build      # Creează folderul dist/
188# Face deploy prin workflow-ul GitHub Actions la push în main
189```
190 
191Configurare Azure Static Web Apps:
192- **Locația aplicației**: `/quiz-app`
193- **Locația de output**: `dist`
194- **Workflow**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Generarea PDF documentație
197 
198```bash
199npm install                    # Instalează docsify-to-pdf
200npm run convert               # Generează PDF din docs
201```
202 
203### Documentație Docsify
204 
205```bash
206npm install -g docsify-cli    # Instalează Docsify la nivel global
207docsify serve                 # Servește pe localhost:3000
208```
209 
210### Build-uri specifice proiectelor
211 
212Fiecare director de proiect poate avea propriul proces de build:
213- Proiecte Vue: `npm run build` creează pachete de producție
214- Proiecte statice: Fără pas de build, se servesc fișierele direct
215 
216## Ghid pentru pull request-uri
217 
218### Formatul titlului
219 
220Folosiți titluri clare și descriptive care indică zona de modificare:
221- `[Quiz-app] Adaugă chestionar nou pentru lecția X`
222- `[Lesson-3] Corectează greșeală de scriere în proiectul terrarium`
223- `[Translation] Adaugă traducere în spaniolă pentru lecția 5`
224- `[Docs] Actualizează instrucțiuni de configurare`
225 
226### Verificări obligatorii
227 
228Înainte de a trimite un PR:
229 
2301. **Calitatea codului**:
231   - Rulați `npm run lint` în directoarele proiectului afectat
232   - Remediați toate erorile și avertismentele lint
233 
2342. **Verificarea build-ului**:
235   - Rulați `npm run build` dacă este cazul
236   - Asigurați-vă că nu apar erori în build
237 
2383. **Validarea linkurilor**:
239   - Testați toate linkurile markdown
240   - Verificați că referințele imaginilor funcționează
241 
2424. **Revizuirea conținutului**:
243   - Corectați ortografia și gramatica
244   - Asigurați-vă că exemplele de cod sunt corecte și educaționale
245   - Verificați dacă traducerile păstrează sensul original
246 
247### Cerințe pentru contribuții
248 
249- Acceptați CLA Microsoft (verificare automată la primul PR)
250- Respectați [Codul de conduită Microsoft Open Source](https://opensource.microsoft.com/codeofconduct/)
251- Consultați [CONTRIBUTING.md](./CONTRIBUTING.md) pentru detalii
252- Referiți numerele issue-urilor în descrierea PR-ului, dacă este cazul
253 
254### Procesul de revizuire
255 
256- PR-urile sunt revizuite de mentori și comunitate
257- Prioritate pentru claritatea educațională
258- Exemplele de cod trebuie să urmeze cele mai bune practici actuale
259- Traducerile sunt verificate pentru acuratețe și adaptare culturală
260 
261## Sistem de traducere
262 
263### Traducere automată
264 
265- Folosește GitHub Actions cu workflow co-op-translator
266- Traduce automat în peste 50 de limbi
267- Fișiere sursă în directoarele principale
268- Fișiere traduse în directoarele `translations/{language-code}/`
269 
270### Adăugarea îmbunătățirilor manuale
271 
2721. Găsiți fișierul în `translations/{language-code}/`
2732. Faceți îmbunătățiri păstrând structura
2743. Asigurați-vă că exemplele de cod rămân funcționale
2754. Testați eventualele conținuturi locale din chestionare
276 
277### Metadate traducere
278 
279Fișierele traduse includ antet cu metadate:
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## Depanare și rezolvarea problemelor
293 
294### Probleme comune
295 
296**Quiz app nu pornește**:
297- Verificați versiunea Node.js (recomandat v14+)
298- Ștergeți `node_modules` și `package-lock.json`, rulați iar `npm install`
299- Verificați conflictele de port (implict: Vite folosește portul 5173)
300 
301**Serverul API nu pornește**:
302- Asigurați-vă că versiunea Node.js este minim node >=10
303- Verificați dacă portul este ocupat
304- Verificați că toate dependențele sunt instalate cu `npm install`
305 
306**Extensia de browser nu se încarcă**:
307- Verificați formatul corect al manifest.json
308- Consultați consola browserului pentru erori
309- Urmați instrucțiunile specifice browserului pentru instalarea extensiei
310 
311**Probleme proiect chat Python**:
312- Asigurați-vă că pachetul OpenAI este instalat: `pip install openai`
313- Verificați dacă variabila de mediu GITHUB_TOKEN este setată
314- Verificați permisiunile de acces la GitHub Models
315 
316**Docsify nu servește documentația**:
317- Instalați global docsify-cli: `npm install -g docsify-cli`
318- Rulați din directorul rădăcină al depozitului
319- Verificați existența fișierului `docs/_sidebar.md`
320 
321### Sfaturi pentru mediul de dezvoltare
322 
323- Folosiți VS Code cu extensia Live Server pentru proiectele HTML
324- Instalați extensiile ESLint și Prettier pentru formatare consistentă
325- Folosiți DevTools ale browserului pentru depanarea JavaScript
326- Pentru proiecte Vue, instalați extensia Vue DevTools în browser
327 
328### Considerații de performanță
329 
330- Numărul mare de fișiere traduse (50+ limbi) face clonările totale mari
331- Folosiți clonarea superficială dacă lucrați doar pe conținut: `git clone --depth 1`
332- Excludeți traducerile din căutări când lucrați pe conținut în engleză
333- Procesele de build pot fi lente la prima rulare (npm install, build Vite)
334 
335## Considerații de securitate
336 
337### Variabile de mediu
338 
339- Cheile API nu trebuie niciodată comise în depozit
340- Folosiți fișiere `.env` (deja în `.gitignore`)
341- Documentați variabilele de mediu necesare în README-urile proiectelor
342 
343### Proiecte Python
344 
345- Folosiți medii virtuale: `python -m venv venv`
346- Mențineți dependențele actualizate
347- Token-urile GitHub trebuie să aibă permisiuni minime necesare
348 
349### Acces GitHub Models
350 
351- Sunt necesare token-uri personale de acces (PAT) pentru GitHub Models
352- Token-urile trebuie păstrate ca variabile de mediu
353- Nu comiteți niciodată token-uri sau credențiale
354 
355## Note suplimentare
356 
357### Public țintă
358 
359- Începători compleți în dezvoltare web
360- Studenți și autodidacți
361- Profesori care folosesc curriculumul în săli de clasă
362- Conținut gândit pentru accesibilitate și dezvoltare graduală a competențelor
363 
364### Filosofie educațională
365 
366- Abordare bazată pe proiecte
367- Verificări frecvente ale cunoștințelor (chestionare)
368- Exerciții practice de codare
369- Exemple aplicate din lumea reală
370- Accent pe elementele fundamentale înaintea framework-urilor
371 
372### Mentenanță depozit
373 
374- Comunitate activă de cursanți și contribuitori
375- Actualizări regulate ale dependențelor și conținutului
376- Probleme și discuții monitorizate de mentori
377- Actualizări automate ale traducerilor prin GitHub Actions
378 
379### Resurse conexe
380 
381- [Module Microsoft Learn](https://docs.microsoft.com/learn/)
382- [Resurse Student Hub](https://docs.microsoft.com/learn/student-hub/)
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) recomandat pentru cursanți
384- Cursuri suplimentare: AI Generativ, Știința datelor, ML, curricula IoT disponibile
385 
386### Lucrul cu proiecte specifice
387 
388Pentru instrucțiuni detaliate despre proiectele individuale, consultați fișierele README din:
389- `quiz-app/README.md` - aplicație quiz Vue 3
390- `7-bank-project/README.md` - aplicație bancară cu autentificare
391- `5-browser-extension/README.md` - dezvoltarea extensiilor pentru browser
392- `6-space-game/README.md` - dezvoltarea jocurilor canvas
393- `9-chat-project/README.md` - proiect asistent chat AI
394 
395### Structura monorepo
396 
397Deși nu este un monorepo tradițional, acest depozit conține mai multe proiecte independente:
398- Fiecare lecție este autonomă
399- Proiectele nu împart dependențe
400- Lucrați pe proiectele individuale fără a afecta altele
401- Clonați întregul repo pentru experiența completă a curriculumului
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Declinare a responsabilității**:
407Acest document a fost tradus folosind serviciul de traducere AI [Co-op Translator](https://github.com/Azure/co-op-translator). Deși ne străduim pentru acuratețe, vă rugăm să rețineți că traducerile automate pot conține erori sau inexactități. Documentul original în limba sa nativă trebuie considerat sursa autoritară. Pentru informații critice, se recomandă traducerea profesională realizată de o persoană. Nu ne asumăm responsabilitatea pentru eventuale neînțelegeri sau interpretări greșite rezultate din utilizarea acestei traduceri.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->