# 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 | 7.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 ``` --- ## Команды ```bash # Разработка 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** (токен: в `.env.local` не хранить, спросить у пользователя) - **После завершения каждого этапа из 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 `, не копировать вручную - Не добавлять абстракции "на будущее" — только то, что нужно для текущего этапа - Server Actions — использовать для форм и мутаций (auth, прогресс, ДЗ) ### Маршруты и роли - Защита маршрутов — через `middleware.ts` (Better Auth), не в каждом компоненте отдельно - Роли: `student`, `curator`, `admin` — проверять через `auth()` или `authClient.useSession()` - Admin-маршруты (`/admin/*`) доступны только роли `admin` - Curator-маршруты (`/curator/*`) доступны ролям `curator` и `admin` --- ## Переменные окружения (`.env.example`) ```env # База данных 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) ```