CRUD без боли: форма запроса как граница безопасности поверх Prisma

• Невалидированный ввод попадает в Prisma. prisma.listing.create({ data: req.body }) — и клиент фактически управляет всем содержимым запроса, включая agencyId, verifiedAt, commissionRate.
  
• Слишком широкая форма запроса. Клиент через include доходит до agent.passwordHash или через where фильтрует по internalNotes.
  
• Утечки между агентствами. findFirst({ where: { id:req.params.id} }) без условия по агентству - и агент видит объявления чужой компании. В терминах SaaS это утечка между тенантами; в терминах предметной области - между агентствами. Дальше я использую «агентство» для домена и «тенант» для архитектуры.

• валидирует тело запроса (через сгенерированные из Prisma Zod-схемы),
  
• ограничивает форму Prisma-запроса (списком разрешённых полей в where/select/include/orderBy),
  
• задаёт проекцию по умолчанию, если клиент select/include не прислал,
  
• подставляет принудительные значения (тенант, владелец, флаги видимости).

{
  where: {
    city: { equals: true },
    type: { in: true },
    priceMin: { gte: true },
    priceMax: { lte: true },
    isPublished: { equals: force(true) },
    deletedAt: { equals: force(null) },
  },
  orderBy: { createdAt: true, priceMin: true },
  take: { default: 20, max: 50 },
  select: listingPublicSelect,
}

headers: { 'x-api-variant': window.location.pathname, ...options.headers }

findMany: {
  shape: {
    "/listings/search": { /* поиск с фильтрами */ },
    "/agency/dashboard": { /* активные объявления агентства */ },
    "/agent/dashboard": { /* мои объявления */ },
    "public": { /* публичная выдача */ },
  },
}

store.run(
  { userId: ctx.auth?.id, agencyId: ctx.activeAgency?.id },
  () => next(),
);

prisma.$extends(
  guard.extension(() => ({
    userId: store.getStore()?.userId,
    agencyId: store.getStore()?.agencyId,
  }))
)

findFirst: {
  shape: {
    "/agent/dashboard": (ctx) => ({
      select: agentDashboardSelect,
      where: {
        id: { equals: force(ctx.userId) },
      },
    }),
  },
},

GET /api/v1/user/first
x-api-variant: /agent/dashboard
Authorization: Bearer ...

"/agency/dashboard": (ctx) => ({
  select: agencyDashboardSelect,
  where: {
    id: { equals: force(ctx.agencyId) },
  },
}),

"/agent/dashboard": (ctx) => {
  if (!ctx.userId) throw new Error("Missing userId in context");
  return { select: agentDashboardSelect, where: { id: { equals: force(ctx.userId) } } };
},

"/agency/dashboard": (ctx) => ({
  where: { id: { equals: force(ctx.agencyId) } },
  select: {
    id: true,
    name: true,
    _count: { select: { listings: true, agents: true } },
    listings: {
      orderBy: { createdAt: true },
      take: { default: 10, max: 10 },
      where: { deletedAt: { equals: force(null) } },
      select: {
        id: true,
        title: true,
        priceMin: true,
        city: true,
        _count: { select: { inquiries: true, views: true } },
        inquiries: {
          orderBy: { createdAt: true },
          take: { default: 5, max: 5 },
          where: { deletedAt: { equals: force(null) } },
          select: {
            id: true,
            createdAt: true,
            message: true,
            tenant: { select: { id: true, name: true } },
          },
        },
      },
    },
    pendingInvitations: {
      take: { default: 5, max: 5 },
      where: { ignored: { equals: force(null) } },
      select: { /* ... */ },
    },
  },
}),

• Сначала инфраструктура контекста — ALS. Без store.run в middleware shape получает undefined вместо контекста. Это видно по логам: console.log(store.getStore()) в guard-расширении пишет undefined, и любая force(ctx.userId) получает undefined. Это должен быть fail-fast сценарий: если userId или agencyId отсутствует, лучше падать до вызова Prisma, а не надеяться на поведение undefined. Заполнение хранилища — обязательный нулевой шаг.
  
