course-cli-LVAAVL 0.1.0

CLI-инструмент для структурирования учебных курсов

🎓 Course CLI

Course CLI — это консольный инструмент (teacher-side модуль) для преподавателей и методистов. Он позволяет рассматривать учебный курс как проект с готовой файловой структурой, обеспечивая единый стандарт разработки образовательных материалов.

🎯 Какую проблему мы решаем?

Обычно курсы создаются хаотично: файлы теряются, названия разделов непоследовательны, а учебные результаты (outcomes) и компетенции (skills) формулируются задним числом или забываются вовсе.

Course CLI генерирует стандартизированный шаблон курса при старте, заставляет автора продумать метаданные заранее и автоматически проверяет целостность курса (битые ссылки, пропущенные уроки).

---

🚀 Основной функционал

• Scaffolding (Генерация): Интерактивное создание структуры папок, Markdown-файлов и конфигурации course.yaml.
• Умная валидация: Проверка наличия обязательных полей, последовательности уроков и поиск «битых» внутренних ссылок.
• Аналитика: Генерация красивого дашборда с образовательными метриками и структурой курса.
• Интеграция с xAPI: Автоматическое логирование событий (initialized, validated, reported) в локальный файл-хранилище log.json по стандартам Evidence Locker.

---

🛠 Установка

Инструмент упакован как Python-пакет и поддерживает запуск через Docker.

Локальная установка (Рекомендуется для разработки)

Убедитесь, что у вас установлен Python 3.12+ и выполните:

git clone <ваш-репозиторий>
cd course-cli
make install

Запуск через Docker

Если вы не хотите устанавливать Python локально:

make docker-build
make docker-up

---

📖 Использование (Сценарий преподавателя)

После установки вам доступна глобальная команда course-cli.

1. Создание нового курса

Запустите команду и следуйте интерактивным подсказкам терминала:

course-cli init MyCourse

Что произойдет: Будет создана директория MyCourse/, файл course.yaml, корневой index.md и папки с уроками.

2. Проверка курса

Перед публикацией убедитесь, что курс не содержит ошибок:

course-cli validate MyCourse

Что произойдет: Скрипт проверит наличие результатов обучения, найдет пропущенные уроки и рекурсивно проверит все [ссылки](...) в Markdown файлах.

3. Отчет и аналитика

Сгенерируйте статистику по созданному материалу:

course-cli report MyCourse

Что произойдет: В консоль будет выведен аналитический дашборд (количество модулей, уроков, пустых разделов). При подтверждении будет записано xAPI-событие.

---

🤖 Команды автоматизации (Makefile)

Для удобства разработки и тестирования в проекте настроен Makefile.

Команда	Описание
make demo	🎬 Запуск сквозного демо-сценария (E2E). Создает курс, прогоняет проверку (специально ловит тестовую ошибку) и выводит отчет. Идеально для демонстрации работы.
make test	Запускает набор unit и интеграционных тестов через pytest.
make coverage	Генерирует отчет о покрытии кода тестами (в консоли и HTML).
make run-cli	Выводит справку по доступным командам CLI.

---

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

course-cli/
├── src/course_cli/        # Исходный код модуля
│   ├── cli.py             # Точка входа и маршрутизация команд
│   ├── validate.py        # Логика проверки курса
│   ├── report.py          # Логика сбора статистики
│   └── xapi.py            # Генератор событий по контракту xAPI
├── tests/                 # Автотесты (pytest)
├── scripts/               # Git-хуки (pre-commit для защиты коммитов)
├── Makefile               # Автоматизация рутинных задач
├── module.yaml            # Паспорт модуля
├── .env.example           # Шаблон переменных окружения
└── README.md              # Документация проекта

---

🔒 xAPI и Приватность

Все события логируются локально в директории курса (log.json). Система не собирает персональные данные студентов или полные тексты уроков, фиксируя только факты (verb) успешного выполнения действий преподавателем (actor) по спецификации xAPI.