# AGENTS.md

## Огляд проєкту

Це навчальний репозиторій курсу для викладання основ веб-розробки для початківців. Курс є всебічним 12-тижневим курсом, розробленим Microsoft Cloud Advocates, що включає 24 практичні уроки з JavaScript, CSS та HTML.

### Ключові компоненти

- **Навчальний контент**: 24 структуровані уроки, організовані в модулі, орієнтовані на проєкти
- **Практичні проєкти**: Терраріум, Гра на друку, Розширення браузера, Космічна гра, Банківський додаток, Код-редактор і AI чат-асистент
- **Інтерактивні вікторини**: 48 вікторин по 3 питання у кожній (до/після уроку)
- **Підтримка багатьох мов**: Автоматичний переклад більш ніж на 50 мов за допомогою GitHub Actions
- **Технології**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (для AI проєктів)

### Архітектура

- Репозиторій з навчальним контентом, структурованим за уроками
- Кожна директорія уроку містить README, приклади коду та рішення
- Окремі проєкти розміщені в власних папках (quiz-app, різні уроки)
- Система перекладів з використанням GitHub Actions (co-op-translator)
- Документація подається через Docsify і доступна у форматі PDF

## Команди для налаштування

Цей репозиторій призначений переважно для споживання навчального контенту. Для роботи з конкретними проєктами:

### Основне налаштування репозиторію

```bash
git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
cd Web-Dev-For-Beginners
```

### Налаштування Quiz App (Vue 3 + Vite)

```bash
cd quiz-app
npm install
npm run dev        # Запустити сервер розробки
npm run build      # Зібрати для продакшена
npm run lint       # Запустити ESLint
```

### API Банківського проєкту (Node.js + Express)

```bash
cd 7-bank-project/api
npm install
npm start          # Запустити сервер API
npm run lint       # Запустити ESLint
npm run format     # Відформатувати за допомогою Prettier
```

### Проєкти розширень браузера

```bash
cd 5-browser-extension/solution
npm install
# Дотримуйтесь інструкцій із завантаження розширень, специфічних для браузера
```

### Проєкти космічної гри

```bash
cd 6-space-game/solution
npm install
# Відкрийте index.html у браузері або використовуйте Live Server
```

### Проєкт чату (Python бекенд)

```bash
cd 9-chat-project/solution/backend/python
pip install openai
# Встановіть змінну середовища GITHUB_TOKEN
python api.py
```

## Робочий процес розробки

### Для внесення контенту

1. **Форкніть репозиторій** у свій акаунт GitHub
2. **Клонуйте ваш форк** локально
3. **Створіть нову гілку** для своїх змін
4. Внесіть зміни у контент уроків або приклади коду
5. Перевірте коди у відповідних директоріях проєктів
6. Надішліть pull request відповідно до інструкцій внесення змін

### Для учнів

1. Форкніть або клонувати репозиторій
2. Перейдіть послідовно до директорій уроків
3. Читайте README в кожному уроці
4. Проходьте вікторини перед уроком на https://ff-quizzes.netlify.app/web/
5. Працюйте з прикладами коду в папках уроків
6. Виконуйте завдання і виклики
7. Проходьте вікторини після уроку

### Жива розробка

- **Документація**: Запустіть `docsify serve` у корені (порт 3000)
- **Quiz App**: Запустіть `npm run dev` у директорії quiz-app
- **Проєкти**: Використовуйте розширення VS Code Live Server для HTML-проєктів
- **API проєкти**: Запустіть `npm start` у відповідних API директоріях

## Інструкції для тестування

### Тестування Quiz App

```bash
cd quiz-app
npm run lint       # Перевірте проблеми зі стилем коду
npm run build      # Переконайтеся, що збірка проходить успішно
```

### Тестування Bank API

```bash
cd 7-bank-project/api
npm run lint       # Перевірте наявність проблем зі стилем коду
node server.js     # Переконайтеся, що сервер запускається без помилок
```

### Загальний підхід до тестування

- Це навчальний репозиторій без комплексних автоматизованих тестів
- Ручне тестування орієнтоване на:
  - Запуск прикладів коду без помилок
  - Правильну роботу посилань у документації
  - Успішне збирання проєктів
  - Відповідність прикладів найкращим практикам

### Перевірка перед подачею

- Запустіть `npm run lint` у директоріях з package.json
- Перевірте валідність markdown посилань
- Тестуйте приклади коду у браузері або Node.js
- Перевірте, що переклади мають правильну структуру

## Керівництво по стилю коду

### JavaScript

