Документы и сущности системы

Эта страница описывает сквозную логику SNABZHENETS+: какие документы и справочники есть в системе, как они называются в интерфейсе и как должны связываться друг с другом от клиентской потребности до закупки, оплаты, поставки и аналитики.

При изменении схемы данных или пользовательских потоков эту карту нужно обновлять вместе с кодом, чтобы названия документов и связи оставались едиными для разработки и документации.

Принципы сквозной модели

В системе есть два уровня идентификации.

Уровень	Что хранит	Для чего используется
`id`	Технический UUID записи	Связи в базе, API, аудит, вложения
Номер документа	Человекочитаемый номер вроде `REQ-00001`, `PUR-00001`, `CP-20260506113000`	Интерфейс, поиск, печатные формы, коммуникация с клиентами и поставщиками

Все рабочие данные изолированы внутри портала через tenantId. Номенклатура, контрагенты, документы, склад, счета, платежи, файлы и аудит одного портала не должны смешиваться с данными другого портала.

Позиции документов должны сохранять снимок названия, артикула, единицы измерения, цены и условий на момент создания документа. Для этого в моделях используются поля productNameSnapshot, skuSnapshot, uom, суммы, НДС и комментарии. Даже если карточка товара или контрагента позже изменится, исторический документ должен оставаться читаемым в исходном виде.

Единый формат строк для закупочного контура повторяет PO: номенклатура или название, количество, ед. изм., цена, сумма, НДС, дата поставки и комментарий. Такой формат используется в заявке на закупку из PO, RFQ поставщику, КП и входящем счёте.

Файловый обмен строк PO ведётся через домен PROCUREMENTS в data_exchange_jobs: template, import preview, mapping, apply и export работают для текущей закупки, а не как локальная CSV-операция фронтенда. Импорт поддерживает режимы добавления, обновления по SKU или точному сочетанию названия и единицы измерения, а также полной замены строк после успешного preview.

Как процесс виден в интерфейсе

Рабочий портал показывает не отдельные таблицы, а один закупочный маршрут. Один и тот же документ можно увидеть в воронке, реестре, карточке закупки, аналитике и связанных справочниках.

Заявки (PO) — канбан закупочной воронки. Колонки отражают рабочие статусы: черновик, в работе, поиск поставщика, ожидание КП, согласование, ожидание оплаты и просроченные заявки.
Заявки на закупку — реестр внутренних потребностей. В строке видны дата создания, номер заявки, контекст PO, инициатор, срок, статус и количество позиций. Раскрытая строка показывает подразделение, проект, источник PO, комментарий и состав потребности.
Карточка закупки — рабочее место закупщика. Здесь ведутся позиции, бюджет, срок закупки, поставщики, RFQ, КП, счета, приход на склад, история статусов и быстрые переходы к связанным документам.
Номенклатура — единый каталог товаров и услуг. Он хранит коды, артикулы, названия, категории, единицы измерения, статусы, остатки и цены, чтобы строки PO, RFQ и счетов не заполнялись вручную заново.
Контрагенты — общая база покупателей, поставщиков и перевозчиков. Одна карточка хранит профиль, форму, ИНН, контакты, теги, статус и supplier-профиль, если контрагент участвует в закупках.
Аналитика — сводка по PO, счетам, поставщикам и срокам. Здесь видны объём закупок, сумма к оплате, выполнение бюджета, конверсия заявок, on-time delivery, средний цикл, просрочки и топ поставщиков.
Интеграции — маркет подключений и API-инструменты. Через него связываются email, webhooks, ERP/1C, ЭДО, банки, BI и другие внешние сервисы.

Такой интерфейс помогает пройти путь от клиентской потребности до оплаты и поставки без ручной сборки цепочки из переписок, файлов и разрозненных таблиц.

Основные документы

