AGENTS.md

1# AGENTS.md
2 
3## Преглед на проекта
4 
5Това е образователно хранилище за учебна програма за обучение на начинаещи в основите на уеб разработката. Учебната програма е всеобхватен 12-седмичен курс, разработен от Microsoft Cloud Advocates, включващ 24 практически урока, обхващащи JavaScript, CSS и HTML.
6 
7### Ключови компоненти
8 
9- **Образователно съдържание**: 24 структурирани урока, организирани в модули, базирани на проекти
10- **Практически проекти**: Террариум, Игра за писане, Разширение за браузър, Космическа игра, Банково приложение, Редактор на код и AI асистент за чат
11- **Интерактивни тестове**: 48 теста с по 3 въпроса всеки (оценки преди и след урок)
12- **Поддръжка на множество езици**: Автоматизирани преводи за 50+ езика чрез GitHub Actions
13- **Технологии**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (за AI проекти)
14 
15### Архитектура
16 
17- Образователно хранилище със структура, базирана на уроци
18- Всяка папка с урок съдържа README, примерен код и решения
19- Самостоятелни проекти в отделни директории (quiz-app, различни проекти от уроците)
20- Система за превод с използване на GitHub Actions (co-op-translator)
21- Документация, предоставена чрез Docsify и достъпна в PDF формат
22 
23## Команди за настройка
24 
25Това хранилище е основно за консумация на образователно съдържание. За работа с конкретни проекти:
26 
27### Основна настройка на хранилището
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### Настройка на Quiz App (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # Стартиране на сървър за разработка
40npm run build      # Създаване за продукция
41npm run lint       # Стартиране на ESLint
42```
43 
44### API на банковия проект (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # Стартиране на API сървър
50npm run lint       # Стартиране на ESLint
51npm run format     # Форматиране с Prettier
52```
53 
54### Проекти за разширения за браузър
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# Следвайте указанията за зареждане на разширения специфични за браузъра
60```
61 
62### Проекти за Космическата игра
63 
64```bash
65cd 6-space-game/solution
66npm install
67# Отворете index.html в браузър или използвайте Live Server
68```
69 
70### Проект за чат (Python backend)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# Задаване на променливата на средата GITHUB_TOKEN
76python api.py
77```
78 
79## Работен процес при разработка
80 
81### За сътрудници по съдържанието
82 
831. **Форкнете хранилището** в своя GitHub акаунт
842. **Клонирайте форка** локално
853. **Създайте нов клон** за вашите промени
864. Направете промени в съдържанието на урока или примерите за код
875. Тествайте всякакви промени в кода в съответните проектни директории
886. Подайте pull request според указанията за принос
89 
90### За учащите
91 
921. Форкнете или клонирайте хранилището
932. Навигирайте последователно през директориите с уроци
943. Прочетете README файловете за всеки урок
954. Попълнете тестовете преди урока на https://ff-quizzes.netlify.app/web/
965. Работете с примерите за код в папките на уроците
976. Завършете задачи и предизвикателства
987. Попълнете тестовете след урока
99 
100### Жива разработка
101 
102- **Документация**: Стартирайте `docsify serve` в главната директория (порт 3000)
103- **Quiz App**: Стартирайте `npm run dev` в директорията quiz-app
104- **Проекти**: Използвайте разширението Live Server на VS Code за HTML проекти
105- **API проекти**: Стартирайте `npm start` в съответните API директории
106 
107## Инструкции за тестване
108 
109### Тестване на Quiz App
110 
111```bash
112cd quiz-app
113npm run lint       # Проверка за проблеми със стила на кода
114npm run build      # Проверете дали сглобяването е успешно
115```
116 
117### Тестване на Bank API
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # Проверка за проблеми със стил на кода
122node server.js     # Проверете дали сървърът стартира без грешки
123```
124 
125### Общ подход за тестване
126 
127- Това е образователно хранилище без пълни автоматизирани тестове
128- Ръчното тестване се концентрира върху:
129  - Изпълнение на примерите за код без грешки
130  - Проверка дали линковете в документацията работят правилно
131  - Успешно завършване на билдовете на проектите
132  - Примерите следват добри практики
133 
134### Проверки преди подаване
135 
136- Стартирайте `npm run lint` в директории с package.json
137- Проверете валидността на връзките в markdown
138- Тествайте примерите за код в браузър или Node.js
139- Проверете дали преводите поддържат правилната структура
140 
141## Насоки за стил на кода
142 
143### JavaScript
144 
145- Използвайте модерен ES6+ синтаксис
146- Следвайте стандартните ESLint конфигурации, предоставени в проектите
147- Използвайте смислени имена на променливи и функции за образователна яснота
148- Добавяйте коментари, обясняващи концепциите за учащите
149- Форматирайте с Prettier, където е конфигуриран
150 
151### HTML/CSS
152 
153- Семантични HTML5 елементи
154- Принципи на отзивчив дизайн
155- Ясни конвенции за именуване на класове
156- Коментари, обясняващи CSS техники за учащите
157 
158### Python
159 
160- Стилови насоки PEP 8
161- Ясни, образователни примери за код
162- Типови подсказки, където е полезно за обучението
163 
164### Markdown документация
165 
166- Ясна йерархия на заглавията
167- Кодови блокове с посочен език
168- Връзки към допълнителни ресурси
169- Скриншотове и изображения в директориите `images/`
170- Alt текст за изображения за достъпност
171 
172### Организация на файловете
173 
174- Уроците са подредени последователно (1-getting-started-lessons, 2-js-basics и др.)
175- Всеки проект има директории `solution/` и често `start/` или `your-work/`
176- Изображенията се съхраняват в папки `images/`, специфични за урока
177- Преводите са в структура `translations/{language-code}/`
178 
179## Създаване и внедряване
180 
181### Внедряване на Quiz App (Azure Static Web Apps)
182 
183quiz-app е конфигуриран за внедряване в Azure Static Web Apps:
184 
185```bash
186cd quiz-app
187npm run build      # Създава папка dist/
188# Разгръща чрез GitHub Actions workflow при push към main
189```
190 
191Конфигурация за Azure Static Web Apps:
192- **Папка на приложението**: `/quiz-app`
193- **Изходна папка**: `dist`
194- **Работен процес**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### Генериране на документация в PDF
197 
198```bash
199npm install                    # Инсталиране на docsify-to-pdf
200npm run convert               # Генериране на PDF от docs
201```
202 
203### Документация с Docsify
204 
205```bash
206npm install -g docsify-cli    # Инсталирайте Docsify глобално
207docsify serve                 # Сървирайте на localhost:3000
208```
209 
210### Специфични билдове за проекти
211 
212Всяка проектна директория може да има собствен процес на билд:
213- Проекти с Vue: `npm run build` създава продукционни пакети
214- Статични проекти: няма стъпка за билд, файловете се сервира директно
215 
216## Насоки за pull request
217 
218### Формат на заглавието
219 
220Използвайте ясни и описателни заглавия, показващи областта на промяната:
221- `[Quiz-app] Добавяне на нов тест за урок X`
222- `[Lesson-3] Поправка на правописна грешка в проекта террариум`
223- `[Translation] Добавяне на испански превод за урок 5`
224- `[Docs] Актуализация на инструкциите за настройка`
225 
226### Задължителни проверки
227 
228Преди подаване на PR:
229 
2301. **Качество на кода**:
231   - Стартирайте `npm run lint` в засегнатите проектни директории
232   - Поправете всички грешки и предупреждения
233 
2342. **Проверка на билд**:
235   - Стартирайте `npm run build`, ако е приложимо
236   - Уверете се, че няма грешки при билд
237 
2383. **Проверка на линкове**:
239   - Тествайте всички markdown връзки
240   - Проверете референциите към изображения
241 
2424. **Преглед на съдържанието**:
243   - Корекция на правопис и граматика
244   - Уверете се, че примерите за код са правилни и образователни
245   - Проверете дали преводите запазват оригиналния смисъл
246 
247### Изисквания за принос
248 
249- Съгласие с Microsoft CLA (автоматична проверка при първи PR)
250- Спазване на [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
251- Вижте [CONTRIBUTING.md](./CONTRIBUTING.md) за подробни указания
252- Позоваване на номерата на проблеми в описанието на PR, ако е приложимо
253 
254### Процес на преглед
255 
256- PR се преглежда от поддържащи и общността
257- Предпочита се образователна яснота
258- Примерите за код трябва да следват актуални добри практики
259- Преводите се проверяват за точност и културна уместност
260 
261## Система за превод
262 
263### Автоматизиран превод
264 
265- Използва GitHub Actions с workflow co-op-translator
266- Превежда автоматично на 50+ езика
267- Изходни файлове в основните директории
268- Преведените файлове в директории `translations/{language-code}/`
269 
270### Добавяне на ръчни подобрения на превода
271 
2721. Намерете файла в `translations/{language-code}/`
2732. Направете подобрения, като запазите структурата
2743. Уверете се, че примерите за код остават функционални
2754. Тествайте локализираното съдържание на тестове
276 
277### Метаданни на превода
278 
279Преведените файлове включват метаданни в хедъра:
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## Отстраняване на грешки и проблеми
293 
294### Чести проблеми
295 
296**Quiz app не стартира**:
297- Проверете версията на Node.js (препоръчително v14+)
298- Изтрийте `node_modules` и `package-lock.json`, стартирайте `npm install` отново
299- Проверете за конфликти на портове (по подразбиране Vite използва порт 5173)
300 
301**API сървърът не стартира**:
302- Уверете се, че версията на Node.js е поне node >=10
303- Проверете дали портът е зает
304- Уверете се, че всички зависимости са инсталирани с `npm install`
305 
306**Разширението за браузър не се зарежда**:
307- Проверете дали manifest.json е правилно форматиран
308- Разгледайте конзолата на браузъра за грешки
309- Следвайте указанията за инсталиране на разширения според браузъра
310 
311**Проблеми с Python чат проект**:
312- Уверете се, че пакетът OpenAI е инсталиран: `pip install openai`
313- Проверете, че променливата на средата GITHUB_TOKEN е зададена
314- Проверете разрешенията за достъп до GitHub Models
315 
316**Docsify не подава документация**:
317- Инсталирайте docsify-cli глобално: `npm install -g docsify-cli`
318- Стартирайте от коренната директория на хранилището
319- Проверете дали съществува `docs/_sidebar.md`
320 
321### Съвети за развойна среда
322 
323- Използвайте VS Code с разширението Live Server за HTML проекти
324- Инсталирайте разширения ESLint и Prettier за консистентно форматиране
325- Използвайте DevTools на браузъра за дебъгване на JavaScript
326- За Vue проекти инсталирайте Vue DevTools разширението за браузър
327 
328### Съображения за производителността
329 
330- Голям брой преведени файлове (50+ езика) означава, че пълните клонирания са големи
331- Използвайте shallow clone, ако работите само със съдържание: `git clone --depth 1`
332- Изключвайте преводите от търсения при работа с английско съдържание
333- Процесите на билд могат да са бавни при първо изпълнение (npm install, Vite build)
334 
335## Съображения за сигурността
336 
337### Променливи на средата
338 
339- API ключове никога не трябва да се комитират в хранилището
340- Използвайте `.env` файлове (вече в `.gitignore`)
341- Документирайте изискваните променливи на средата в README файловете на проектите
342 
343### Python проекти
344 
345- Използвайте виртуални среди: `python -m venv venv`
346- Поддържайте зависимостите актуални
347- GitHub токените трябва да имат минималните необходими разрешения
348 
349### Достъп до GitHub Models
350 
351- За GitHub Models се изискват Personal Access Tokens (PAT)
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- Автоматизирани актуализации на преводите чрез GitHub Actions
378 
379### Свързани ресурси
380 
381- [Microsoft Learn модули](https://docs.microsoft.com/learn/)
382- [Ресурси от Student Hub](https://docs.microsoft.com/learn/student-hub/)
383- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) препоръчван за учащи
384- Допълнителни курсове: Generative AI, Data Science, ML, IoT учебни поредици налични
385 
386### Работа с конкретни проекти
387 
388За подробни инструкции относно отделните проекти, вижте README файловете в:
389- `quiz-app/README.md` - Vue 3 приложение за викторини
390- `7-bank-project/README.md` - Банково приложение с удостоверяване
391- `5-browser-extension/README.md` - Разработка на разширение за браузър
392- `6-space-game/README.md` - Разработка на игра с Canvas
393- `9-chat-project/README.md` - Проект с AI асистент за чат
394 
395### Структура на монохранилището
396 
397Въпреки че не е традиционно монохранилище, това хранилище съдържа множество независими проекти:
398- Всеки урок е самостоятелен
399- Проектите не споделят зависимости
400- Работете по отделни проекти, без да засягате други
401- Клонирайте цялото хранилище за пълното учебно преживяване
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**Отказ от отговорност**:
407Този документ е преведен чрез AI преводаческа услуга [Co-op Translator](https://github.com/Azure/co-op-translator). Въпреки че се стремим към точност, моля, имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Ние не носим отговорност за каквито и да било недоразумения или неправилни тълкувания, произтичащи от използването на този превод.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->