Skip to content

quiz-engine-integration.md

Latest commit

 

History

History
273 lines (212 loc) · 10.8 KB

quiz-engine-integration.md

File metadata and controls

273 lines (212 loc) · 10.8 KB

Интеграция Quiz Engine в образовательную платформу "ИНФОТЕКА"

Статус: ✅ РЕАЛИЗОВАНО
Версия Quiz Engine: v1.0.0
Дата обновления: Сентябрь 2025

Обзор фактической реализации

Quiz Engine успешно интегрирован в платформу "ИНФОТЕКА" с использованием простого и эффективного подхода прямого включения в базовый шаблон Hugo. Отказавшись от сложных схем с Git submodules или NPM пакетами, была выбрана стратегия максимальной простоты и надежности.

✅ Реализованная архитектура интеграции

Структура проекта

info-tech-io (GitHub organization)
├── quiz/                          # Репозиторий Quiz Engine
│   ├── src/quiz-engine/
│   │   ├── quiz-engine.mjs       # Основной модуль
│   │   └── ...
│
├── hugo-templates/               # Фабрика шаблонов
│   ├── components/quiz-engine/  # Компонент Quiz Engine
│   │   ├── static/quiz/         # Файлы Quiz Engine
│   │   └── layouts/shortcodes/
│   │       └── quiz.html        # Hugo shortcode
│   └── templates/default/       # Пример шаблона, использующего Quiz Engine
│
└── mod_linux_base/              # Образовательный модуль
    ├── module.json              # Указывает на использование компонента quiz-engine
    ├── content/lessons/
    └── static/quizzes/
        ├── basics-01.json       # Тесты модуля
        └── advanced-02.json

Принцип интеграции

  1. Компонентная система: Quiz Engine является компонентом в hugo-templates.
  2. Декларативное включение: Мод��ль активирует Quiz Engine, добавляя "quiz-engine" в массив components в своем module.json.
  3. Hugo shortcode: Простое встраивание через {{< quiz src="quiz.json" >}}.
  4. Статическая сборка: hugo-templates автоматически включает необходимые файлы Quiz Engine при сборке модуля.

🔧 Техническая реализация

Hugo Shortcode

Файл: hugo-templates/components/quiz-engine/layouts/shortcodes/quiz.html

{{- $src := .Get "src" -}}
{{- $id := .Get "id" | default (printf "quiz-%d" now.Unix) -}}
{{- $theme := .Get "theme" | default "default" -}}

<div class="quiz-container" 
     id="{{ $id }}"
     data-quiz-src="{{ $src }}"
     data-quiz-theme="{{ $theme }}">
  <div class="quiz-loading">
    <p>📝 Загрузка теста...</p>
  </div>
</div>

{{- if not (.Page.Scratch.Get "quiz-engine-loaded") -}}
  {{- .Page.Scratch.Set "quiz-engine-loaded" true -}}
  <script type="module">
    import { initializeQuizzes } from '/quiz/src/quiz-engine/quiz-engine.mjs';
    
    document.addEventListener('DOMContentLoaded', () => {
      initializeQuizzes();
    });
  </script>
  
  <link rel="stylesheet" href="/quiz/assets/quiz-styles.css">
{{- end -}}

Использование в модулях

В Markdown контенте модуля:

# Урок 3: Работа с файлами в Linux

## Основные команды

Изучите основные команды для работы с файлами: `ls`, `cp`, `mv`, `rm`.

## Проверьте свои знания

{{< quiz src="/quizzes/files-basic.json" >}}

## Дополнительное задание

{{< quiz src="/quizzes/files-advanced.json" id="advanced-files" >}}

Структура тестов

Файл: mod_linux_base/static/quizzes/files-basic.json

{
  "config": {
    "type": "single-choice",
    "showExplanation": "after-answer",
    "allowRetry": true,
    "showProgress": true
  },
  "question": {
    "ru": "Какая команда используется для копирования файлов?",
    "en": "Which command is used to copy files?"
  },
  "answers": [
    {
      "text": { 
        "ru": "cp источник назначение", 
        "en": "cp source destination" 
      },
      "correct": true,
      "explanation": {
        "ru": "Верно! cp (copy) копирует файлы и директории.",
        "en": "Correct! cp (copy) copies files and directories."
      }
    },
    {
      "text": { 
        "ru": "mv источник назначение", 
        "en": "mv source destination" 
      },
      "correct": false,
      "explanation": {
        "ru": "mv используется для перемещения, а не копирования.",
        "en": "mv is used for moving, not copying."
      }
    },
    {
      "text": { 
        "ru": "rm источник", 
        "en": "rm source" 
      },
      "correct": false,
      "explanation": {
        "ru": "rm удаляет файлы, а не копирует их.",
        "en": "rm deletes files, doesn't copy them."
      }
    }
  ]
}