• Сначала одно сложное чтение. Я начал с дашборда пользователя. Сложный, потому что много вложенных селектов с разными фильтрами и take — это лучший стресс-тест для DSL. И второй довод: у запроса один корневой объект (findMe → user.findFirst с принуждением по userId).
  
• GraphQL остаётся параллельно. Старая GraphQL-операция продолжала работать, пока новая RPC-страница не подтверждена. Никакой резкой замены. На клиенте usePrivateApollo менялся на useFetchQuery поштучно — страница за страницей.
  
• Дашборд агентства вторым. Сложнее, потому что добавляется агентство как корневой объект (agency.findFirst с force(ctx.agencyId)), плюс ещё уровень вложенности.
  
• Удалить GraphQL-код. Только когда обе страницы работают.

const where = { type: { in: types } };
if (city) where.city = { equals: city };

• CRUD-тяжёлая многотенантная SaaS (агентство недвижимости, кадровая платформа, биллинг)
  
• Дашборды и страницы со стабильной структурой ответа
  
• Маленькая или средняя команда (1–10 разработчиков), где таблица форм помещается в голове и каждое поле имеет смысл
  
• Когда GraphQL Federation/Subgraph избыточен

• Аналитика, BI, конструктор запросов для пользователя
  
• Команды на 50+ разработчиков с десятками автономных моделей, где общая таблица форм станет узким местом ревью
  
• Когда основной клиент — внешние интеграции и процесс строится contract-first: сначала публичный OpenAPI/GraphQL-контракт, потом реализация

• Декларация = граница. Shape — это не декоративная валидация поверх логики, а часть границы доступа к данным.
  
• Pathname-as-variant — ключ выбора варианта, не авторизация. Авторизация всё равно должна быть в resolveVariant или в обработчике авторизации.
  
• ALS — нормально, если заполнение в правильном middleware. Это не магия, это store.run(value, callback) обёрнутый вокруг next().
  
• Сложные дашборды через вложенные селекты — да. Ad-hoc query builder через тот же механизм — нет.

• findUnique и findUniqueOrThrow нельзя безопасно ограничить tenant scope через Prisma extension. Для scoped моделей лучше держать findUniqueMode = "reject" и использовать findFirst с принудительным tenant/user условием.
  
• Автоматический tenant scope работает только на top-level операцию. Вложенные чтения через include/select им не фильтруются.
  
• Вложенные записи связей (relation writes в data) не перехватываются scope-расширением. Если используете — закрывайте границы на уровне БД или явно в shape.
  
• Raw SQL ($queryRaw, $executeRaw) обходит этот уровень защиты, поэтому такие запросы нужно проверять отдельно.
  
• x-api-variant — не источник прав. Подделывается клиентом.

export function createRestContext(prisma: any): RequestHandler {
  return async (req, res, next) => {
    const ctx = await getContext({ req, res } as any, prisma);
    req.context = ctx;
    store.run(
      { userId: ctx.auth?.id, agencyId: ctx.activeAgency?.id },
      () => next(),
    );
  };
}

• findMany → GET /{model}/; для длинных запросов есть POST-альтернатива POST /{model}/read (потому что POST /{model}/ занят под create).
  
• findFirst → GET /{model}/first или POST /{model}/first.
  
• findManyPaginated → GET /{model}/paginated или POST /{model}/paginated.

GET /api/v1/user/first
x-api-variant: /agent/dashboard

• JWT декодируется → userId попадает в ALS
  
• Express маршрутизирует на сгенерированный userRouter.findFirst
  
• prisma-guard смотрит на x-api-variant: /agent/dashboard
  
• Находит shape, вызывает (ctx) => ({...}) с заполненным ctx.userId
  
• Принуждает where: { id: { equals: ctx.userId } }
  
• Применяет вложенный select: профиль, сохранённые объявления, отклики, активность
  
• Prisma собирает и выполняет запросы к БД
  
• Ответ — структура, в точности соответствующая shape