lms-sb/LMS_PROJECT_BRIEF.md

LMS-проект: стартовый бриф для Claude Code

Этот документ — отправная точка проекта. Положи его в корень репозитория как PROJECT_BRIEF.md. В первой сессии Claude Code попроси: «Прочитай PROJECT_BRIEF.md, задай мне уточняющие вопросы по архитектуре, затем предложи план работ по этапам и создай CLAUDE.md с ключевыми правилами проекта».

---

1. Контекст и цель

Я — автор образовательных курсов (PKM, Obsidian). Сейчас размещаюсь на сторонней LMS-платформе (emdesell.ru), хочу переехать на собственное решение, которое буду развивать сам с помощью Claude Code.

Цель: собственная LMS, развёрнутая на моём сервере в Hetzner, с бесшовной интеграцией Kinescope, ролями, прогрессом и проверкой ДЗ.

Масштаб: ~1000 учётных записей, ~200 активных, до 10 курсов одновременно. Это камерный проект, не маркетплейс — простота и поддерживаемость важнее «масштабируемости на миллионы».

Мой технический уровень: уверенный пользователь — git, терминал, деплой знаю; код самостоятельно не пишу. Значит: стек должен быть популярным (много примеров), архитектура — простой и читаемой, шаги Claude Code — небольшими и обратимыми.

---

2. Роли пользователей

• Ученик — регистрируется сам или добавляется админом, проходит курсы, сдаёт ДЗ, оставляет комментарии.
• Куратор — проверяет ДЗ, оставляет обратную связь, видит прогресс группы.
• Админ (я) — всё вышеперечисленное + создание/редактирование курсов, управление пользователями, аналитика, импорт/экспорт.

---

3. Функционал MVP (обязательно)

3.1. Курсы и контент

• Курс → модули → уроки. До 10 курсов.
• Типы контента в уроке: видео Kinescope (через iframe-embed с защитой), форматированный текст, PDF/файлы для скачивания, картинки.
• Редактор уроков в админке: WYSIWYG с базовым форматированием (заголовки, списки, цитаты, код, ссылки, картинки).
• Импорт урока из .md-файла — желательно (frontmatter → метаданные урока, тело → контент). Это критично, потому что я работаю в Obsidian.
• Водяные знаки на загружаемых картинках и PDF — если просто, добавляем; иначе в бэклог.

3.2. Kinescope-интеграция

• Хранение видео — только Kinescope.
• Бесшовная вставка: в админке вставляю ID видео или ссылку, во фронте отрисовывается плеер.
• Защита от скачивания обеспечивается самим Kinescope (signed URLs / referrer-проверка).
• На этапе планирования: Claude Code должен изучить актуальное API Kinescope и предложить, как удобнее всего его подключить.

3.3. Прохождение и прогресс

• Линейное прохождение: следующий урок открывается только после завершения предыдущего.
• Урок засчитывается как пройденный по совокупности: просмотр видео + (если есть) сданный тест + (если есть) отправленное ДЗ.
• ДЗ принимается автоматически при отправке — ученик сразу идёт дальше. Куратор оставляет обратную связь асинхронно, она прилетает ученику уведомлением и появляется в карточке урока.
• Прогресс-бар по курсу и по модулю в личном кабинете.

3.4. Тесты и квизы

• Типы вопросов: одиночный выбор, множественный выбор, короткий текстовый ответ.
• Авто-проверка, показ правильных ответов после прохождения (настраивается).

3.5. Домашние задания

• Формат отправки: текст + прикреплённые файлы.
• Комментарии куратора к ДЗ — обязательны.
• История переписки по конкретному ДЗ.

3.6. Комментарии под уроками

• Тред обсуждения у каждого урока. Видны всем ученикам этого курса. Модерация — куратор/админ может удалять.

3.7. Уведомления (email)

• Учеников: регистрация, новый комментарий куратора к ДЗ, ответ в обсуждении урока.
• Админа/куратора: новое ДЗ на проверку, новый комментарий в обсуждении, регистрация нового ученика.
• Telegram-бот для уведомлений админа/куратора (новое ДЗ, ошибки) — добавить во вторую итерацию MVP.

3.8. Регистрация и доступы

• Самостоятельная регистрация по email + подтверждение.
• Админ может вручную создать аккаунт и выдать доступ к курсу.
• Доступ к курсу — на уровне «есть/нет» (продажи на платформе не делаем).

3.9. Миграция с emdesell

• Перенос базы пользователей (email, имя, прогресс если возможно) — критично.
• Перенос контента курсов (тексты уроков, ссылки на видео Kinescope, файлы) — критично.
• На этапе планирования: Claude Code должен изучить документацию emdesell и предложить стратегию (API / экспорт CSV / парсинг HTML).