Код / номер	Документ в интерфейсе	Модель	Назначение	Ключевые связи
`PO` / внешний номер	Заявка или заказ от покупателя	Отдельной модели сейчас нет	Внешнее основание от клиента: письмо, заказ, заявка, тендерная потребность. В текущей схеме фиксируется как `clientRef`, `externalReference`, комментарий или вложение к связанному документу	Покупатель, КП, исходящий счёт, заявка на закупку
`REQ-00001`	Заявка на закупку	`ProcurementRequest`	Внутренний запрос от инициатора: что нужно купить, в каком количестве, к какому сроку и для какого контекста	Инициатор, позиции заявки, будущая закупка
Строка заявки	Позиция заявки на закупку	`ProcurementRequestItem`	Конкретная потребность в PO-формате: товар или услуга, количество, ед. изм., цена, сумма, НДС, дата поставки, бренд и комментарий	Заявка, номенклатура, единица измерения, позиция закупки
`PUR-00001` / `PO-...`	Закупка / закупочная воронка	`Procurement`	Рабочий объект закупщика: входящий запрос клиента, shortlist поставщиков, условия, КП, победитель, счета, поставка	Заявка, заказчик-контрагент, ответственный, поставщики, КП поставщиков, входящие счета, склад
Строка закупки	Позиция закупки	`ProcurementItem`	Позиция, которую реально закупают. Может быть перенесена из заявки или создана вручную	Закупка, позиция заявки, номенклатура, RFQ, котировки
Участник закупки	Поставщик в закупке	`ProcurementSupplier`	Поставщик, которого пригласили или рассматривают в конкретной закупке	Закупка, профиль поставщика, котировки, RFQ
`RFQ-...`	Заявка поставщику / запрос КП	`SupplierRfq`	Исходящий запрос поставщику на цену, сроки и условия поставки	Закупка, поставщик, позиции RFQ, токен портала поставщика
Строка RFQ	Позиция заявки поставщику	`SupplierRfqItem`	Что именно запрашивается у поставщика в PO-подобном формате: количество, ед. изм., целевая цена, НДС, срок поставки, комментарий и допустимость аналогов	RFQ, позиция закупки, номенклатура
`QUOTE-...`	Ответ поставщика / КП поставщика	`SupplierQuote`	Полученное от поставщика предложение с ценами, сроками, условиями и источником	Закупка, RFQ, поставщик, версии, события статусов
Строка ответа поставщика	Позиция КП поставщика	`SupplierQuoteItem`	Цена, скидка, НДС, срок поставки и решение по строке	КП поставщика, строка RFQ, номенклатура
Версия ответа	Версия КП поставщика	`SupplierQuoteVersion`	Снимок предложения при отправке или пересогласовании	КП поставщика, автор сохранения
Котировка закупки	Сравнительная котировка	`ProcurementQuote`	Внутренняя запись для сравнения предложений и выбора победителя	Поставщик в закупке, КП поставщика, закупка
Строка котировки	Позиция сравнительной котировки	`ProcurementQuoteItem`	Сопоставление строк закупки и строк предложения поставщика	Котировка закупки, позиция закупки, строка КП поставщика
Номер поставщика	Входящий счёт	`Invoice`	Счёт от поставщика на оплату закупки. Старые счета могут хранить только сумму, новые счета создаются со строками	Закупка, поставщик, файл счёта, позиции счёта, оплаты, история цен
Строка входящего счёта	Позиция входящего счёта	`InvoiceItem`	Строка счета в PO-формате: товар, количество, ед. изм., цена, сумма, НДС, дата поставки и комментарий	Входящий счёт, позиция закупки, номенклатура
Платёж	Оплата входящего счёта	`Payment`	Факт оплаты поставщику, включая частичные оплаты	Входящий счёт
`CP-...`	Коммерческое предложение клиенту	`CommercialProposal`	Sell-side предложение покупателю: цены, сроки, условия оплаты и поставки	Покупатель, позиции КП, исходящий счёт
Строка КП	Позиция коммерческого предложения	`CommercialProposalItem`	Товар или услуга в PO-подобном формате: количество, ед. изм., цена, сумма, скидка, НДС, срок поставки и комментарий	КП, номенклатура, строка исходящего счёта
`SI-...`	Счёт клиенту / исходящий счёт	`SalesInvoice`	Счёт на оплату для покупателя. Может быть создан из КП или напрямую	Покупатель, КП, оплаты клиента
Строка исходящего счёта	Позиция счёта клиенту	`SalesInvoiceItem`	Строка, выставленная покупателю	Исходящий счёт, строка КП, номенклатура
Платёж клиента	Оплата исходящего счёта	`SalesInvoicePayment`	Факт оплаты от покупателя	Исходящий счёт

