lms-sb/CLAUDE.md

CLAUDE.md — LMS Second Brain

Читай AGENTS.md перед тем как писать любой Next.js код — версия отличается от обучающих данных.

Стек и версии

Технология	Версия	Назначение
Next.js	16.2.2 (App Router)	Full-stack фреймворк
Node.js	20 LTS	Runtime
TypeScript	5.x	Язык
React	19	UI
PostgreSQL	16	База данных
Prisma	6.x	ORM + миграции
Better Auth	latest	Аутентификация и сессии
Tailwind CSS	4.x (CSS-based config)	Стили (нет tailwind.config.ts)
shadcn/ui	latest	UI-компоненты
TipTap	2.x	WYSIWYG-редактор уроков
@kinescope/react-kinescope-player	latest	Видеоплеер
Resend	latest	Email-уведомления
AWS SDK (S3)	3.x	Hetzner Object Storage
Zod	3.x	Валидация данных
Docker Compose	2.x	Локальная разработка и деплой

Важно по Tailwind v4: конфиг — только в CSS через @import "tailwindcss" и @theme. Нет tailwind.config.ts. Кастомизация — через CSS переменные в globals.css.

Важно по Better Auth: не NextAuth. Сессии — cookie-based. Роли через плагин admin. Подробнее: https://www.better-auth.com/docs

---

Структура каталогов

lms-system/
├── src/
│   ├── app/                        # Next.js App Router
│   │   ├── (auth)/                 # Вход, регистрация, подтверждение email
│   │   │   ├── login/
│   │   │   ├── register/
│   │   │   └── verify-email/
│   │   ├── (student)/              # Личный кабинет ученика
│   │   │   ├── dashboard/
│   │   │   ├── courses/[slug]/
│   │   │   └── courses/[slug]/lessons/[lessonId]/
│   │   ├── curator/                # Панель куратора
│   │   │   ├── dashboard/
│   │   │   └── homework/
│   │   ├── admin/                  # Панель администратора
│   │   │   ├── courses/
│   │   │   ├── users/
│   │   │   └── settings/
│   │   └── api/                    # API-маршруты
│   │       ├── auth/               # Better Auth handler
│   │       ├── courses/
│   │       ├── lessons/
│   │       ├── progress/
│   │       ├── homework/
│   │       └── upload/
│   ├── components/
│   │   ├── ui/                     # shadcn/ui (не редактировать вручную)
│   │   ├── editor/                 # TipTap WYSIWYG
│   │   ├── player/                 # Kinescope Player wrapper
│   │   ├── course/                 # Компоненты курса
│   │   └── layout/                 # Header, Sidebar, Footer
│   ├── lib/
│   │   ├── auth.ts                 # Better Auth config (сервер)
│   │   ├── auth-client.ts          # Better Auth client (браузер)
│   │   ├── prisma.ts               # Prisma singleton client
│   │   ├── s3.ts                   # Hetzner Object Storage клиент
│   │   ├── email.ts                # Resend email helpers
│   │   └── utils.ts                # cn() и прочие утилиты
│   ├── types/
│   │   └── index.ts                # Общие TypeScript-типы
│   └── middleware.ts               # Auth middleware (защита маршрутов)
├── prisma/
│   ├── schema.prisma               # Схема БД
│   ├── seed.ts                     # Seed-скрипт
│   └── migrations/                 # НИКОГДА не редактировать вручную
├── public/
│   └── images/
├── docker-compose.yml              # Локальная разработка
├── docker-compose.prod.yml         # Production
├── Dockerfile
├── .env.example                    # Шаблон переменных (без секретов)
├── .env.local                      # Локальные секреты (в .gitignore)
├── CLAUDE.md
├── ROADMAP.md
└── PROJECT_BRIEF.md

---

Команды

# Разработка
npm run dev              # Запустить dev-сервер (localhost:3000)
docker compose up -d     # Поднять PostgreSQL локально

# Сборка и проверка
npm run build            # Production build
npm run lint             # ESLint
npm run type-check       # TypeScript без сборки (tsc --noEmit)

# База данных (Prisma)
npx prisma migrate dev --name <название>   # Создать и применить миграцию
npx prisma migrate deploy                  # Применить миграции в production
npx prisma studio                          # GUI для просмотра БД
npx prisma generate                        # Пересоздать клиент после изменений schema
npx prisma db seed                         # Запустить seed-скрипт

