admins
80ca4b2d9d
- Next.js 16.2.2 + React 19 + TypeScript + Tailwind v4 - Better Auth with email/password and role system (student/curator/admin) - Prisma 7 schema: User, Session, Account, Verification + full LMS model - Role-based dashboards: student /dashboard, curator /curator/dashboard, admin /admin/dashboard - Auth pages: login, register, verify-email - Better Auth API route handler - Middleware for route protection - Docker Compose with PostgreSQL 16 - Seed script with test users (admin/curator/student) - CLAUDE.md and ROADMAP.md project documentation Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
166 lines
14 KiB
Markdown
166 lines
14 KiB
Markdown
# LMS-проект: стартовый бриф для Claude Code
|
||
|
||
> Этот документ — отправная точка проекта. Положи его в корень репозитория как `PROJECT_BRIEF.md`. В первой сессии Claude Code попроси: **«Прочитай PROJECT_BRIEF.md, задай мне уточняющие вопросы по архитектуре, затем предложи план работ по этапам и создай CLAUDE.md с ключевыми правилами проекта»**.
|
||
|
||
---
|
||
|
||
## 1. Контекст и цель
|
||
|
||
Я — автор образовательных курсов (PKM, Obsidian). Сейчас размещаюсь на сторонней LMS-платформе ([emdesell.ru](https://docs.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/](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 считается готовым.
|