Справочники и рабочие сущности

Сущность	Модель	Что означает	Где используется
Портал / организация	`Tenant`	Изолированная рабочая область компании	Владеет всеми tenant-данными
Пользователь	`User`	Сотрудник портала или платформенный администратор. Для сотрудника хранится отдел, должность, телефон, Telegram и признак обязательной смены временного пароля	Инициирует заявки, отвечает за закупки, действует в аудитах
Отдел	`Department`	Tenant-справочник подразделений сотрудников	Групповой доступ к документам уровня `Для группы`, профиль пользователя
Роль	`Role`	Набор прав пользователя по матрице доступа	Управление доступом, навигацией и действиями
Разрешение	`Permission`	Конкретное право на действие	Роли и RBAC
Контрагент	`Counterparty`	Юрлицо, ИП, физлицо или иностранная компания	Покупатели, поставщики, перевозчики, счета, КП
Профиль поставщика	`Supplier`	Дополнительная закупочная карточка контрагента	Закупки, цены, входящие счета
Номенклатура	`CatalogItem`	Товар или услуга из каталога	Позиции заявок, закупок, RFQ, КП, счетов, склад
Категория	`CatalogCategory`	Группа номенклатуры	Каталог и аналитика
Единица измерения	`Unit`	Шт, кг, м, услуга и другие единицы	Позиции документов
Склад	`Warehouse`	Место хранения или транзитная зона	Остатки и движения
Остаток	`StockBalance`	Количество товара на складе: на руках, резерв, доступно, в пути	Каталог, складская аналитика
Движение склада	`StockMovement`	Приход, расход, резерв, корректировка или перемещение	Приёмка по закупке или счёту, ручные корректировки
История цен	`PriceHistory`	Зафиксированная закупочная цена по товару	Каталог, аналитика, повторные закупки
Прайс-лист	`PriceList`	Прайс поставщика, покупателя или внутренний ориентир	Каталог, контрагенты и сравнение цен
Строка прайса	`PriceListItem`	Коммерческие условия по товару из номенклатуры: цена, валюта, минимальная партия, срок поставки и срок действия	Прайс-лист, номенклатура
Версия прайса	`PriceListVersion`	История изменения строк прайса и источник обновления	Прайс-лист, аудит изменений
Файл	`File`	Вложение к документу или сущности	Счета, КП, закупки, контрагенты
Задача обмена данными	`DataExchangeJob`	Preview, mapping, apply и export для файлового обмена	Каталог, остатки, позиции PO через домен `PROCUREMENTS`
Комментарий	`Comment`	Обсуждение внутри карточки	Любая сущность через `entityType` и `entityId`
Журнал аудита	`AuditLog`	История действий и изменений	Все ключевые документы и справочники

Служебные и связующие сущности

Сущность	Модель	Назначение
Роль пользователя	`UserRole`	Связь пользователя и его единственной основной роли
Право роли	`RolePermission`	Связь роли и разрешения
Refresh-токен	`RefreshToken`	Основа будущего обновления сессий
Аудит входа	`LoginAudit`	Успешные и неуспешные попытки входа
Токен портала поставщика	`SupplierRfqPortalToken`	Безопасная ссылка поставщика на RFQ
Событие статуса RFQ	`SupplierRfqStatusEvent`	История переходов заявки поставщику
Событие статуса ответа поставщика	`SupplierQuoteStatusEvent`	История переходов КП поставщика
Событие статуса КП клиенту	`CommercialProposalStatusEvent`	История переходов коммерческого предложения
Событие статуса счёта клиенту	`SalesInvoiceStatusEvent`	История переходов исходящего счёта

Сквозной buy-side поток

Базовый закупочный поток начинается с внутренней потребности и заканчивается оплатой поставщику и складским отражением.

text

REQ Заявка на закупку
  -> PUR Закупка
    -> ProcurementSupplier shortlist поставщиков
      -> RFQ Заявка поставщику
        -> QUOTE Ответ поставщика
          -> ProcurementQuote сравнение и выбор победителя
            -> Invoice входящий счёт
              -> Payment оплата поставщику
              -> StockMovement приход на склад
              -> PriceHistory история закупочной цены

Правила работы:

Заявка REQ создаётся инициатором и содержит позиции потребности.
Закупка PUR / PO может быть создана из заявки или напрямую как быстрый входящий запрос клиента. При создании из заявки позиции должны переноситься в ProcurementItem, а заявка получает статус converted_to_procurement; при быстром создании позиции можно добавить уже внутри карточки закупки.
Если из PO создаётся заявка на закупку, все строки с ненулевым остатком заранее отмечены. Пользователь снимает лишние галочки, а цена, сумма, НДС и дата поставки копируются из строк PO.
В закупке закупщик формирует список поставщиков ProcurementSupplier.
Для каждого поставщика можно создать RFQ. RFQ можно запустить из заявки на закупку или напрямую из PO, если поставщик уже известен. В обоих случаях строки RFQ подтягиваются из источника и заранее отмечены.
Ответ поставщика QUOTE фиксирует цены, скидки, НДС, сроки и условия. Если ответ пришёл через RFQ, он связан с SupplierRfq.
Внутренняя ProcurementQuote нужна для сравнения предложений и выбора победителя. Победитель записывается в selectedSupplierId, selectedSupplierCounterpartyId и selectedQuoteId закупки.
Входящий счёт Invoice связывается с закупкой и поставщиком. Новые счета создаются со строками: сумма и НДС считаются из выбранных позиций, а при привязке к PO строки подтягиваются из доступного остатка.
При приёмке создаются движения склада StockMovement, обновляются остатки StockBalance, а закупочные цены попадают в PriceHistory.

Сквозной sell-side поток

Sell-side поток начинается с покупателя и заканчивается выставлением и оплатой исходящего счёта.

text

PO / внешняя заявка покупателя
  -> CP Коммерческое предложение
    -> SI Счёт клиенту
      -> SalesInvoicePayment оплата клиента

Правила работы:

Покупатель хранится как Counterparty с сегментом buyer.
Если клиент прислал PO, заявку, письмо или тендерное основание, в текущей схеме это внешний документ. Его нужно фиксировать в clientRef, externalReference, комментарии или файле до появления отдельной модели CustomerOrder.
Коммерческое предложение CP создаётся на покупателя и содержит условия продажи: позиции, цены, НДС, сроки, оплату и доставку.
Строки КП заполняются тем же PO-подобным редактором, чтобы названия, количества, цены, суммы, НДС, сроки поставки и комментарии не расходились с закупочным контуром.
Принятое КП может быть конвертировано в исходящий счёт SI; строки счёта сохраняют связь со строками КП.
Оплаты клиента фиксируются как SalesInvoicePayment; сумма оплаты обновляет paidAmount, outstandingAmount и статус счёта.
Если для выполнения клиентского заказа нужна закупка, в Procurement фиксируется быстрый клиентский контекст: номер заявки клиента, заказчик-контрагент или текстовое название компании, ожидаемая клиентом дата и файл запроса. Целевая логика на будущее: отдельный PO/CustomerOrder связывает покупателя, КП, закупочные заявки и исходящие счета напрямую.

Статусы основных документов

Заявка на закупку

Статус	Наименование	Смысл
`new`	Новая	Заявка создана
`under_review`	На проверке	Заявку проверяет закупщик или руководитель
`accepted`	Принята	Заявку можно передавать в закупку
`needs_clarification`	Нужно уточнение	Не хватает данных по позициям, срокам или контексту
`converted_to_procurement`	Передана в закупку	По заявке создана закупка
`cancelled`	Отменена	Заявка закрыта без закупки

Закупка

Статус	Наименование	Смысл
`draft`	Черновик	Закупка создана, данные ещё заполняются
`in_progress`	В работе	Закупщик ведёт закупку
`supplier_search`	Поиск поставщика	Формируется список поставщиков
`waiting_quote`	Ожидаем КП	Запрошены или ожидаются предложения
`approval`	Согласование	Победитель и условия проходят согласование
`waiting_payment`	Ожидает оплаты	Есть счёт или условия к оплате
`paid`	Оплачено	Оплата поставщику выполнена
`in_delivery`	В пути	Поставка ожидается
`partially_received`	Частично получено	Принята часть количества
`fully_received`	Получено	Поставка получена полностью
`closed`	Закрыто	Закупка завершена
`cancelled`	Отменено	Закупка остановлена
`overdue`	Просрочено	Нарушен контрольный срок