- Використовуйте сучасний синтаксис ES6+
- Дотримуйтесь стандартних ESLint конфігурацій проектів
- Використовуйте зрозумілі імена змінних і функцій для навчальної ясності
- Додавайте коментарі, що пояснюють концепції для учнів
- Форматуйте код за допомогою Prettier, де налаштовано

### HTML/CSS

- Семантичні елементи HTML5
- Принципи адаптивного дизайну
- Чітка система імен класів
- Коментарі, що пояснюють CSS-техніки для учнів

### Python

- Дотримання стилю PEP 8
- Зрозумілі, навчальні приклади коду
- Використання типових підказок, якщо це допомагає навчанню

### Документація у Markdown

- Чітка ієрархія заголовків
- Код-блоки з вказанням мови
- Посилання на додаткові ресурси
- Скриншоти та зображення в папках `images/`
- Опис alt для зображень для доступності

### Організація файлів

- Уроки пронумеровані послідовно (1-getting-started-lessons, 2-js-basics тощо)
- Кожен проєкт має папки `solution/` та часто `start/` або `your-work/`
- Зображення зберігаються у папках уроків `images/`
- Переклади зберігаються у структурі `translations/{language-code}/`

## Збирання та розгортання

### Розгортання Quiz App (Azure Static Web Apps)

quiz-app налаштовано для розгортання Azure Static Web Apps:

```bash
cd quiz-app
npm run build      # Створює папку dist/
# Виконує розгортання через workflow GitHub Actions при пуші в main
```

