МСП и агенты

МСП в Gigma ERP — это режим, где в одной платформе живёт много разных бизнесов.

Главное правило простое:

Один проект = один бизнес = один хозяин = свои данные.

Backend должен проверять это правило при каждом чтении и при каждой записи. Если пользователь или агент из проекта A, он не должен видеть, менять или удалять данные проекта B.

Что такое проект

Проект — это граница бизнеса внутри ERP.

К проекту относятся:

• пользователи;
• роли и права;
• отделы и филиалы;
• заказы;
• звонки;
• контрагенты;
• контакты и банковские реквизиты;
• меню;
• интеграции.

Если проще: проект — это “комната бизнеса”. У каждого бизнеса своя комната. Агент получает ключ только от одной комнаты.

Как работает стена между бизнесами

Когда приходит запрос, backend делает три шага:

1. Смотрит на токен и понимает, кто делает запрос.
2. Находит проект этого пользователя.
3. Проверяет, что объект запроса тоже из этого проекта.

Если проекты разные, запрос закрывается.

Обычно API вернёт:

• 403 — доступ запрещён;
• 404 — объект не найден для этого пользователя;
• 422 — запрос понятен, но бизнес-правило нарушено.

Почему нельзя доверять id

id — это только номер записи в базе. Его можно угадать или случайно получить из чужого сценария.

Поэтому агент не должен думать так:

У меня есть order_id = 15, значит я могу открыть заказ 15.

Правильная логика:

У меня есть order_id = 15.
Backend должен проверить, что заказ 15 принадлежит моему проекту.
Если не принадлежит — я останавливаюсь.

Как агент получает доступ

Агент входит как обычный пользователь ERP.

Рекомендуемая схема:

1. Создать отдельного пользователя для агента внутри проекта.
2. Дать ему отдельную роль, например agent, manager или operator.
3. Выдать только нужные права.
4. Получить пароль через POST /api/send_password.
5. Войти через POST /api/login и получить токен.
6. Отправлять этот токен в каждом запросе.

Токен — это временный ключ доступа. Его нужно хранить как пароль.

{
    "login": "agent@example.com"
}

{
    "message": "Password successfully send"
}

{
    "login": "agent@example.com",
    "password": "123456",
    "device": "sales-agent"
}

{
    "user": {
        "access_token": {
            "value": "28|example-token"
        },
        "id": 25,
        "login": "agent@example.com",
        "role": {
            "name": "agent"
        },
        "permissions": []
    }
}

Authorization: Bearer 28|example-token

{
    "user": {
        "id": 25,
        "login": "agent@example.com",
        "role": {
            "name": "agent"
        },
        "permissions": [
            {
                "name": "view-orders"
            }
        ]
    }
}

Как научить агента работать с МСП

Агенту нужна не “супер-админка”, а инструкция поведения.

Минимальная инструкция:

Ты работаешь только внутри проекта своего токена.
Не выбирай project_id сам.
Не пытайся открыть чужой id.
Если API вернул 403 или 404 — это не твоя зона.
Перед записью проверяй, что объект получен из текущего проекта.
Для опасных действий проси подтверждение человека.

Что агент может делать

Если у агента есть токен пользователя проекта и нужные права, он может:

• смотреть свои заказы;
• создавать или обновлять свои рабочие данные;
• работать со звонками своего проекта;
• читать своих контрагентов;
• добавлять контакты и реквизиты только своим контрагентам;
• работать с меню и интеграциями своего проекта;
• выполнять внутренние операции, которые разрешены его ролью.

Что агент не должен делать

Агент не должен:

• использовать общий системный токен для всех бизнесов;
• сам подставлять чужой project_id;
• открывать заказ, звонок, контакт или реквизиты по случайному id;
• получать роль owner, если ему достаточно роли оператора;
• видеть токены, платежные данные или чувствительные поля без отдельного права;
• повторять опасное действие автоматически после неизвестной ошибки.

Хорошая роль для агента

Для production лучше заводить отдельную роль agent.

Пример набора прав:

• view-orders — читать заказы;
• edit-orders — менять заказы, если агенту это реально нужно;
• view-counterparties — читать контрагентов;
• edit-counterparties — менять контрагентов, контакты и реквизиты, если это входит в сценарий;
• view-communications — читать коммуникации;
• edit-communications — менять коммуникации;
• view-tasks — читать задачи;
• edit-tasks — менять задачи.

Обычно агенту не надо давать:

