API и server routes

Защищённые endpoints размещаются в server/api/ и используют getCurrentUserId(event) или эквивалентный server helper. Body и query валидируются через Zod до Prisma-запроса.

Контракт

Используйте суффиксы .get.ts, .post.ts, .patch.ts, .delete.ts. Для списков возвращайте стабильную структуру data и pagination, если результат может быть большим. Ошибки должны иметь корректный HTTP-статус и безопасное сообщение.

Безопасность

Нельзя принимать от клиента пользователя, tenant или instance как источник прав. Идентификатор из URL проверяется на доступ текущего пользователя. Prisma-запросы не должны возвращать секреты и лишние персональные данные.

Аутентификация

Сессия хранится в HTTP-only cookie и проверяется через requireUserSession(event). Идентификатор пользователя берётся из server session через getCurrentUserId(event). Не принимай userId, tenantId, instance identifier или роль из body как источник доверия.

Для отсутствующей сессии возвращай 401, для недостаточных прав 403, для недоступной записи 404 или безопасный эквивалент по контракту.

Организация endpoints

Используй суффиксы .get.ts, .post.ts, .patch.ts, .delete.ts. Сложную бизнес-логику выноси в server/services/ или server/utils/, чтобы endpoint оставался orchestration-слоем.

server/api/crm/entity/
├── index.get.ts
├── index.post.ts
└── [id].patch.ts

Для списков используй select, pagination и стабильную сортировку. Не допускай N+1; независимые запросы выполняй через Promise.all, атомарные изменения через $transaction.

AI и MCP используют те же auth/resource checks, что и обычный API. Write-команда сначала возвращает план, а выполняется только после явного подтверждения и записи аудита.