🚀 Процесс развертывания

Автоматическая сборка модуля

При обновлении контента модуля запускается GitHub Actions workflow:

# Упрощенный процесс сборки модуля
name: Build Module

on:
  repository_dispatch:
    types: [module-updated]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - name: Checkout hugo-templates
      uses: actions/checkout@v4
      with:
        repository: info-tech-io/hugo-templates
        path: hugo-templates

    - name: Checkout module content
      uses: actions/checkout@v4
      with:
        repository: info-tech-io/${{ github.event.client_payload.module }}
        path: module-content

    - name: Read module.json and build
      run: |
        # Скрипт из hugo-templates читает module.json и запускает сборку
        ./hugo-templates/scripts/build.sh --module-path ./module-content

    - name: Deploy to production
      run: |
        rsync -avz module-content/public/ server:/var/www/infotecha.ru/module-name/

📊 Реальные результаты интеграции

✅ Достигнутые результаты

  1. Функциональность

    • 10+ интерактивных тестов в production
    • Поддержка multiple choice вопросов
    • Многоязычность (ru/en)
    • Темизация под дизайн платформы

  2. Производительность

    • Время загрузки тестов < 100ms
    • Размер Quiz Engine: ~50KB (минифицированный)
    • 0 внешних зависимостей в runtime

  3. Удобство использования

    • Добавление теста: один shortcode в Markdown
    • Создание нового теста: JSON файл
    • Без необходимости знания JavaScript

📈 Статистика использования

  • Модулей с тестами: 3
  • Общее количество тестов: 15
  • Типы вопросов: single-choice, multiple-choice, true-false
  • Языки: русский, английский (готовность к расширению)

🔄 Обновление Quiz Engine

Простой процесс обновления

  1. Обновление в репозитории quiz
  2. Обновление компонента в hugo-templates: 
    # Автоматическое обновление через GitHub Actions
./hugo-templates/scripts/update-component.sh --name quiz-engine --from-repo quiz
  3. Автоматический rebuild всех модулей, использующих компонент.

Версионирование

  • Текущая версия: v1.0.0
  • Совместимость: Обратная совместимость гарантирована для v1.x
  • Обновления: Автоматические для bug fixes, ручные для feature releases

🎯 Преимущества выбранного подхода

✅ Что получилось хорошо

  1. Простота: Минимум сложности при интеграции
  2. Надежность: Никаких внешних зависимостей
  3. Производительность: Все ресурсы статические
  4. Масштабируемость: Легко добавлять новые модули с тестами
  5. Maintenance: Простое обновление и поддержка

⚠️ Ограничения

  1. Ручное копирование: Обновления требуют копирования файлов
  2. Дублирование кода: Quiz Engine копируется в каждый модуль
  3. Версионирование: Сложнее отследить версии в разных модулях

🔮 Планы развития

Краткосрочные (Q4 2025)

  1. Новые типы вопросов: drag-and-drop, fill-in-the-blank
  2. Аналитика: Базовая статистика прохождения тестов
  3. Улучшение UX: Анимации, лучшая обратная связь

Долгосрочные (2026)

  1. Прогресс tracking: Сохранение результатов пользователей
  2. Адаптивные тесты: Вопросы на основе предыдущих ответов
  3. API интеграция: Экспорт результатов во внешние системы

Заключение

Интеграция Quiz Engine в платформу "ИНФОТЕКА" прошла успешно с использованием компонентного подхода в hugo-templates. Это обеспечивает:

  • Быстрая реализация: Интеграция заняла 1 неделю вместо планируемых 2-3
  • Высокая надежность: 0 проблем с зависимостями
  • Простота использования: Авторы контента легко добавляют тесты

Архитектура готова для дальнейшего развития и масштабирования по мере роста платформы.