Константин Лебединский
127 lines
6.6 KiB
Markdown
127 lines
6.6 KiB
Markdown
# Edu Helper
|
||
|
||
Веб-приложение для обучения с ИИ: чат, вопросы, учебники, тесты, «Зал» с фотографиями по датам. Два типа пользователей — **наставник** и **ученик** (роли и связка наставник ↔ ученик задаются в БД).
|
||
|
||
## Стек
|
||
|
||
- **Frontend:** React 19, Vite, TypeScript, Tailwind CSS
|
||
- **Backend:** Node.js, Express, Prisma ORM
|
||
- **БД:** PostgreSQL 16
|
||
- **ИИ:** DeepSeek API (ключ в настройках или переменной окружения)
|
||
- **Деплой:** Docker Compose (один контейнер с API + статикой фронта, отдельно Postgres)
|
||
|
||
## Требования
|
||
|
||
- [Docker](https://docs.docker.com/get-docker/) и Docker Compose (для продакшен-сборки)
|
||
- или **Node.js 22+** и локальный PostgreSQL (для разработки без Docker)
|
||
|
||
## Быстрый старт (Docker)
|
||
|
||
1. Склонируйте репозиторий и перейдите в каталог проекта.
|
||
|
||
2. Создайте файл `.env` в **корне** репозитория (можно скопировать шаблон):
|
||
|
||
```bash
|
||
cp .env.docker.example .env
|
||
```
|
||
|
||
3. Отредактируйте `.env`:
|
||
- задайте **`JWT_SECRET`** — длинная случайная строка (не короткий пароль);
|
||
- задайте **`SEED_TUTOR_PASSWORD`** и **`SEED_STUDENT_PASSWORD`** — пароли первых пользователей (создаются только при пустой таблице `User`);
|
||
- при необходимости укажите **`DEEPSEEK_API_KEY`**;
|
||
- для работы по **HTTPS** за прокси выставьте **`COOKIE_SECURE=true`**; для обычного **http://localhost** оставьте **`COOKIE_SECURE=false`**, иначе cookie с сессией не установится.
|
||
|
||
4. Запуск:
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
5. Откройте в браузере: **http://localhost:3107** (или порт из `APP_PORT` в `.env`).
|
||
|
||
6. Проверка API:
|
||
|
||
```bash
|
||
curl http://localhost:3107/api/health
|
||
```
|
||
|
||
При первом старте контейнер приложения выполняет `prisma migrate deploy` и сид пользователей (если пользователей ещё нет).
|
||
|
||
### Windows: `exec /docker-entrypoint.sh: no such file or directory`
|
||
|
||
Обычно это **CRLF** в `docker-entrypoint.sh` после клонирования на Windows. В репозитории задан **`.gitattributes`** (для `*.sh` — только LF). Обновите репозиторий и пересоберите образ без кэша:
|
||
|
||
```bash
|
||
git pull
|
||
docker compose build --no-cache app
|
||
docker compose up -d
|
||
```
|
||
|
||
Если проблема осталась: `git config core.autocrlf false`, затем `git add --renormalize .` и зафиксируйте изменения или переклонируйте репозиторий; либо в редакторе сохраните `docker-entrypoint.sh` с окончаниями строк **LF (Unix)**. При сборке образа символы `\r` в скрипте также удаляются автоматически.
|
||
|
||
### Тома данных
|
||
|
||
- **`pgdata`** — данные PostgreSQL. Пароль пользователя БД задаётся в **`POSTGRES_PASSWORD`** только при **первом** создании тома. Если сменить пароль в `.env` позже, сам PostgreSQL **не** пересоздаст пароль автоматически — приложение не подключится (ошибка Prisma `P1000`). Варианты: вернуть в `.env` старый пароль, либо сменить пароль вручную в Postgres, либо **один раз** пересоздать том (данные БД пропадут):
|
||
|
||
```bash
|
||
docker compose down -v
|
||
docker compose up -d --build
|
||
```
|
||
|
||
- **`uploads`** — загруженные файлы «Зала».
|
||
|
||
## Локальная разработка (без Docker)
|
||
|
||
1. Поднимите PostgreSQL и создайте базу (например `edu_helper`).
|
||
|
||
2. В каталоге **`backend`** создайте `.env` с `DATABASE_URL` и остальными переменными по аналогии с корневым `.env.docker.example`.
|
||
|
||
3. Установка и миграции:
|
||
|
||
```bash
|
||
cd backend && npm ci && npx prisma migrate deploy
|
||
```
|
||
|
||
4. Запуск бэкенда (по умолчанию порт **3001**):
|
||
|
||
```bash
|
||
npm run dev
|
||
```
|
||
|
||
5. В другом терминале — фронт:
|
||
|
||
```bash
|
||
cd frontend && npm ci && npm run dev
|
||
```
|
||
|
||
Vite откроется на **http://localhost:5173**; запросы к `/api` проксируются на бэкенд (см. `frontend/vite.config.ts`).
|
||
|
||
Корневой скрипт **`npm run dev`** (из корня репозитория, после `npm install` в корне) поднимает backend и frontend одновременно через `concurrently`.
|
||
|
||
## Структура репозитория
|
||
|
||
| Путь | Назначение |
|
||
|------|------------|
|
||
| `frontend/` | SPA (React + Vite) |
|
||
| `backend/` | API, Prisma-схема и миграции |
|
||
| `Dockerfile` | Сборка фронта и бэка, один образ Node |
|
||
| `docker-compose.yml` | Сервисы `app` и `db`, тома `pgdata` и `uploads` |
|
||
| `docker-entrypoint.sh` | Миграции Prisma и сид перед стартом Node |
|
||
| `.env.docker.example` | Шаблон переменных для Docker |
|
||
|
||
Файл **`.env`** в git не коммитится (см. `.gitignore`).
|
||
|
||
## Переменные окружения (кратко)
|
||
|
||
| Переменная | Описание |
|
||
|------------|----------|
|
||
| `POSTGRES_*` | Пользователь, пароль и имя БД для контейнера Postgres |
|
||
| `DATABASE_URL` | Строка подключения Prisma (в Docker задаётся из `POSTGRES_*`) |
|
||
| `JWT_SECRET` | Секрет подписи JWT (обязательно задать) |
|
||
| `SEED_*_USERNAME` / `SEED_*_PASSWORD` | Логины и пароли для первичного сида |
|
||
| `DEEPSEEK_API_KEY` | Опционально: ключ API по умолчанию |
|
||
| `COOKIE_SECURE` | `true` только при HTTPS |
|
||
| `APP_PORT` | Проброс порта хоста на контейнер приложения (по умолчанию 3107) |
|
||
|
||
|