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### Проект чата (Backend на Python)
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- **Проекты**: Используйте расширение VS Code Live Server для 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### Тестирование 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# Выполняет деплой через workflow GitHub Actions при пуше в main
189```
190 
191Конфигурация Azure Static Web Apps:
192- **Расположение приложения**: `/quiz-app`
193- **Расположение сборки**: `dist`
194- **Workflow**: `.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   - Исправьте все ошибки и предупреждения linter
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](https://opensource.microsoft.com/codeofconduct/)
251- См. [CONTRIBUTING.md](./CONTRIBUTING.md) для подробных инструкций
252- Указывайте номера issue в описании 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 не ниже 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)
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- Контроль за issue и обсуждениями мейнтэйнерами
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- Дополнительные курсы: генеративный AI, Data Science, ML, IoT
385 
386### Работа с конкретными проектами
387 
388Для подробных инструкций по отдельным проектам смотрите README файлы в:
389- `quiz-app/README.md` - Vue 3 quiz приложение
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Этот документ был переведен с помощью сервиса автоматического перевода [Co-op Translator](https://github.com/Azure/co-op-translator). Несмотря на наши усилия по обеспечению точности, пожалуйста, учитывайте, что автоматические переводы могут содержать ошибки или неточности. Оригинальный документ на исходном языке следует считать авторитетным источником. Для критически важной информации рекомендуется профессиональный перевод носителем языка. Мы не несем ответственности за любые недоразумения или неправильные толкования, возникающие в результате использования этого перевода.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->