RFQ поставщику

Статус	Наименование	Смысл
`DRAFT`	Черновик	Запрос готовится
`PENDING_APPROVAL`	На согласовании	Запрос ожидает внутреннего подтверждения
`APPROVED`	Согласован	Можно отправлять поставщику
`REJECTED`	Отклонён	Нужно доработать или отменить
`SENT`	Отправлен	Запрос ушёл поставщику
`VIEWED`	Просмотрен	Поставщик открыл запрос
`PARTIALLY_ANSWERED`	Частично отвечен	Ответ получен не по всем позициям
`ANSWERED`	Отвечен	Поставщик дал ответ
`EXPIRED`	Истёк	Срок ответа прошёл
`CLOSED`	Закрыт	Работа по запросу завершена
`CANCELLED`	Отменён	Запрос отменён

Ответ поставщика

Статус	Наименование	Смысл
`DRAFT`	Черновик	Ответ готовится
`SUBMITTED`	Подан	Поставщик или менеджер отправил предложение
`UNDER_REVIEW`	На проверке	Закупщик анализирует условия
`REVISION_REQUESTED`	Запрошена правка	Поставщику нужна доработка
`RESUBMITTED`	Подан повторно	Поставщик прислал исправленную версию
`ACCEPTED`	Принят	Предложение принято полностью
`PARTIALLY_ACCEPTED`	Принят частично	Приняты отдельные строки
`REJECTED`	Отклонён	Предложение не подходит
`WITHDRAWN`	Отозван	Поставщик или менеджер снял предложение
`EXPIRED`	Истёк	Предложение потеряло актуальность

Входящий счёт

Статус	Наименование	Смысл
`draft`	Черновик	Счёт заведён, но ещё не готов к оплате
`uploaded`	Загружен	Файл счёта загружен
`checking`	На проверке	Реквизиты и суммы проверяются
`waiting_payment`	Ожидает оплаты	Счёт готов к оплате
`partially_paid`	Оплачен частично	Зарегистрирована часть оплаты
`paid`	Оплачен	Счёт закрыт оплатами
`overdue`	Просрочен	Срок оплаты прошёл
`voided`	Аннулирован	Счёт исключён из оплаты

Коммерческое предложение

Статус	Наименование	Смысл
`DRAFT`	Черновик	КП готовится
`PENDING_APPROVAL`	На согласовании	КП ожидает внутреннего подтверждения
`APPROVED`	Согласовано	КП можно отправлять клиенту
`REJECTED`	Отклонено	КП нужно доработать
`SENT`	Отправлено	КП отправлено покупателю
`VIEWED`	Просмотрено	Покупатель открыл КП
`ACCEPTED`	Принято	Покупатель согласился
`DECLINED`	Отклонено клиентом	Покупатель отказался
`EXPIRED`	Истекло	Срок действия КП прошёл
`CONVERTED_TO_INVOICE`	Сконвертировано в счёт	По КП создан исходящий счёт
`CANCELLED`	Отменено	КП отменено внутри системы

Счёт клиенту

Статус	Наименование	Смысл
`DRAFT`	Черновик	Счёт готовится
`PENDING_APPROVAL`	На согласовании	Ожидает внутреннего подтверждения
`APPROVED`	Согласован	Можно выставлять
`ISSUED`	Выставлен	Счёт выпущен
`SENT`	Отправлен	Счёт отправлен покупателю
`VIEWED`	Просмотрен	Покупатель открыл счёт
`PARTIALLY_PAID`	Оплачен частично	Есть частичная оплата
`PAID`	Оплачен	Счёт полностью закрыт
`OVERDUE`	Просрочен	Оплата просрочена
`VOIDED`	Аннулирован	Счёт аннулирован
`CANCELLED`	Отменён	Счёт отменён до завершения

Статусы справочников и сервисного слоя

