# Локальное окружение KORZILLA.Admin (Laragon)

```
korzilla-admin/
├── backend/    # git: korzilla-ru/korzilla-admin-backend  (NestJS 11 + Prisma 7 + PostgreSQL)
├── frontend/   # git: korzilla-ru/korzilla-admin-frontend (Next.js 16 + React 19)
├── dev/        # локальные скрипты (не в git)
└── .claude/launch.json
```

## Сервисы

| Что            | Адрес                         | Откуда                                     |
| -------------- | ----------------------------- | ------------------------------------------ |
| Фронтенд       | http://localhost:3000         | `dev\frontend.cmd`                         |
| API            | http://localhost:4000/api     | `dev\backend.cmd`                          |
| Push-заглушка  | http://localhost:4010         | `node dev\push-mock.js` (логирует запросы) |
| PostgreSQL 17  | 127.0.0.1:5432                | Laragon; БД `korzilla_admin`, роль `korzilla`/`korzilla` |
| Mailpit        | http://localhost:8025         | Laragon; SMTP 127.0.0.1:1025 — сюда приходят OTP-коды |

Node.js берётся из `D:\laragon\bin\nodejs\node-v22` (в системном PATH его нет),
pnpm — через corepack: `corepack pnpm@10.26.2 ...`.

## Первый запуск с нуля

```bat
set PATH=D:\laragon\bin\nodejs\node-v22;%PATH%
cd backend
corepack pnpm@10.26.2 install
corepack pnpm@10.26.2 prisma generate
corepack pnpm@10.26.2 prisma migrate deploy
cd ..\frontend
corepack pnpm@10.26.2 install
```

`.env` лежат в `backend/.env` и `frontend/.env` (в git не попадают).

## Как проверить синхронизацию сайта без реального сайта

1. В кабинете добавить сайт → получить 6-значный код.
2. `POST /api/external/sites/sync` `{ "domain": "...", "otp": "..." }` → в ответе `token`.
3. `POST /api/external/notifications` с `Authorization: Bearer <token>` и
   `{ "title", "body", "description?", "type": "SITE_NEW_ORDER" | "SITE_NEW_FORM" | "SITE_CUSTOM" | ... }`.

В Git Bash отправляйте JSON с кириллицей через `--data-binary @file.json` (UTF-8), иначе curl испортит кодировку.

## Как устроен прод (проверено по SSH 2026-10-21, `ssh korzilla-prod`)

VPS Timeweb `109.73.193.24`, на нём же много других проектов Корзиллы.

| Что       | Как запущено                                                                 |
| --------- | ---------------------------------------------------------------------------- |
| nginx     | HestiaCP, домен `admin.korzilla.ru` (пользователь `adminapp`, прокси-шаблон `nodejs-admin`): `/api` → `127.0.0.1:4000`, `/` → `127.0.0.1:3000`. С 2026-10-22 `SSL_FORCE=yes`, но `nginx.forcessl.conf` правлен вручную: 301 на https для всего, **кроме `/api`** (сайты могут слать POST по http). `v-add-web-domain-ssl-force` перезапишет его на редирект всего |
| Бэкенд    | systemd `korzilla-admin-backend`, root, Node 20.19.5 (nvm), `node dist/src/main` в `/home/adminapp/web/admin.korzilla.ru/apps/backend`. Миграции при старте **не** запускаются |
| Фронтенд  | Docker-контейнер `frontend` (образ собран 2026-06-01 GitLab-раннером из `/builds/...`, этой папки уже нет). Порт 3000 опубликован на 0.0.0.0 |
| БД        | PostgreSQL на `127.0.0.1:5432`, `adminapp_base_db`; извне закрыта, есть Adminer на visor.korzilla.ru |

- Копия бэкенда на сервере чистая, HEAD = `ae7fc00` (= GitHub `main` без README). `origin` всё ещё
  указывает на `gitlab.com/korzilla/admin-backend` и без логина не тянется; GitHub-репозитории приватные.
- С 2026-10-22 `origin` бэкенда — GitHub (через deploy key, алиас `github-korzilla-admin-backend`),
  старый GitLab оставлен как remote `gitlab`. GitLab-ветки `ddd` (+9 коммитов) и `new-arch` (+2),
  которых нет в GitHub, закреплены локальными ветками `gitlab-ddd`, `gitlab-new-arch`.
- Фронт склонирован в `apps/frontend` (deploy key, алиас `github-korzilla-admin-frontend`), `.env` там же.
- pnpm 10.26.2 и Prisma CLI на сервере есть. Postgres и pg_dump — 14.24.
- Диск `/` заполнен на 94% (свободно ~6 ГБ) — сборка фронта требует ≥4 ГБ.

## Выкладка

Исходники скриптов — `dev/deploy/`, на сервере — `/root/deploy/korzilla-admin/`
(обновлять: `scp dev/deploy/deploy-*.sh korzilla-prod:/root/deploy/korzilla-admin/`).

```bash
ssh korzilla-prod DRY_RUN=1 /root/deploy/korzilla-admin/deploy-backend.sh    # что будет выложено
ssh korzilla-prod /root/deploy/korzilla-admin/deploy-backend.sh              # origin/main
ssh korzilla-prod /root/deploy/korzilla-admin/deploy-frontend.sh             # origin/main
ssh korzilla-prod FORCE=1 /root/deploy/korzilla-admin/deploy-frontend.sh     # пересобрать тот же коммит
```

- **backend**: бэкап БД (`/root/backups/korzilla-admin`, 10 последних) → ff-merge `origin/main` →
  `pnpm install` (если менялся lock) → `prisma generate` → baseline (один раз, только если схема БД
  совпадает со `schema.prisma`) → `migrate deploy` → `pnpm build` → `systemctl restart` → проверка
  `GET /api/sessions` = 401. При ошибке — откат кода/dist/node_modules и рестарт; миграции не откатываются.
- **frontend**: ff-merge → текущий образ сохраняется как `:rollback` → `docker compose -p
  korzilla-admin-frontend build && up -d` → проверка `/` и `/auth/signin` = 200. При ошибке — откат на `:rollback`.

## Известные особенности

- **Расхождение миграций (исправлено в ветке `fix/user-grants-migration`).** В `main` есть только
  миграция `init`, без `user_grants`, `grant_sites`, `GrantRole` и `sites.ipv4 NULL`. Миграция
  `20261021120000_add_user_grants` их добавляет и написана идемпотентно (безопасна там, где таблицы
  уже созданы через `db push`). Проверка, что БД совпадает со схемой (exit 0 = совпадает):
  `prisma migrate diff --from-config-datasource --to-schema prisma/schema.prisma --exit-code`.
- **Прод: baseline сделан 2026-10-22** при выкладке `c2b3d40`. Обе миграции записаны в
  `_prisma_migrations`, дальше `migrate deploy` работает штатно. До этого прод-БД была собрана через
  `db push` без истории миграций (схема при этом 1:1 совпадала со `schema.prisma`).
- **`COOKIE_SECURE` / `SMTP_SECURE`** парсятся как `Boolean(string)` → `"false"` даёт `true`.
  Для `false` оставляйте значение пустым.
- Ссылка в push-уведомлениях захардкожена на `https://admin.korzilla.ru/...`.