• edit-users — управление пользователями;
• edit-roles — управление ролями;
• edit-permissions — управление правами;
• edit-admins — управление администраторами;
• edit-applications — изменение приложений и витрин без отдельного сценария.

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

Безопасный сценарий работы

Пример правильного сценария:

1. Агент получает пароль через /api/send_password.
2. Агент входит через /api/login.
3. Получает токен.
4. Проверяет себя через /api/user.
5. Берёт список доступных заказов через обычный ERP API.
6. Работает только с теми id, которые получил из своего списка.
7. Если API вернул 403, 404 или 422, не обходит ошибку, а сообщает человеку.

Полная схема ручек для агента

Агент использует обычные ERP-ручки. Отличие агента от фронта не в URL, а в роли, правах и инструкции поведения.

Эта схема описывает ERP-агента под auth:user. Публичные E-Commerce ручки клиента под auth:counterparty сюда не входят.

Базовый URL:

https://api.gigma.ru/api

Все рабочие ручки ниже, кроме входа, требуют заголовок:

Authorization: Bearer <token>

Как читать таблицы ниже

resource означает стандартный набор:

Если у ручки нет удаления, это указано отдельно. Если агенту нужна только безопасная выдача данных, ниже пишем явные GET, а не resource.

Уровни доступа агента

Вход и сессия

Заказы

МСП-стена: заказ должен принадлежать проекту агента. Чужой order_id не должен открываться.

Звонки и коммуникации

МСП-стена: звонок, заказ и контрагент внутри звонка должны быть из проекта агента.

Контрагенты, контакты и реквизиты

МСП-стена: вложенный контакт или реквизит должен принадлежать указанному контрагенту, а контрагент должен принадлежать проекту агента.

Задачи

МСП-стена: список фильтруется по проекту агента. Для просмотра и изменения конкретной задачи нельзя доверять одному task_id: сначала подтвердить, что задача из проекта агента.

Пользователи, роли, права, отделы и филиалы

Для обычного агента эти ручки не нужны. Их стоит давать только агенту-администратору и только в одном проекте.

Интеграции пользователя и филиала

МСП-стена: user, branch, bank_requisite и integration должны быть внутри проекта агента.

Меню

МСП-стена: проектное меню не должно смешиваться с глобальными шаблонами и чужими пользовательскими пунктами.

Справочники и таблицы для чтения

Эти ручки обычно нужны агенту для выбора значений в формах и фильтрах. В этом разделе разрешено только чтение. POST, PUT/PATCH и DELETE по справочникам давать отдельно и только под задачу администратора.

Если справочник начинает менять деньги, доступы или витрины, переводить его из “можно” в “осторожно”.

Номенклатура, склады и остатки

Важно: часть inventory-permissions (view-nomenclatures, view-warehouses, view-shops и похожие) может не быть заведена базовым seeder-ом. Перед выдачей агенту проверить конкретную роль в БД. Для агента безопаснее начинать с чтения. Импорт и массовые изменения лучше делать только после подтверждения человека.

Магазины, приложения, страницы и витрина

Важно: shop-permissions (view-shops, create-shops, edit-shops) тоже проверить в роли/БД перед выдачей агенту. Эта зона меняет то, что видит клиент в витрине. Для обычного агента лучше только чтение.

Webhooks приложений

Webhook-и могут отправлять данные наружу. В backend доступ к ним ограничен проектом приложения и ролью owner/admin. Агенту давать только при явной задаче интеграции.

Файлы, Dadata и вспомогательные запросы

Файлы могут содержать персональные или финансовые данные, поэтому права на них стоит давать отдельно. В текущей policy список и загрузка требуют edit-users, а один файл можно смотреть, менять и удалять только его создателю.

История

История полезна агенту для объяснения “что изменилось”. Но если история содержит чужой проект, это баг МСП-стены.

Скидки, промо и билеты

Эти ручки влияют на деньги, доступы или посещение события. Агенту лучше давать их только с подтверждением человека.

Служебные и неагентские зоны

Минимальный набор ручек для первого агента

Для безопасного первого запуска лучше начать так:

Всё остальное лучше подключать по одному сценарию и после теста на двух проектах: агент проекта A не должен видеть проект B.

Короткое правило для разработчика

Перед любым новым API для МСП нужно ответить на один вопрос:

Где в этом запросе доказано, что данные принадлежат проекту текущего пользователя?

Если ответа нет, API небезопасен.

Короткое правило для агента

Мой токен — это мой проект. Всё, что не принадлежит моему проекту, для меня закрыто.