---

4. В бэклог (после MVP)

• Геймификация (баллы, бейджи, рейтинги).
• Сертификаты по окончании курса.
• Промокоды, рассрочки, продажи через платформу (место в архитектуре заложить, реализацию — потом).
• Дедлайны и расписания.
• Мобильное приложение.

---

5. Технические требования и предпочтения

• Хостинг: собственный сервер в Hetzner.

• Локальная разработка: возможна, кроме видео (Kinescope доступен только онлайн).

• Дизайн: тёплый и дружелюбный, подходящий для образования. Не корпоративный, не «тёмный энтерпрайз». Качественная типографика, читабельность важнее «вау-эффектов».

• Язык интерфейса: русский (i18n не нужен).

• Стек: не зафиксирован — Claude Code должен предложить на выбор 2–3 варианта с обоснованием. Критерии выбора:

  1. Простота поддержки в одиночку.
  2. Большое сообщество и много примеров (чтобы Claude Code хорошо его знал).
  3. Удобный деплой на VPS (Docker Compose как базовый сценарий).
  4. Хороший Markdown-рендеринг и возможность подключить TipTap/аналог для WYSIWYG.

  Мои ожидания (но я открыт к альтернативам): что-то вроде Next.js + PostgreSQL + Prisma + NextAuth + Tailwind, либо Laravel + Inertia + Vue, либо Django + HTMX.

---

6. Интеграции

• Kinescope — обязательно, MVP.
• SMTP / email-сервис (Postmark, Resend, или свой SMTP) — обязательно, MVP.
• Telegram-бот — для уведомлений, вторая итерация MVP.
• Аналитика — Yandex.Metrika и/или Plausible, в конце MVP.
• Платежи — место в архитектуре заложить, реализацию отложить.

---

7. Что НЕ нужно делать

• Продажи, корзина, промокоды, рассрочки.
• Многоязычность.
• Мобильное приложение.
• Сложные ролевые иерархии помимо трёх ролей.
• Дедлайны и жёсткие расписания.

---

8. Как я хочу работать с Claude Code

• Маленькими шагами, с git-коммитами после каждого осмысленного куска.
• В начале каждой большой фичи — короткий план в чате, потом реализация.
• README и комментарии в коде — на русском или английском, но последовательно.
• Перед любой миграцией БД или удалением файлов — спросить меня.
• Все секреты — только в .env, никаких токенов в коде.

---

9. Первые шаги для Claude Code (план первой сессии)

1. Изучить документацию Kinescope API (особенно: вставка плеера, защита от скачивания, получение метаданных видео).
2. Изучить документацию emdesell (https://docs.emdesell.ru/) — есть ли API для экспорта пользователей и контента; если нет — предложить альтернативы.
3. Предложить 2–3 варианта стека с плюсами/минусами под мои критерии.
4. После выбора стека вместе со мной — создать CLAUDE.md в корне проекта со следующими разделами:
   • Стек и версии.
   • Структура каталогов.
   • Команды (dev, build, test, lint, db migrate).
   • Правила: маленькие коммиты, не трогать миграции без подтверждения, секреты только в env, русские названия только в UI-строках.
   • Чек-лист перед коммитом.
5. Инициализировать репозиторий, базовый каркас, Docker Compose с приложением + PostgreSQL, минимальную страницу «hello world» с auth.
6. Создать ROADMAP.md с разбивкой на этапы:
   • Этап 0: каркас, auth, роли.
   • Этап 1: курсы → модули → уроки (CRUD в админке).
   • Этап 2: интеграция Kinescope, рендер уроков для ученика.
   • Этап 3: прогресс и линейное открытие уроков.
   • Этап 4: тесты и квизы.
   • Этап 5: ДЗ и комментарии куратора.
   • Этап 6: обсуждения под уроками.
   • Этап 7: email-уведомления.
   • Этап 8: импорт .md, водяные знаки.
   • Этап 9: миграция с emdesell.
   • Этап 10: Telegram-бот, аналитика.
   • Этап 11: деплой на Hetzner.

---

10. Критерий «MVP готов»

Я могу: создать курс из админки, добавить модули и уроки с видео Kinescope и текстами, импортировать ученика из старой LMS, дать ему доступ, он зарегистрируется, пройдёт первый урок, сдаст тест, отправит ДЗ, получит автоматический допуск к следующему уроку, а позже — комментарий куратора по почте.

Когда этот сценарий работает end-to-end на production-сервере в Hetzner — MVP считается готовым.