From c9975d2fc020c4bcc35ed60897d07d073689c6f7 Mon Sep 17 00:00:00 2001 From: Muhammadcell Date: Sat, 6 Jun 2026 14:32:23 +0500 Subject: [PATCH] docs(api): document backend data ownership The backend data guide was too short to explain package boundaries or schema ownership. The updated version gives contributors a clearer path for safe API and Prisma changes. Co-Authored-By: Claude Opus 4.8 --- docs/api/backend-data.md | 96 +++++++++++++++++++--------------------- 1 file changed, 46 insertions(+), 50 deletions(-) diff --git a/docs/api/backend-data.md b/docs/api/backend-data.md index 2849766..c13f2f8 100644 --- a/docs/api/backend-data.md +++ b/docs/api/backend-data.md @@ -1,69 +1,65 @@ -API Backend And Data +# API Backend And Data -Этот документ объясняет root API-блок. +Этот документ описывает root API-блок Metrix: `packages/api`, общую Prisma +схему в `prisma/schema.prisma` и правила работы с данными, которые относятся к +web/API слою. Telegram microservices runtime из `apps/bot` описан отдельно в +`docs/telegram-bot/`. -Важно +## Роль `packages/api` -Он описывает packages/api и root prisma/schema.prisma. -Он не описывает весь Telegram bot microservices runtime из apps/bot. +`packages/api` - переиспользуемый backend пакет. Его можно подключать к Next.js +route handlers, отдельному Node API или тестовым harness-ам без копирования +бизнес-логики. -Зачем нужен packages/api +Пакет держит три слоя: -packages/api — это reusable backend-блок. -Его можно подключить к Next route handlers или отдельному Node API. +- `src/contracts` - типы запросов, ответов и публичных DTO. +- `src/modules/*` - use cases и мапперы конкретных доменных областей. +- `src/shared/*` - auth, validation и общие инфраструктурные helper-ы. -Что внутри +## Данные и владение -- src/contracts — типы запросов и ответов. -- src/database/prisma-client.ts — общий PrismaClient. -- src/modules/bookings — создание и проверка брони. -- src/modules/resources — преобразование локаций, ресурсов и слотов. -- src/modules/admin — validation для админских изменений. -- src/shared/auth — JWT, session, password hash, auth guard. -- src/shared/validation — простые validators. +Root Prisma schema находится в `prisma/schema.prisma`. Она описывает данные, +которые нужны web/API слою и общим интеграциям: -Root Prisma schema +- `User` и `Session` - пользовательские аккаунты, роли и refresh sessions. +- `Location`, `Resource`, `Slot` - каталог локаций, ресурсов и доступных слотов. +- `Booking` - подтвержденная бронь и ее состояние. +- `CalendarConnection`, `CalendarEvent` - подключенные календари и синхронизация. -Файл: +Владелец модели должен быть понятен до изменения схемы. Если модель используется +и root API, и bot microservices, изменение сначала согласуется через contract или +миграцию, а затем раскатывается в оба runtime. -prisma/schema.prisma +## Booking safety -Главные модели: +Создание брони должно оставаться транзакционным: -- User — пользователь или админ. -- Session — refresh-сессия. -- Location — офисная локация. -- Resource — ресурс внутри локации. -- Slot — слот времени. -- Booking — бронь. -- CalendarConnection — подключение календаря. -- CalendarEvent — событие календаря. +- проверить существование `Resource`; +- проверить `Slot` или явный интервал `startsAt`/`endsAt`; +- отфильтровать активные брони, которые пересекаются с новым интервалом; +- создать запись в транзакции, чтобы параллельные запросы не расходились. -Auth +Любая новая ветка логики бронирования должна явно отвечать, что происходит при +повторном запросе, конфликте слота и отмене брони. -JWT используется для обычного API-слоя. -Пароли хешируются через pbkdf2. -Refresh sessions лежат в таблице Session. +## Auth -Booking safety +JWT используется для API-запросов. Пароли хешируются через `pbkdf2`, а refresh +sessions хранятся в таблице `Session`. Код, который читает user identity, не +должен доверять client-provided id без проверки токена или server-side session. -Создание брони проверяет: +## Команды -- существует ли resource; -- существует ли slot или переданы startsAt/endsAt; -- не пересекается ли новая бронь с активной бронью; -- можно ли создать запись в транзакции. +- `npm run prisma:generate` - сгенерировать Prisma Client. +- `npm run prisma:validate` - проверить схему без подключения к production DB. +- `npm run prisma:migrate` - применить локальную миграцию. +- `npm run prisma:seed` - заполнить локальные данные. -Команды +## Чеклист расширения -npm run prisma:generate — сгенерировать Prisma Client. -npm run prisma:migrate — применить миграции. -npm run prisma:seed — заполнить локальные данные. - -Как расширять - -1. Сначала обновить contract. -2. Потом validator. -3. Потом use case или repository. -4. Потом mapper. -5. Потом тесты. +1. Обновить contract или DTO. +2. Добавить validation для входных данных. +3. Обновить use case и repository/Prisma запрос. +4. Добавить mapper для ответа наружу. +5. Покрыть happy path, conflict path и invalid input тестами.