Область	Значения	Наименования
Общий статус записи	`active`, `inactive`, `blocked`, `archived`	Активно, неактивно, заблокировано, в архиве
Пользователь	`invited`, `active`, `suspended`, `deleted`	Приглашён, активен, приостановлен, удалён
Контрагент	`llc`, `ie`, `individual`, `self_employed`, `foreign_company`	Юрлицо/ООО, ИП, физлицо, самозанятый, иностранная компания
Сегмент контрагента	`supplier`, `buyer`, `carrier`	Поставщик, покупатель, перевозчик
Поставщик	`new`, `active`, `checking`, `risky`, `blocked`	Новый, активный, на проверке, рисковый, заблокированный
Склад	`storage`, `transit`, `returns`	Хранение, транзит, возвраты
Движение склада	`receipt`, `issue`, `transfer_in`, `transfer_out`, `adjustment`, `reservation`, `release`, `in_transit_increase`, `in_transit_decrease`	Приход, расход, перемещение, корректировка, резерв, снятие резерва, изменение количества в пути
Подписка портала	`TRIAL`, `ACTIVE`, `EXPIRED`, `BLOCKED`, `CANCELED`, `MANUAL_PENDING`, `ENTERPRISE_REQUESTED`	Триал, активна, истекла, заблокирована, отменена, ручное ожидание, запрос Enterprise
Биллинг-платёж	`PENDING`, `PAID`, `FAILED`, `CANCELED`	Ожидает, оплачен, ошибка, отменён
Установка интеграции	`PENDING_CONFIG`, `ACTIVE`, `ERROR`, `DISABLED`, `UNINSTALLED`	Ожидает настройки, активна, ошибка, отключена, удалена
Синхронизация интеграции	`SUCCESS`, `ERROR`, `RUNNING`, `IDLE`	Успешно, ошибка, выполняется, простаивает

Административные, биллинговые и интеграционные сущности

Сущность	Модель	Назначение
API-ключ	`ApiKey`	Доступ внешних систем к API портала
Исходящий вебхук	`Webhook`	Отправка событий портала во внешнюю систему
Категория интеграций	`IntegrationCategory`	Группировка интеграций в маркетплейсе
Интеграция	`IntegrationDefinition`	Описание доступного подключения
Установка интеграции	`IntegrationInstallation`	Подключение интеграции в конкретном портале
Webhook endpoint интеграции	`IntegrationWebhookEndpoint`	Публичный входящий URL для интеграции
Лог вебхука интеграции	`IntegrationWebhookLog`	История входящих и исходящих webhook-событий
Задача синхронизации	`IntegrationSyncJob`	Регламентный импорт или экспорт данных
Возможность интеграции	`IntegrationCapabilityRecord`	Включённые capability: товары, счета, банк, EDI, BI и другие
Тариф	`BillingPlan`	План START, TEAM, BUSINESS или ENTERPRISE
Подписка портала	`TenantSubscription`	Текущий тариф, период, статус и провайдер оплаты
Платёж биллинга	`BillingPayment`	Оплата подписки
Биллинговая транзакция	`BillingTransaction`	История ручных и системных начислений
Биллинговое событие	`BillingEvent`	Журнал событий подписки
Партнёр	`Partner`	Партнёр платформы
Реферальная ссылка	`ReferralLink`	Код регистрации порталов от партнёра
Вознаграждение партнёра	`PartnerReward`	Начисление или выплата партнёру
Hub-аудит	`HubAuditLog`	Журнал действий операторской панели
Настройки Telegram Hub	`HubTelegramSettings`	Конфигурация Telegram-бота операторов
Подписчик Telegram	`HubTelegramSubscriber`	Получатель уведомлений Hub
Лог Telegram-уведомлений	`HubTelegramNotificationLog`	Защита от повторных уведомлений
Настройки Max Hub	`HubMaxSettings`	Конфигурация Max-бота операторов
Получатель Max	`HubMaxSubscriber`	Получатель уведомлений Hub
Лог Max-уведомлений	`HubMaxNotificationLog`	Защита от повторных уведомлений

Документы и сущности системы ​

Принципы сквозной модели ​

Как процесс виден в интерфейсе ​

Основные документы ​

Справочники и рабочие сущности ​

Служебные и связующие сущности ​

Сквозной buy-side поток ​

Сквозной sell-side поток ​

Статусы основных документов ​

Заявка на закупку ​

Закупка ​

RFQ поставщику ​

Ответ поставщика ​

Входящий счёт ​

Коммерческое предложение ​

Счёт клиенту ​

Статусы справочников и сервисного слоя ​

Административные, биллинговые и интеграционные сущности ​

Рекомендуемый сквозной формат связей ​