Конфігурація Azure Static Web Apps:
- **Розташування додатку**: `/quiz-app`
- **Розташування результату**: `dist`
- **Workflow**: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`

### Генерація PDF документації

```bash
npm install                    # Встановіть docsify-to-pdf
npm run convert               # Згенерувати PDF з docs
```

### Документація Docsify

```bash
npm install -g docsify-cli    # Встановіть Docsify глобально
docsify serve                 # Запуск на localhost:3000
```

### Зборки для конкретних проєктів

Кожна директорія проєкту може мати власний процес збірки:
- Vue проєкти: `npm run build` створює продакшн-бандли
- Статичні проєкти: Кроку збірки немає, файли подаються напряму

## Керівництво з Pull Request

### Формат заголовку

Використовуйте чіткі, описові заголовки, що вказують область змін:
- `[Quiz-app] Додати нову вікторину для уроку X`
- `[Lesson-3] Виправити описку у проєкті терраріум`
- `[Translation] Додати іспанський переклад для уроку 5`
- `[Docs] Оновити інструкції з налаштування`

### Обов’язкові перевірки

Перед подачею PR:

1. **Якість коду**:
   - Запустіть `npm run lint` у відповідних директоріях проєктів
   - Виправте всі помилки і зауваження lint

2. **Перевірка збірки**:
   - Запустіть `npm run build`, якщо застосовно
   - Переконайтесь, що немає помилок збірки

3. **Перевірка посилань**:
   - Протестуйте всі markdown-посилання
   - Перевірте роботу зображень

4. **Перевірка контенту**:
   - Вичитка на орфографію та граматику
   - Переконайтесь, що приклади коду коректні і навчальні
   - Перевірте, що переклади зберігають оригінальний зміст

### Вимоги до внесення змін

- Погодьтеся з Microsoft CLA (автоматична перевірка при першому PR)
- Дотримуйтесь [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/)
- Див. [CONTRIBUTING.md](./CONTRIBUTING.md) для детальних інструкцій
- Вказуйте номери issues у описі PR, якщо застосовно

### Процес огляду

- PR перевіряють мейнтейнери і спільнота
- Пріоритет надається навчальній зрозумілості
- Приклади коду мають відповідати сучасним кращим практикам
- Переклади перевіряються на точність і культурну відповідність

## Система перекладів

### Автоматичний переклад

- Використовує GitHub Actions з workflow co-op-translator
- Автоматично перекладає на понад 50 мов
- Файли-джерела у головних директоріях
- Переклади у `translations/{language-code}/`

### Додавання ручних покращень

1. Знайдіть файл у `translations/{language-code}/`
2. Внесіть покращення, зберігаючи структуру
3. Переконайтесь, що приклади коду функціональні
4. Протестуйте локалізований контент вікторин

### Метадані перекладів

Перекладені файли містять метадані у шапці:
```markdown
<!--
CO_OP_TRANSLATOR_METADATA:
{
  "original_hash": "...",
  "translation_date": "...",
  "source_file": "...",
  "language_code": "..."
}
-->
```

## Відлагодження та усунення проблем

### Типові проблеми

**Quiz app не запускається**:
- Перевірте версію Node.js (рекомендується v14+)
- Видаліть `node_modules` і `package-lock.json`, запустіть `npm install` знову
- Перевірте конфлікти портів (за замовчуванням Vite використовує порт 5173)

**API сервер не запускається**:
- Перевірте версію Node.js (node >=10)
- Перевірте, чи порт не зайнятий
- Переконайтесь, що всі залежності встановлені (`npm install`)

**Розширення браузера не завантажується**:
- Перевірте формат manifest.json
- Перегляньте помилки у консолі браузера
- Дотримуйтесь інструкцій установки для конкретного браузера

**Проблеми з Python чат-проєктом**:
- Переконайтесь, що пакет OpenAI встановлений: `pip install openai`
- Перевірте наявність змінної середовища GITHUB_TOKEN
- Перевірте права доступу GitHub Models

**Docsify не подає документацію**:
- Встановіть docsify-cli глобально: `npm install -g docsify-cli`
- Запустіть із кореневої папки репозиторію
- Переконайтесь, що існує файл `docs/_sidebar.md`

### Поради щодо середовища розробки

- Використовуйте VS Code з розширенням Live Server для HTML-проєктів
- Встановіть розширення ESLint і Prettier для консистентного форматування
- Використовуйте DevTools браузера для відлагодження JavaScript
- Для Vue проектів встановіть Vue DevTools браузерне розширення

### Особливості продуктивності

- Велика кількість перекладів (50+ мов) призводить до великих повних клонів
- Використовуйте shallow clone, якщо працюєте тільки з контентом: `git clone --depth 1`
- Ігноруйте переклади в пошуку при роботі з англійським контентом
- Процеси збірки можуть бути повільними при першому запуску (npm install, Vite build)

## Заходи безпеки

### Змінні оточення

- API ключі ніколи не мають потрапляти у репозиторій
- Використовуйте `.env` файли (вже в `.gitignore`)
- Документуйте потрібні змінні в README проєктів

### Python проєкти

- Використовуйте віртуальні середовища: `python -m venv venv`
- Оновлюйте залежності
- Токени GitHub повинні мати мінімальні необхідні дозволи

### Доступ до GitHub Models

- Потрібні персональні токени доступу (PAT) для GitHub Models
- Токени зберігайте у змінних оточення
- Ніколи не комітьте токени чи облікові дані

## Додаткові відомості

### Цільова аудиторія

- Повні новачки у веб-розробці
- Студенти та самонавчання
- Викладачі, що використовують курс у класах
- Контент створено з орієнтацією на доступність і поступове нарощування навичок

### Освітня філософія

- Проєктно-орієнтоване навчання
- Часті перевірки знань (вікторини)
- Практичні вправи з кодування
- Приклади реальних застосувань
- Фокус на основах перед фреймворками

### Підтримка репозиторію

- Активна спільнота учнів і контрибуторів
- Регулярні оновлення залежностей і контенту
- Моніторинг issues та дискусій мейнтейнерами
- Автоматичні оновлення перекладів через GitHub Actions

### Пов’язані ресурси

- [Microsoft Learn modules](https://docs.microsoft.com/learn/)
- [Student Hub resources](https://docs.microsoft.com/learn/student-hub/)
- [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) рекомендується для учнів
- Додаткові курси: генеративний AI, Data Science, ML, IoT

### Робота з конкретними проєктами

Для детальних інструкцій з окремих проєктів дивіться README файли у:
- `quiz-app/README.md` - Vue 3 quiz додаток
- `7-bank-project/README.md` - Банківський додаток з автентифікацією
- `5-browser-extension/README.md` - Розробка розширення браузера
- `6-space-game/README.md` - Розробка гри на Canvas
- `9-chat-project/README.md` - AI чат-асистент

### Структура монорепозиторію

Хоча це не традиційний монорепозиторій, він містить кілька незалежних проєктів:
- Кожен урок автономний
- Проєкти не ділять залежності
- Можна працювати з окремими проєктами без впливу на інші
- Клонування всього репозиторію для повного досвіду курсу

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**Відмова від відповідальності**:  
Цей документ був перекладений за допомогою сервісу автоматичного перекладу [Co-op Translator](https://github.com/Azure/co-op-translator). Хоча ми прагнемо до точності, будь ласка, майте на увазі, що автоматичні переклади можуть містити помилки або неточності. Оригінальний документ рідною мовою слід вважати авторитетним джерелом. Для критичної інформації рекомендується професійний переклад людиною. Ми не несемо відповідальності за будь-які непорозуміння або хибні тлумачення, що виникли внаслідок використання цього перекладу.
<!-- CO-OP TRANSLATOR DISCLAIMER END -->