# Docker (production)
docker compose -f docker-compose.prod.yml up -d --build
docker compose -f docker-compose.prod.yml logs -f app

---

Правила работы

Деплой и окружение

• Production-домен: school.second-brain.ru
• Git-сервер: Gitea — https://git.second-brain.ru/admins/lms-sb
• После завершения каждого этапа из ROADMAP.md — делать git push в Gitea

Коммиты

• Один коммит = одна логически завершённая единица работы (маршрут, компонент, миграция)
• Сообщения коммитов — на английском, в повелительном наклонении: Add lesson progress tracking, Fix auth redirect
• Перед коммитом всегда запускать npm run lint && npm run type-check

Миграции базы данных

• НИКОГДА не редактировать файлы в prisma/migrations/ вручную
• ВСЕГДА спрашивать пользователя перед созданием миграции, меняющей или удаляющей существующие поля
• Называть миграции по-английски, snake_case: add_lesson_progress, add_user_roles
• Перед prisma migrate deploy на production — делать бэкап БД

Файлы и контент

• Загружаемые файлы (ДЗ, PDF) — только через Hetzner Object Storage, никогда на диск VPS
• Секреты (API-ключи, токены, строки подключения) — только в .env.local, в коде запрещено
• .env.example всегда обновлять при добавлении новых переменных (без реальных значений)

Код

• UI-строки (заголовки, кнопки, сообщения) — на русском
• Имена переменных, функций, файлов, комментарии в коде — на английском
• Компоненты shadcn/ui — добавлять через npx shadcn@latest add <component>, не копировать вручную
• Не добавлять абстракции "на будущее" — только то, что нужно для текущего этапа
• Server Actions — использовать для форм и мутаций (auth, прогресс, ДЗ)

Маршруты и роли

• Защита маршрутов — через middleware.ts (Better Auth), не в каждом компоненте отдельно
• Роли: student, curator, admin — проверять через auth() или authClient.useSession()
• Admin-маршруты (/admin/*) доступны только роли admin
• Curator-маршруты (/curator/*) доступны ролям curator и admin

---

Переменные окружения (.env.example)

# База данных
DATABASE_URL="postgresql://lms_user:password@localhost:5432/lms_db"

# Better Auth
BETTER_AUTH_SECRET="generate-with-openssl-rand-base64-32"
BETTER_AUTH_URL="http://localhost:3000"

# Email (Resend)
RESEND_API_KEY=""
EMAIL_FROM="noreply@school.second-brain.ru"

# Hetzner Object Storage (S3-совместимый)
S3_ENDPOINT="https://fsn1.your-objectstorage.com"
S3_BUCKET="lms-uploads"
S3_ACCESS_KEY=""
S3_SECRET_KEY=""
S3_REGION="eu-central"

# Kinescope (добавить при получении платного плана)
# KINESCOPE_API_KEY=""

---

Чек-лист перед каждым коммитом

• npm run lint — нет ошибок ESLint
• npm run type-check — нет ошибок TypeScript
• Новые .env переменные добавлены в .env.example (без значений)
• Миграция БД одобрена пользователем (если есть)
• Нет console.log в production-коде (только console.error для реальных ошибок)
• Нет захардкоженных секретов, URL-ов, ID

---

Модель данных (основные сущности)

User (id, email, name, role, emailVerified) — управляется Better Auth
Session (id, userId, expiresAt, ...) — управляется Better Auth
Course (id, slug, title, description, coverImage, published)
Module (id, courseId, title, order)
Lesson (id, moduleId, title, order, content, kinescopeId, published)
CourseEnrollment (userId, courseId, enrolledAt)
LessonProgress (userId, lessonId, completedAt)
Quiz (id, lessonId)
QuizQuestion (id, quizId, text, type)
QuizOption (id, questionId, text, isCorrect)
QuizAttempt (id, userId, quizId, score, completedAt)
Homework (id, lessonId, description)
HomeworkSubmission (id, homeworkId, userId, text, files[], submittedAt)
HomeworkFeedback (id, submissionId, curatorId, text, createdAt)
LessonComment (id, lessonId, userId, text, createdAt)