Адаптация существующих модулей и тем под CS-Cart 4.22.1

Изменения в ядре

  • smarty/smarty обновлён до версии 5.8.4.
  • imagine/imagine обновлён до версии 1.5.4.
  • symfony/lock обновлён до версии 5.4.45.
  • symfony/css-selector обновлён до версии 5.4.45.
  • symfony/console обновлён до версии 5.4.54.
  • tijsverkoyen/css-to-inline-styles обновлён до версии 2.4.0.
  • guzzlehttp/guzzle обновлён до версии 7.10.0.
  • guzzlehttp/promises обновлён до версии 2.3.0.
  • guzzlehttp/psr7 обновлён до версии 2.8.0.
  • phpseclib/mcrypt_compat обновлён до версии 2.0.8.

Изменились требования к версии PHP

Теперь поддерживаются версии PHP от 7.4.0 включительно до 8.6.0 не включительно — добавлена поддержка PHP 8.4 и 8.5. Ранее верхней границей была версия 8.4.0.

Независимо от минимальной версии, поддерживаемой продуктом, рекомендуем использовать актуальную версию PHP, для которой ещё выпускаются официальные обновления безопасности. Устаревшие версии PHP больше не получают исправлений безопасности и могут сделать магазин уязвимым, поэтому своевременное обновление безопаснее. Кроме того, новые версии работают быстрее.

Обработчики сохранения сессий теперь регистрируются как объект

Tygh\Web\Session::registerHandlers() больше не передаёт шесть отдельных callback-функций в session_set_save_handler() — этот способ объявлен устаревшим начиная с PHP 8.4. Вместо них передаётся новый объект Tygh\Web\SessionSaveHandler, который реализует \SessionHandlerInterface и делегирует вызовы тем же методам Session::open(), close(), read(), write(), destroy() и gc().

Типы в адаптере намеренно не указаны для совместимости с \SessionHandlerInterface в PHP 7.4, где интерфейс не объявляет типы параметров и возвращаемых значений. Атрибут #[\ReturnTypeWillChange] подавляет уведомления о предварительно объявленных типах возвращаемых значений в PHP 8.1 и более поздних версиях.

Для модулей ничего не меняется: эти шесть методов Session сохраняют названия, сигнатуры и видимость, поэтому их по-прежнему можно переопределять в подклассе.

Токены доступа

В ядро добавлены токены доступа. Пользователь выпускает персональные токены в профиле, а модули — от имени пользователя, например сервер авторизации для подключаемых приложений. У токена есть области доступа (scopes), определяющие, что разрешено приложению. Модули объявляют области доступа в схеме access_tokens/scopes, а принимающий токены входной скрипт указывает обслуживаемые области доступа (см. “Входные скрипты с обработчиком запросов”).

  • Токены хранятся в новой таблице access_tokens. В таблице сохраняется только SHA-256-хеш токена, поэтому его значение показывается пользователю один раз.
  • Токен не хранит права пользователя. Права владельца проверяются при каждом запросе, а области доступа токена только сужают их. Токен перестаёт работать при отключении владельца; токен продавца не работает, пока продавец неактивен.
  • Новая вкладка “Токены доступа” в профиле позволяет выпускать, просматривать и отзывать персональные токены. Она отображается, если пользователю доступна хотя бы одна область доступа. В форме доступные области представлены флажками, объединёнными в группы; зависимые области выбираются вместе с необходимыми для них. Продавцу, которому запрещено использовать токены, например приостановленному продавцу маркетплейса, форма не предлагается. Администраторы просматривают и отзывают токены других пользователей в их профилях и на новой странице Администрирование → Токены доступа (access_tokens.manage). Вкладка профиля содержит персональные токены; вкладка другого пользователя отображается, пока у него есть активный персональный токен. Административный список включает персональные токены и токены приложений, в том числе сохранённые истёкшие и отозванные записи.
  • Токены нельзя выпускать в сессии, открытой с помощью функции “Войти как пользователь”.
  • Новая настройка Настройки → Безопасность → Максимальный срок действия токенов доступа (access_tokens_max_lifetime) ограничивает срок, который пользователь выбирает для персонального токена: 30, 90, 180 или 365 дней.
  • Существуют два типа токенов (\Tygh\Enum\AccessTokenTypes): персональные (P, значения начинаются с pat_) и токены приложений (A, значения начинаются с aat_). Токен приложения всегда выпускает модуль-эмитент. Для указания объекта, которому выдан токен, модуль использует собственный идентификатор: столбцы issuer и issuer_ref.
  • Истёкший или отозванный токен хранится ещё 30 дней (AccessTokenService::RETENTION_PERIOD): администраторы могут проверить его на странице управления токенами, а эмитент — отличить отозванный токен от неизвестного. Отозванные токены не отображаются в персональном списке профиля. Затем ядро удаляет их. Хранилище растёт только при выпуске токенов, поэтому очистка выполняется при выпуске, не чаще раза в день (ключ хранилища access_tokens_next_cleanup). Модулям не требуется отдельное расписание очистки таблицы токенов ядра.
  • При удалении модуля отзываются токены с любой объявленной им областью доступа, в том числе содержащие области других модулей. При удалении пользователя удаляются все его токены.
  • Модуль, выпускающий токены, показывает доступ для собственных записей так же, как ядро показывает доступ токена: шаблон views/access_tokens/components/access_list.tpl принимает результат ScopeRegistry::group() в параметре $access.

Объявление областей доступа

Модуль объявляет области доступа в файле schemas/access_tokens/scopes.post.php. Идентификатор области состоит из слов, разделённых двоеточиями; допустимы строчные латинские буквы, цифры и подчёркивания (\Tygh\AccessTokens\ScopeRegistry::ID_PATTERN). Платформа не разбирает идентификаторы: префикс перед двоеточием — только соглашение об именовании.

$schema['my_api:read'] = [
    'name'         => 'my_addon.scope_read',             // language variable
    'description'  => 'my_addon.scope_read_description', // optional language variable
    // Optional: the language variable of the title of the group, under which a person sees the scopes of the group
    'group'        => 'my_addon.scopes',
    // Optional: whether the user of the session may get the scope. The scope is offered only when it returns true.
    'is_available' => static function (\Tygh\Web\Session $session) {
        return true;
    },
];

$schema['my_api:write'] = [
    'name'     => 'my_addon.scope_write',
    // Optional: the scopes that a token must have to get this one. They are granted together with it, and a scope
    // whose requirements are not available is not available either
    'requires' => ['my_api:read'],
];

return $schema;

Области одной группы отображаются вместе под её заголовком; области без группы — под заголовком “Доступ”. Модуль добавляет собственную подсказку рядом со своими областями в форме персонального токена через шаблонный хук access_tokens:scope_group; переменная $scope_group.group указывает группу.

  • Схема читается и при отключённом или удаляемом модуле, который её расширяет: ядро отзывает токены с областями удаляемого модуля. Поэтому объявление должно обращаться к классам своего модуля только внутри is_available.
  • is_available определяет, что может получить пользователь: какие области предлагаются на странице токенов и при предоставлении согласия приложению, а также какие области получает токен. Запрос с токеном повторно не проверяется этим условием, поэтому код, обслуживающий входной скрипт, самостоятельно проверяет доступ пользователя.

Сервисы

  • Tygh::$app['access_tokens.service'] (\Tygh\AccessTokens\AccessTokenService) выпускает и отзывает токены и обслуживает их хранилище:
    • issuePersonalToken(\Tygh\Web\Session $session, $name, $lifetime_days, $requested_scopes) выпускает персональный токен пользователю сессии: сессия должна принадлежать самому владельцу, штатная политика паролей не должна требовать смены пароля, компании пользователя должно быть разрешено использовать токены, а срок должен укладываться в установленный максимум. Токен получает разрешённые пользователю области вместе с необходимыми для них зависимостями;
    • issueApplicationToken(int $user_id, string $issuer, int $issuer_ref, string $name, array $scopes, DateTimeImmutable $expires_at, string $issuer_version = ''): IssuedAccessToken выпускает токен модуля. Эмитент должен проверить согласие пользователя, доступность областей и их зависимости. Метод требует активной зарегистрированной ссылки на исходного владельца и поколение, ограничивает области и срок действия этой ссылкой, но не разрешает области в контексте сессии. При вставке токена атомарно проверяется то же поколение;
    • оба метода возвращают \Tygh\AccessTokens\IssuedAccessToken: выпущенный токен и его значение, показываемое один раз. Если токен нельзя выпустить, возникает \Tygh\AccessTokens\AccessTokenIssueException; метод getReason() возвращает языковую переменную причины;
    • getToken(int $token_id): ?AccessToken, getTokenByValue(string $value): ?AccessToken, hasActiveTokens(int $user_id, string $type = AccessTokenTypes::PERSONAL): bool и getTokens(array $params, int $items_per_page = 0, ?array $owner_user_types = null): array находят токены. getTokens() возвращает [$tokens, $search]: первый элемент содержит объекты AccessToken, второй — применённые параметры поиска и постраничного вывода. Параметр q сопоставляется с названием токена, электронной почтой и именем владельца; $owner_user_types — доверенный фильтр, передаваемый отдельно от параметров поиска: null не ограничивает типы владельцев, пустой список не разрешает ни одного типа, а непустой список ограничивает выборку, подсчёт и пагинацию указанными типами владельцев.
    • revoke(), revokeByIssuerRefs($issuer, $issuer_refs) и revokeByScopes($scopes) сохраняют состояние отзыва ссылки приложения и отзывают связанные с ней токены. Отзыв по области доступа охватывает также ссылки, для которых уже не осталось записей токенов. retire(array $token_ids): int заменяет отдельные токены без отзыва их ссылки;
    • deleteByIssuerRefs($issuer, $issuer_refs) удаляет токены и состояние ссылки после удаления объектов эмитента; deleteUserTokens() сохраняет факт удаления владельца перед удалением токенов; deleteIssuerTokens(string $issuer): void освобождает пространство имён эмитента после удаления модуля;
    • getLifetimeVariants() возвращает сроки, разрешённые настройкой Максимальный срок действия токенов доступа, или пустой список, если ни один срок не разрешён. В этом случае персональный токен не выпускается: issuePersonalToken() отказывает с причиной access_tokens.error_lifetime_not_configured, а не выбирает срок, который администратор не разрешал;
    • registerUsage() сохраняет сведения о последнем использовании токена не чаще раза в минуту.
  • Tygh::$app['access_tokens.policy'] (\Tygh\AccessTokens\AccessTokenPolicy, AccessTokensProvider::getPolicy()) содержит правила использования токенов и управления ими. Правила для пользователя принимают сессию: isIssuingAllowedInSession() (администратор или продавец в собственной сессии), canIssueTokens() (то же, при отсутствии обязательной смены пароля и при условии, что компании пользователя разрешено использовать токены), isTokenAdministrator() (администратор без ограничений компании или витрины управляет токенами всех пользователей), canManageUserTokens($session, $user_id) и isTokenOwner($session, $user_id). Методы canCompanyUseTokens($company_id) и mayOwnerUseTokens($owner) проверяют компанию и владельца токена. Эти методы не заменяют схемы разрешений: для просмотра чужих токенов требуется view_administrators или view_vendor_administrators в зависимости от типа учётной записи владельца; для отзыва требуется соответствующая привилегия управления. getIssuingRefusalReason($session): ?string возвращает языковой ключ причины отказа в выдаче или null, если выдача разрешена; сервис и вкладка профиля используют одно правило. Обязательный третий аргумент конструктора — замыкание, которое проверяет штатную политику паролей по данным аутентификации сессии. Оно вызывается только при проверках выдачи, поэтому создание политики и аутентификация существующего токена не требуют чтения настроек паролей.
  • Tygh::$app['access_tokens.authenticator'] (\Tygh\AccessTokens\Authentication\AccessTokenAuthenticator) проверяет токен запроса: authenticate($bearer_token, $accepted_scopes). Используются только запросы к БД, поэтому проверка работает до определения типа учётной записи запроса. Результат — \Tygh\AccessTokens\Authentication\AuthenticationResult: принятый токен (getToken()) с владельцем (getOwner(), \Tygh\AccessTokens\Authentication\AccessTokenOwner — идентификатор, тип учётной записи, компания и язык владельца) либо причина отказа (getRefusal(), одно из значений \Tygh\Enum\AccessTokenRefusals). Инициализация сохраняет результат для запроса в Tygh::$app['access_tokens.authentication']; AccessTokensProvider::getAuthentication() возвращает его или null, если запрос не аутентифицирован токеном. При входе владельца дополнительно проверяется, что тип учётной записи и компания совпадают с ранее установленными данными, чтобы контексты выполнения и кэша не совмещались с учётной записью, изменённой во время инициализации.
  • \Tygh\AccessTokens\AccessToken представляет токен доступа: его владельца, разрешённые приложению действия и срок работы. Работоспособность зависит от момента времени, поэтому состояние запрашивается на заданный момент: getStatus(\DateTimeImmutable $now) возвращает одно из значений \Tygh\Enum\AccessTokenStatuses; момент также принимает isActive(\DateTimeImmutable $now), но не isRevoked(). Контроллер передаёт шаблонам обычные массивы токенов с полем status, сравниваемым с "AccessTokenStatuses::ACTIVE"|enum и аналогичными значениями. getIssuer() и getIssuerRef() указывают модуль-эмитент и объект, для которого выпущен токен; hasAnyScope($scopes) проверяет наличие одной из областей доступа.
  • Чтение и запись таблицы access_tokens выполняет \Tygh\AccessTokens\Persistence\AccessTokenRepository — единственный компонент, знающий формат хранения токена. Владельцев токенов читает \Tygh\AccessTokens\Persistence\AccessTokenOwnerRepository.
  • Сервисы получают время через \Psr\Clock\ClockInterface, а не из константы TIME. Момент передаётся как \DateTimeImmutable, например срок истечения в issueApplicationToken(). Только репозиторий преобразует момент в Unix timestamp для хранения в таблице; методы получения данных AccessToken возвращают временные метки в сохранённом виде, готовыми к форматированию дат в шаблонах.
  • Столбцы issuer и issuer_ref указывают модуль-эмитент и объект, для которого выдан токен. Каждый эмитент нумерует ссылки самостоятельно, поэтому ссылка имеет смысл только вместе с эмитентом: revokeByIssuerRefs() и deleteByIssuerRefs() принимают эмитента первым аргументом. Удаляя объект, для которого выданы токены, эмитент удаляет и токены: иначе сохранившийся токен указывал бы на следующий объект, получивший освободившийся номер.
  • \Tygh\AccessTokens\IssuerReference и Persistence\IssuerReferenceRepository управляют новым состоянием access_token_issuer_refs: исходный владелец, неизменяемое поколение, выданные области доступа, абсолютный срок истечения, отзыв и удаление владельца. Токены ядра и OAuth-подключения привязываются к нему через issuer_version. Перед выпуском любых учётных данных эмитент вызывает AccessTokenService::registerIssuerReference(string $issuer, int $reference, int $user_id, DateTimeImmutable $expires_at, string $version, array $scopes): bool с новым 32-символьным шестнадцатеричным идентификатором поколения на весь срок жизни объекта. Для повторного использования вызывается extendIssuerReference(string $issuer, int $reference, int $user_id, DateTimeImmutable $expires_at, string $version): bool; отозванное или удалённое поколение не создаётся заново. getIssuerReference(string $issuer, int $reference): ?IssuerReference, getPendingIssuerReferences(string $issuer, int $limit): array и acknowledgeIssuerReference(IssuerReference $reference): void позволяют эмитенту применить состояние ядра через свои сервисы. Подтверждение сопоставляет исходного владельца, поколение и наблюдаемое состояние. Ссылки сохраняются после очистки отдельных токенов до собственного истечения и окончания периода хранения. Ранняя аутентификация читает это состояние без инициализации выпуска.
  • Идемпотентные миграции ядра и OAuth добавляют привязку к поколению и согласуют статусы пары модулей; учётные данные приложений из версий разработки без такой привязки требуют повторного подключения.
  • Токен доступа не зависит от сессии административной панели. Инициализация не вызывает fn_get_panel_access_refusal(), поэтому токен продолжает работать, даже если пользователь не может войти в панель, например из-за истёкшего пароля. Чтобы прекратить доступ, отзовите токен. Статус пользователя, доступность компании и ограничения панели по IP по-прежнему проверяются при каждом запросе.
  • Tygh::$app['access_tokens.scope_registry'] (\Tygh\AccessTokens\ScopeRegistry) предоставляет области схемы access_tokens/scopes (getScopes()), области, доступные пользователю сессии (getAvailable($session)), и области, выдаваемые по запросу пользователя (resolve($requested_scopes, $session) добавляет необходимые зависимости и исключает неизвестные и недоступные области). Также доступны группировка областей для формы и списка токенов (group($scope_ids); незарегистрированная область, например отключённого модуля, обозначается своим идентификатором) и области, объявленные модулем, без областей ядра (getDeclaredByAddon($addon)): при удалении модуля ядро отзывает токены с этими областями, чтобы они не заработали после повторной установки. Схема загружается один раз за запрос. Область представляет собой проверенное объявление с добавленными значениями по умолчанию; ScopeRegistry::isValidId() проверяет идентификатор.

Сессии с истёкшим сроком действия

Механизм хранения сессий в БД больше не возвращает истёкшие сессии: Tygh\Backend\Session\Database::read() выбирает сессию по идентификатору и времени истечения. Раньше истёкшая сессия работала до удаления её строки сборщиком мусора, который запускается вероятностно и не чаще раза в десять минут. Механизм Redis хранит срок в TTL ключа и уже работает таким образом, поэтому теперь оба механизма ведут себя одинаково.

Входные скрипты с обработчиком запросов

Входной скрипт модуля, не являющийся страницей dispatch, например API или конечная точка протокола, обслуживается обработчиком запросов PSR-15 этого модуля. Перед подключением init.php скрипт объявляет:

  • REQUEST_HANDLER — сервис контейнера приложения, отвечающий на запрос вместо dispatch и реализующий \Psr\Http\Server\RequestHandlerInterface. После init.php скрипт вызывает HttpApplication::serve(). Если модуль не регистрирует сервис, например отключён или недоступен на тарифе магазина, скрипт отвечает кодом 404.
  • ACCESS_TOKEN_SCOPES — необязательная константа: запросы аутентифицируются Bearer-токенами доступа, и токен должен иметь хотя бы одну область из списка. Такой скрипт также объявляет NO_SESSION, но не объявляет ACCOUNT_TYPE: тип определяется владельцем токена.
  • NO_SESSION — скрипт вызывается программой. Без этой константы скрипт обслуживает пользователя панели и объявляет ACCOUNT_TYPE, из которого формируется имя cookie сессии.

Значения задаются литералами: автозагрузчик ещё недоступен. Противоречивое объявление — области без обработчика или вместе с сессией либо панелью, обработчик скрипта панели без типа учётной записи — является ошибкой разработчика и вызывает \Tygh\Exceptions\DeveloperException.

Каждый скрипт обработчика в области A без ACCESS_TOKEN_SCOPES должен объявлять ACCOUNT_TYPE, в том числе при наличии NO_SESSION. Только скрипт с аутентификацией токенами получает тип учётной записи от владельца токена.

define('AREA', 'A');
define('REQUEST_HANDLER', 'addons.my_addon.request_handler');
define('ACCESS_TOKEN_SCOPES', ['my_api:read', 'my_api:write']);
define('NO_SESSION', true);

require $root_dir . '/init.php';

/** @var \Tygh\Web\App\HttpApplication $application */
$application = Tygh::$app;
$application->serve();

Запрос, обслуживаемый обработчиком, никогда не владеет сессией (Session::isReadOnly() возвращает true). Скрипт для пользователя читает сессию панели из браузера, ничего не меняя: записи в ?:sessions и ?:stored_sessions не выполняются, срок истечения не продлевается, cookie сессии не отправляется, идентификатор не обновляется и не уничтожается, сборщик мусора не запускается. Скрипт для программного вызова вообще не имеет сессии. Идентификатор сессии берётся только из cookie.

Пока запрос не владеет сессией, записывающие этапы инициализации пропускаются: вход по сохранённым данным сессии (“Запомнить меня”) не выполняется, корзина сессии не сохраняется, плановая очистка корзин не запускается, компания не переключается параметром запроса, цветовая схема и тип меню панели не меняются. Обработчик хука user_init выполняется, но его записи в сессию отбрасываются. Активность владельца токена доступа по-прежнему сохраняется — см. этапы работы с токеном ниже.

Такой скрипт больше не очищает кэш или миниатюры по параметрам запроса cc, ct и ctpl, не позволяет клиенту выбирать представление ответа через is_ajax, не применяет к страницам фильтры вывода панели, не выводит версию магазина по параметру version, не позволяет отключить сессию через no_session и не определяет клиентов как роботов по User-Agent. Всё это относится к dispatch панели, через который входной скрипт не проходит.

  • Запрос обработчика содержит учётные данные — токены доступа, коды протокола авторизации, сессию панели — и обслуживается только по TLS. Исключение — loopback-хост, где сервер разработки обычно работает по обычному HTTP; эти случаи различает fn_is_request_transport_secure(). Любой другой запрос отклоняется с кодом 400 до остальных проверок.

  • Инициализация отклоняет такой запрос через HttpApplication::refuse() и никогда не перенаправляет его: перенаправление в административную панель раскрыло бы её адрес, а программа всё равно не последовала бы ему. Ядро не реализует протокол скрипта и не объясняет причину отказа: клиент получает только статус без тела, будь то программа или пользователь страницы скрипта. Страницы с собственными отказами для пользователя формирует модуль, обслуживающий скрипт.

  • Запрос скрипта, принимающего токены доступа, допускается или отклоняется в первом стеке инициализации, до загрузки обычных модулей:

    1. fn_init_access_token() находит и проверяет Bearer-токен через аутентификатор: хеш, срок, отзыв, статус и тип владельца, доступность компании и наличие области скрипта. Тип учётной записи ещё неизвестен, поэтому выполняются только запросы к БД — без хуков, схем и кэшированных выборок. Результат сохраняется в контейнере приложения: access_tokens.authentication, принятый токен с владельцем либо причина отказа (\Tygh\Enum\AccessTokenRefusals).
    2. fn_init_account_type() определяет константу ACCOUNT_TYPE: тип владельца токена для таких запросов и customer для остальных, если константа ещё не определена.
    3. fn_init_unmanaged_addons() загружает неуправляемые модули: только они могут участвовать в допуске запроса на этом раннем этапе.
    4. fn_init_request_admission() отклоняет запрос по обычному HTTP и запрашивает решение модулей о токене через хук access_tokens_authenticate_post: эмитент может отклонить токен, например если механизм его выпуска отключён. Допуск требует положительной проверки: токен должен пройти первый этап и не быть отклонён ни одним модулем. При отказе возвращается fn_get_access_token_refusal_response(): код причины — 401, если другой токен может быть принят, или 403, если владельцу запрещён токен либо нет области скрипта, — и запрос аутентификации Bearer без тела ответа. Модуль протокола выпуска через хук access_tokens_deny_request описывает отказ клиенту, например параметрами запроса аутентификации, либо заменяет ответ, например публичным документом с указанием, где получить токен.

    Порядок важен: ключ статического уровня кэша содержит тип учётной записи и запоминается на весь запрос при первом обращении, поэтому тип должен быть определён до чтения кэша. Обработчики обоих хуков выполняются до доступности настроек, схем, языковых переменных и обычных модулей и могут обращаться только к БД: прочитанная там схема закэшировалась бы без расширений модулей.

  • Владелец принятого токена входит позже, в третьем стеке инициализации, через fn_init_token_user(), после fn_init_addons() и fn_init_request_handler(). Вход выполняется так же, как в панель и REST API: fn_fill_auth() получает полную строку пользователя, когда все модули загружены и могут участвовать через хук fill_auth. Если после этого владелец не является пользователем запроса, запрос отклоняется с кодом 403: обработчик fill_auth может оставить запрос без авторизованного пользователя. Использование токена регистрируется только для обслуженного запроса. До входа владельца fn_init_company_id() берёт компанию из токена, аналогично компании пользователя REST API. fn_init_user() сохраняет активность владельца (users.last_activity) так же, как для сессии панели, раз в пять минут.

  • fn_init_request_handler() выполняется сразу после fn_init_addons() и отвечает кодом 404, если указанный скриптом обработчик не зарегистрирован. До инициализации модулей их статус известен только из таблицы и не меняется, если модуль недоступен на тарифе магазина. Этап ищет сервис, но не создаёт его: фабрика может читать данные, подготавливаемые позже, например язык запроса. Запрос с неработающим токеном отклоняется раньше, поэтому отключённый модуль отвечает на него кодом 401, а не 404.

  • config.php больше не определяет константу ACCOUNT_TYPE. Точки входа, определяющие её самостоятельно (admin.php, vendor.php), работают как прежде; витрина, REST API, платёжные и другие скрипты по-прежнему получают customer при инициализации. Если config.local.php или код, выполняемый до инициализации init.php, читает ACCOUNT_TYPE, проверяйте, определена ли константа.

  • Модуль access_restrictions отклоняет запрос через fn_deny_request() с кодом 403 вместо остановки скрипта текстовым сообщением: запрос обработчика получает отказ приложения.

Токены защиты форм чужой сессии

fn_generate_security_hash() возвращает пустую строку, если запрос не владеет сессией (Session::isReadOnly()), то есть для любого запроса входного скрипта с обработчиком. Хеш вычисляется из идентификатора сессии, поэтому иначе входной скрипт, работающий внутри сессии панели браузера, выводил бы настоящий токен форм панели на своей общедоступной странице. На такой странице нет форм панели, требующих защиты; если входному скрипту нужен собственный токен, он подписывает его самостоятельно.

Сессии административной панели вне dispatch

Входной скрипт с обработчиком, обслуживающий пользователя панели, объявляет тип учётной записи панели и не объявляет NO_SESSION. Инициализация передаёт ему сессию браузера только для чтения: пользователь запроса заполняется через fn_init_user(), как на любой странице панели, но сессия не меняется.

  • fn_get_panel_access_refusal() проверяет вход в сессии, тип пользователя и необходимость смены пароля. Dispatch панели использует результат для проверок входа и типа пользователя и существующего перенаправления на смену пароля. Скрипт вне dispatch вызывает ту же политику и выбирает собственный ответ. Причины определены в \Tygh\Enum\PanelAccessRefusals.

psr/http-message 2.0

Пакет ядра psr/http-message обновлён с 1.1 до 2.0. Зависящие от него пакеты ядра (guzzlehttp/psr7, php-http/httplug, psr/http-client, psr/http-factory, aws/aws-sdk-php) поддерживают обе версии. Версия 2.0 добавляет типы возвращаемых значений в интерфейсы PSR-7: обновите модуль, если он сам реализует интерфейсы PSR-7 или содержит собственную копию psr/http-message 1.x.

Приложение HTTP-процесса

Процесс, обслуживающий HTTP-запрос, теперь получает \Tygh\Web\App\HttpApplication в качестве Tygh::$app; консольная команда по-прежнему получает \Tygh\Application. init.php выбирает приложение по транспорту процесса, поэтому входные скрипты не меняются. HttpApplication расширяет \Tygh\Application и добавляет компоненты HTTP:

  • Tygh::$app['http.request'] — PSR-7-запрос процесса, построенный из исходных данных запроса. Инициализация очищает только $_REQUEST, поэтому обработчик проверяет читаемые данные по правилам своего протокола.
  • Tygh::$app['http.response_emitter'] — отправляет PSR-7-ответ клиенту.
  • Tygh::$app['http.handler_runner'] — \Tygh\Web\App\Psr15RequestHandlerRunner, запускающий обработчик и отправляющий ответ через компонент отправки с передачей ошибок обработчику ошибок платформы.
  • HttpApplication::serve() — обслуживает запрос обработчиком PSR-15, указанным входным скриптом в константе REQUEST_HANDLER. Обработчик возвращает ответ, не отправляя его самостоятельно и не завершая скрипт: запрос, ответ и реакция на ошибку остаются под управлением платформы.
  • HttpApplication::refuse($status) — отклоняет запрос такого скрипта, возвращая только статус без тела.
  • HttpApplication::send($response) — отправляет собственный ответ платформы, например отказ при инициализации, по тем же правилам, что и ответ обработчика. Каждый ответ платформы получает X-Content-Type-Options: nosniff.
  • HttpApplication::fail($exception) — отвечает на запрос такого скрипта при ошибке инициализации, обработчика или отправки ответа. Ошибка записывается в журнал магазина (Tygh::$app['http.failure_logger'], тип general, действие runtime), а клиент получает только статус 500 без страницы магазина и текста ошибки. В режиме разработки ответ содержит ошибку в виде обычного текста. \Tygh\Tools\ErrorHandler::handleException() передаёт ошибку такого скрипта этому методу до формирования страницы или AJAX-ответа, поэтому AJAX-ответ с текстом исключения больше не попадает в эти скрипты.

Входной скрипт модуля обслуживает свой протокол, как показано в разделе “Входные скрипты с обработчиком запросов”.

psr/http-server-handler 1.0

В ядро включён psr/http-server-handler 1.0: интерфейс PSR-15 \Psr\Http\Server\RequestHandlerInterface. Автозагрузчик ядра имеет приоритет над автозагрузчиками модулей, поэтому модуль с собственной копией пакета получает интерфейс ядра. Версия 1.0 — единственная основная версия; обновление не требуется.

psr/clock 1.0

В ядро включён psr/clock 1.0: интерфейс PSR-20 \Psr\Clock\ClockInterface. Его реализует \Tygh\Tools\SystemClock, доступный как Tygh::$app['clock']. Компонент, проверяющий время, принимает интерфейс как зависимость, что позволяет передать ему нужный момент в тесте.

Новые классы читают время через этот сервис вместо константы TIME и time(). Сервис запрашивает время один раз за операцию и передаёт момент как \DateTimeImmutable; репозиторий принимает его аргументом и преобразует в Unix timestamp только при построении запроса. Строки таблиц и методы получения сохранённых данных сохраняют Unix timestamp согласно принятому в платформе хранению и форматированию дат. \Tygh\Tools\DateTimeHelper работает с такими моментами: addSeconds() сдвигает момент точно, а createPeriodRelativeTo() вычисляет период относительно переданного момента.

Логирование

\Tygh\Logging\StoreLogger — логгер PSR-3 (\Psr\Log\LoggerInterface), записывающий сообщения в журнал магазина. Новый код принимает LoggerInterface как зависимость вместо вызываемого объекта записи сообщения; провайдер компонента создаёт логгер с префиксом, обозначающим компонент:

$pimple['addons.my_addon.logger'] = static function () {
    return new \Tygh\Logging\StoreLogger(
        static function ($message) {
            fn_log_event('general', 'runtime', ['message' => $message]);
        },
        'My add-on: ',
        (string) Registry::get('config.dir.root')
    );
};

Записываются только ошибки и более серьёзные сообщения, если необязательный пятый аргумент не задаёт другой минимальный уровень из \Psr\Log\LogLevel. Компонент, чьи предупреждения указывают на атаку, понижает порог до LogLevel::WARNING. Неизвестный PSR-3 уровень вызывает \Psr\Log\InvalidArgumentException. Исключение в ключе контекста exception добавляет свой класс и расположение относительно каталога установки; остальной контекст не подставляется в сообщение и не записывается отдельно. Само сообщение записывается, поэтому вызывающий код должен передать текст без секретных данных либо использовать необязательный четвёртый аргумент для фильтрации, например удаления персональных данных.

Адреса административной панели и панели продавца

\Tygh\Web\Backoffice\PanelUrlBuilder, доступный как Tygh::$app['backoffice.panel_url_builder'], строит адрес страницы панели: buildAdminUrl($url, $lang_code = null) и buildVendorUrl($url, $lang_code = null). Если код языка не указан, используется язык запроса. Панель всегда задаёт вызывающий код: fn_url() без префикса admin: или vendor: ведёт в панель текущего процесса, что неверно при построении адреса для другого пользователя, например в письме продавцу, отправленном из административной панели или плановой задачей.

Модули с входными скриптами

  • \Tygh\Addons\EntryScript создаёт и удаляет относительную символическую ссылку из корня магазина на входной скрипт модуля, например mcp.php или oauth.php. Созданная администратором копия скрипта сохраняется. install(), uninstall() и checkCanBeInstalled() возвращают \Tygh\Common\OperationResult: при неудаче код ошибки соответствует одной из констант EntryScript::ERROR_*, а сообщение объясняет администратору препятствие и способ его устранения. checkCanBeInstalled() сообщает препятствие, ничего не меняя, поэтому страница диагностики показывает причину, пока скрипт отсутствует. isCopy() определяет, что в корне магазина находится копия, а не ссылка: копия сохраняет код исходной версии, поэтому после обновления диагностика предупреждает об этом.
  • \Tygh\Web\App\Psr7ResponseEmitter отправляет клиенту PSR-7-ответ: статус, заголовки и тело.

Модули, требующие более новой версии PHP

Требуемая модулю версия PHP (<compatibility><php_version><min> в addon.xml) проверяется при установке, но магазин может обслуживать запросы на разных версиях PHP: консольный PHP для плановых задач может быть старее PHP веб-сервера, а после установки версию могут понизить. Модуль может использовать синтаксис требуемой версии, который старый PHP не сможет даже разобрать.

Теперь процесс с версией PHP ниже требуемой активному модулю исключает этот модуль: не загружает и считает отключённым. То же происходит с зависимыми модулями. Остальная часть магазина работает как обычно. Без этих модулей представление магазина отличается от других процессов, поэтому данные кэша Registry хранятся отдельно — см. Registry::setCacheScope(). Модуль исключается, даже если его код мог бы работать на старой версии: указывайте фактически необходимую версию. Верхняя граница по-прежнему проверяется только при установке.

Лицензирование

Новые возможности \Tygh\Licensing\Features::AI_MCP_SERVER (ai_mcp_server), AI_MCP_CORE_TOOLS (ai_mcp_core_tools) и OAUTH_SERVER (oauth_server) доступны на тарифах ultimate и unlim Store Builder, тарифах plus, ultimate и unlim Multi-Vendor, а также в пробном режиме. Все три модуля проходят стандартные проверки лицензирования, в том числе при инициализации и проверке доступности установки.

Изменения в классе Tygh\Http

Tygh\Http::getStatus() возвращает полученный код ответа HTTP или FTP. Сам по себе код 200–299 не гарантирует успешную передачу: сервер может прислать заголовки с кодом 200, после чего соединение оборвётся. В этом случае Http::get() или Http::post() вернёт false, а Http::getStatus() сохранит полученный код.

При проверке успешности запроса проверяйте одновременно результат запроса на строгое false и допустимый код ответа:

$response = Http::get($url);
$status = Http::getStatus();

if ($response === false || $status < 200 || $status >= 300) {
    return false;
}

Сохраняйте прежние ограничения клиента на допустимые коды: если он ожидает именно 200, проверяйте $response !== false && $status === Http::STATUS_OK.

Функции ядра

Новые функции

  • fn_check_permission_access_tokens($action, array $request_variables, $user_id): bool проверяет доступ явно указанного действующего пользователя к существующему владельцу типа администратора или продавца с положительным идентификатором. Только глобальный root-администратор может управлять токенами и OAuth-подключениями глобального root-администратора; просмотр регулируется обычными привилегиями соответствующего типа. Правило действует в обоих режимах управления доступом и не ограничивает автоматический отзыв или отзыв OAuth-клиентом.
  • \Tygh\Storefront\Storefront::setAddress(string $url, string $address_type, string $relative_path) — назначает подготовленный адрес при явном изменении адреса.
  • \Tygh\Storefront\Storefront::isAddressChanged() — проверяет, был ли адрес явно назначен для текущего сохранения.
  • \Tygh\Storefront\Storefront::markAddressSaved() — сбрасывает признак явного изменения адреса после успешного сохранения.
  • fn_init_access_token() — находит и проверяет Bearer-токен доступа запроса к принимающему токены входному скрипту, используя только запросы к БД, и сохраняет результат в access_tokens.authentication для принятия решения о допуске.
  • fn_init_account_type() — определяет константу ACCOUNT_TYPE, если скрипт ещё не определил её.
  • fn_init_request_admission() — допускает запрос входного скрипта с обработчиком либо отклоняет его до загрузки обычных модулей: при обычном HTTP или отсутствии принимаемого магазином токена доступа.
  • fn_get_access_token_refusal() — определяет, отклоняется ли запрос входного скрипта с токенами и почему: возвращает причину из \Tygh\Enum\AccessTokenRefusals либо null для принятого токена. Запрашивает решение модулей о токене через хук access_tokens_authenticate_post.
  • fn_deny_access_token_request($reason) — отклоняет запрос входного скрипта, принимающего токены доступа, через fn_get_access_token_refusal_response() и завершает запрос.
  • fn_get_access_token_refusal_response(ServerRequestInterface $request, array $scopes, $reason) — формирует отказ для запроса входного скрипта с токенами: статус причины и запрос аутентификации Bearer без тела ответа. Модуль протокола выпуска токенов описывает отказ или заменяет ответ через хук access_tokens_deny_request.
  • fn_init_token_user() — после загрузки модулей выполняет вход владельца принятого токена по полной строке пользователя; отклоняет запрос, если владелец после этого не является пользователем запроса, и регистрирует использование токена.
  • fn_init_request_handler() — отвечает кодом 404, если указанный входным скриптом обработчик не зарегистрирован: модуль отключён или не включён в тариф.
  • fn_is_request_transport_secure() — проверяет, поступил ли запрос по допустимому для учётных данных транспорту: TLS либо обращение к loopback-хосту.
  • fn_deny_request($status, $message = '', ?callable $refusal = null) — отказывает в обслуживании запроса на этапе инициализации. Запрос входного скрипта с обработчиком отклоняется через HttpApplication::refuse() с кодом статуса и никогда не перенаправляется; остальные запросы получают сообщение или отказ, заданный вызывающим кодом, например перенаправление на форму. Используйте эту функцию при инициализации вместо остановки запроса HTML-сообщением, чтобы ядро корректно отклоняло запросы таких скриптов.
  • fn_get_request_bearer_token() — получает Bearer-токен из заголовка запроса Authorization; возвращает null, если токена нет.
  • fn_is_password_change_required(array $auth) — проверяет, должен ли пользователь сменить пароль перед работой в административной панели.
  • fn_get_panel_access_refusal(array $auth, $account_type) — определяет, допускает ли панель соответствующего типа учётной записи пользователя сессии: возвращает причину отказа из \Tygh\Enum\PanelAccessRefusals либо null при успешной проверке. Dispatch панели и отдельные страницы авторизации используют эту общую политику.
  • fn_check_permission_manage_own_access_tokens(array $request_variables = []) — условие проверки прав: пользователь работает с собственными токенами доступа.
  • fn_get_cron_password() — получает пароль плановых задач магазина.
  • fn_check_cron_password($password = null) — проверяет пароль в запросе плановой задачи. Сравнение строгое; магазин без заданного пароля вообще не запускает задачу.
  • fn_ult_is_company_used($controller, $mode, array $request) — проверяет, выполняет ли административная панель dispatch от имени компании витрины, по флагу use_company схемы прав.
  • fn_ult_set_sharing_owner($company_id, array $object_ids = []) — задаёт компанию-владельца общих для витрин объектов, создаваемых при обработке запроса, и возвращает прежних владельцев. Если владелец не указан, ядро назначает новый общий объект первой активной компании. Dispatch административной панели задаёт владельца самостоятельно; код вне dispatch использует эту функцию.
  • fn_ult_restore_sharing_owner(array $previous_owners) — восстанавливает компании-владельцев общих объектов.
  • fn_execute_as_storefront(callable $action, \Tygh\Storefront\Storefront $storefront) — выполняет действие в контексте витрины, как при выборе витрины в административной панели: витрина становится текущей (Tygh::$app['storefront'] и runtime.storefront_id), а в магазине, где витрины являются компаниями, её компания становится текущей. Прежний контекст восстанавливается даже при исключении. Используйте функцию для работы с данными витрины вне dispatch административной панели.
  • fn_get_addons_incompatible_with_php(array $addon_names, $php_version) — получает модули, которые не могут работать на указанной версии PHP: требуют более новую версию либо зависят от такого модуля.
  • fn_withhold_addons_incompatible_with_php(array $addon_names) — выбирает активные модули, которые процесс должен исключить из-за неподдерживаемой версии PHP, и при их наличии изолирует кэшированные данные процесса. fn_init_unmanaged_addons() и fn_init_addons() не загружают такие модули, а fn_init_addons() помечает их отключёнными для процесса.
  • fn_is_request_from_crawler(array $server) — определяет по User-Agent, пришёл ли запрос от робота. Результат также указывает, является ли робот ИИ-агентом, действующим по текущему запросу человека, например ChatGPT-User или Claude-User, и содержит часть User-Agent, по которой распознан робот. Ядро пока не обрабатывает таких ИИ-агентов иначе, чем остальных роботов.
  • fn_is_improved_access_management_enabled(): bool — возвращает состояние нового режима управления доступом.
  • fn_get_system_privilege_types(): array — возвращает доступные типы системных привилегий A/V; V добавляет активный модуль.
  • fn_get_system_privileges(string $type): array — читает карту сохранённых системных решений без назначения обычных групп.
  • fn_check_access_management_settings_access(): bool — проверяет право реального root A изменять обязательные правила и настройки доступа.
  • fn_check_system_privileges_access(string $type, bool $manage = false): bool — проверяет просмотр системной карты по view/manage usergroups и её изменение только root A.
  • fn_prepare_usergroup_privilege_states(array $privileges, array $catalog): array — фильтрует состояния по каталогу и проверяет зависимости внутри редактируемой карты в новом режиме.
  • fn_update_system_privileges(string $type, array $privileges): bool — проверяет root и заменяет системную карту; таблица MyISAM, атомарность и откат записей не обеспечиваются.
  • fn_settings_variants_security_privileges_not_covered_by_usergroups(): array — возвращает Full access, Can view only и Forbidden для неопределённых строк.
  • fn_get_user_type_privilege($user_type, $action = 'manage') — возвращает отдельную привилегию просмотра или управления указанным типом пользователей.
  • fn_check_user_type_access($user_type, $action = 'manage', $user_id = null) — проверяет право пользователя на действие с указанным типом учётной записи.
  • fn_get_allowed_user_types($action = 'view', $user_id = null) — возвращает разрешённые пользователю типы учётных записей для просмотра или управления.
  • fn_check_user_record_access(array $target, $action = 'manage', ?array $auth = null) — проверяет конкретную учётную запись с ограничениями типа, компании, витрины и root; действия import, export, status, delete не используют исключение собственного профиля, а специальные запреты удаления root проверяет fn_check_rights_delete_user().
  • fn_get_admin_permission_rule(array $schema, $controller, $mode, $request_method, array $request_variables = []) — выбирает административное правило permissions и condition, включая параметры и карты HTTP-методов.
  • fn_check_profile_access($action, array $request_variables, $user_id, $allow_own_profile = false, $user_id_param = 'user_id', $default_user_type = null): bool — проверяет доступ к настоящему профилю в условиях схемы и guard контроллера с явно заданным исключением собственного профиля; для новой записи явно пустой тип даёт отказ, отсутствие типа использует переданный default. Если цель определяется по profile_id, отсутствие профиля даёт отказ без перехода к собственному профилю.
  • fn_check_usergroup_management_permissions($group_id, $target_user_id = 0) — проверяет право изменить группу или её назначение конкретному пользователю.
  • fn_check_usergroup_management_permissions_for_type($user_type, $action = 'manage', $user_id = null) — проверяет доступ к группам заданного типа пользователей.
  • fn_exim_check_user_import_access(array $primary_object_id, array &$object, array &$processed_data, &$skip_record) — проверяет найденную и запрашиваемую учётную запись до её изменения импортом.
  • fn_exim_filter_users_export(array &$conditions, array $joins, array $export_fields) — ограничивает экспорт доступными пользователю типами записей и назначений групп.
  • fn_exim_notify_user_import_skipped(array $processed_data) — выводит собранные при импорте предупреждения о недоступных типах пользователей и групп.
  • fn_exim_notify_skipped_user_types($message, array $types) — выводит одно предупреждение с локализованным списком пропущенных типов.

Изменённые функции

  • \Tygh\Storefront\Repository::__construct() принимает новый необязательный последний аргумент ?AddressManager $address_manager = null:

    \Tygh\Storefront\Repository::__construct(Connection $db, Factory $factory, Normalizer $normalizer, RelationsManager $relation_manager, Robots $robots, Llms $llms, ?AddressManager $address_manager = null)
    
  • fn_data_feeds_export($datafeed_id, $options = array(), $pattern = '') — ошибки подключения к FTP, авторизации, выбора каталога и передачи файла обрабатываются штатным уведомлением и возвратом false. CLI-экспорт по расписанию выводит уведомления через общий диспетчер и завершается с ненулевым кодом при ошибке.

  • fn_export($pattern, $export_fields, $options) — необязательная опция allow_empty разрешает CSV только с заголовком при отсутствии строк после всех фильтров. Пустые промежуточные пакеты пропускаются. Ошибка записи возвращает false; пользовательский func_save_content_to_file получает пустой массив и options.header_fields при пустой выгрузке и может вернуть false для сообщения об ошибке.

  • fn_exim_put_csv(&$data, &$options, $enclosure) — при пустом data использует options.header_fields для заголовка и возвращает false при ошибке открытия, записи или закрытия файла.

  • fn_google_export_export_product_availability() принимает новый необязательный последний аргумент array $product = []:

    function fn_google_export_export_product_availability(array &$availability, $export_type, array $product = [])
    
  • fn_update_static_data($data, $param_id, $section, $lang_code = DESCR_SL) — перенесена из контроллера static_data в app/functions/fn.common.php, рядом с fn_get_static_data() и fn_delete_static_data(). Функция создаёт и обновляет элементы статических данных, например пункты меню; теперь она доступна вне контроллера. Перед сохранением входные данные стандартного megabox нормализуются: отсутствующие выбранные значения используют идентификатор 0, а отсутствующий megabox или значение не в виде массива считается пустым.

  • fn_execute_as_company() — компания восстанавливается даже при исключении в действии, и хук execute_as_company_after_restore_company_id также выполняется. Вызывающему коду больше не нужен собственный try/finally вокруг функции.

  • fn_generate_security_hash() возвращает пустую строку для сессии только для чтения; см. “Токены защиты форм чужой сессии”.

  • fn_delete_user($user_id) удаляет токены доступа пользователя из ядра до выполнения существующего хука post_delete_user.

  • fn_rma_get_returns($params, $items_per_page = 0, $lang_code = CART_LANGUAGE) принимает storefront_id в $params и ограничивает запросы на возврат заказами указанной витрины.

  • fn_uninstall_addon($addon_name, $show_message = true, $allow_unmanaged = false, $execute_schema_queries = true) отзывает токены с областями модуля после выполнения функций удаления, но до удаления его регистрации в БД; после удаления данных освобождает пространство имён эмитента. Процесс с несовместимым PHP отказывает в удалении, не загружая модуль. Рекурсивные вызовы парных установщиков не повторяют одно действие.

  • fn_install_addon() откатывает установку при неудачной автоматической активации. Строгое значение false, возвращённое fn_settings_actions_addons_post_<addon>(), восстанавливает прежний статус в БД и во время выполнения.

  • \Tygh\Addons\LifecycleException позволяет современному установщику явно отказаться от действия жизненного цикла. XmlScheme4::callCustomFunctions() преобразует исключение в существующий результат прерывания или отката; прежние void-сигнатуры InstallerInterface не меняются.

  • Плановая задача password_reminder контроллера profiles проверяет пароль через fn_check_cron_password(). Теперь сравнение строгое, и магазин с пустой настройкой cron_password не запускает задачу: ранее пустой пароль пропускал любой запрос.

  • fn_init_ua() — распознаёт роботов через fn_is_request_from_crawler(); список роботов обновлён. Теперь роботами без сессии считаются Wget, Scrapy, Go-http-client, PEAR HTTP_Request2, предпросмотр ссылок WhatsApp и VK, facebookcatalog, Naver Yeti, omgili, meta-externalagent без ссылки, а также ИИ-агенты Claude-User, Perplexity-User, MistralAI-User, Amzn-User и meta-externalfetcher. Пользователи поискового приложения Яндекса и телефонов с “bot” в названии модели, например CUBOT, больше не считаются роботами и получают сессию. Константа CRAWLER по-прежнему содержит часть User-Agent в нижнем регистре, по которой распознан робот, но для некоторых роботов значение изменилось. Для скриптов REQUEST_HANDLER результат не задаёт CRAWLER и не отключает сессии: входной скрипт определяет поведение сессии независимо от User-Agent клиента.

  • fn_get_usergroups($params, $lang_code) — параметр with_privileges также принимает список типов групп пользователей, например ['with_privileges' => ['A', 'V']]. Эти группы получают отдельные списки privileges и forbidden_privileges. Значение true выбирает группы, которые могут иметь привилегии, включая группы продавцов, зарегистрированные соответствующим хуком.

  • fn_init(&$request) отклоняет перенаправления при инициализации скрипта REQUEST_HANDLER с кодом 403. Этапы fn_check_cache($params) и fn_init_ajax() пропускают для таких скриптов обработку параметров запроса, относящихся только к панели. fn_init_company_id(&$params), fn_init_user($area = AREA), fn_init_backoffice_theme_mode(array $params) и fn_init_main_menu_type(array $params) учитывают сессии только для чтения, как описано в разделе “Входные скрипты с обработчиком запросов”. Для обычных запросов панели поведение сессии сохраняется.

  • fn_init_addons() и fn_init_unmanaged_addons() исключают несовместимые с PHP модули и зависящие от них модули для текущего процесса; см. “Модули, требующие более новой версии PHP”.

  • fn_simple_ultimate(&$request) делегирует условие use_company функции fn_ult_is_company_used(); fn_ult_parse_request($request) и fn_ult_parse_api_request($object, &$params) делегируют инициализацию владельца функции fn_ult_set_sharing_owner(). Допустимые скалярные значения условий сравниваются по строковому представлению.

  • fn_tools_update_status(array $params) — принимает только один int|string в $params['id']; массивы и другие типы дают false до SQL-запросов. Проверка числового значения ID, сверка id_name с первичным ключом и нормализация ID не выполняются; строковые ключи сохраняются. Массовые вызовы нужно выполнять отдельно для каждого ID.

- fn_check_permission_manage_profiles($user_type)
+ fn_check_permission_manage_profiles($user_type, $action = 'manage')

- fn_mve_check_permission_manage_profiles(&$result, $user_type)
+ fn_mve_check_permission_manage_profiles(&$result, $user_type, $action = 'manage')

- fn_ult_check_permission_manage_profiles(&$result, &$user_type)
+ fn_ult_check_permission_manage_profiles(&$result, &$user_type, $action = 'manage')

- fn_exim_set_usergroups($user_id, $data)
+ fn_exim_set_usergroups($user_id, $data, array &$processed_data = [])

- fn_execute_permission_condition($condition)
+ fn_execute_permission_condition(array $condition, array $context = [])

Проверки профилей различают просмотр и управление. Импорт назначений сохраняет группы, которыми текущий пользователь не вправе управлять, и добавляет сведения о пропущенных типах в счётчики импорта. Условия схемы могут получить #request_variables и #user_id из явно переданного контекста; отсутствие необходимого ключа даёт отказ без вызова обработчика.

Без изменения сигнатур изменены следующие контракты:

  • fn_check_user_access($user_id, $permission), fn_check_current_user_access($permission) и fn_check_admin_permissions(...) используют общий расчёт: при Improved разрешения СП и групп складываются, Forbidden сильнее, полностью неопределённую строку разрешает или запрещает настройка fallback. При выключенном Improved администратор без групп сохраняет прежний доступ.
  • fn_check_user_access($user_id, $permission) при проверке текущего пользователя передаёт сервису ожидаемый тип из аутентифицированного контекста; несовпадение с типом снимка пользователя в Registry означает отказ.
  • fn_check_user_access($user_id, $permission) и fn_check_current_user_access($permission) принимают строку или список строковых привилегий: список проверяется с OR, пустой список возвращает false. Карты HTTP-методов и булевы решения остаются у вызывающего кода.
  • fn_check_admin_permissions(...) исполняет condition с operator = replace как окончательное решение до проверки permissions, включая null; профильные правила и исключение собственного профиля задаются схемой, без выбора по имени контроллера или функции условия.
  • fn_check_view_permissions(...) передаёт параметры проверяемой ссылки, а текущий запрос использует только для ссылки без параметров на текущие контроллер/режим; fn_check_form_permissions() явно передаёт текущий запрос при проверке POST.
  • fn_init_user($area = AREA) сбрасывает прежний контекст сессии при изменении типа пользователя в БД, а в Multi-Vendor — также при изменении storefront_id администратора.
  • fn_get_user_short_info($user_id) в Multi-Vendor дополнительно возвращает storefront_id, используемый для проверки актуальности области доступа сессии.
  • fn_update_user($user_id, $user_data, &$auth, $ship_to_another, $notify_user) сохраняет полномочия и область доступа при редактировании собственного профиля; создание первого владельца через fn_create_company_admin() остаётся доверенной частью создания компании или активации заявки.
  • fn_update_usergroup($usergroup_data, $usergroup_id = 0, $lang_code = DESCR_SL) принимает в privileges отображение privilege => state, где Y разрешает, N запрещает, а отсутствие решения не хранится; пустые группы допустимы.
  • fn_get_usergroups($params = [], $lang_code = CART_LANGUAGE) с with_privileges возвращает разрешения в privileges, запреты в forbidden_privileges.
  • fn_get_usergroup_privileges(array $usergroup) добавляет к действиям dependencies и position, используемые интерфейсом Custom access.
  • fn_get_users($params, &$auth, $items_per_page = 0, $custom_view = '') поддерживает filter_by_view_permissions для ограничения списка разрешёнными типами пользователей.
  • fn_check_rights_delete_user($user_data, $auth) проверяет право управления фактическим типом и область доступа удаляемого пользователя, сохраняя специальные запреты удаления root и собственного аккаунта; в $user_data необходимо передавать user_type.
  • fn_is_restricted_admin($params) и fn_check_editable_permissions($auth, $user_data) учитывают отдельные полномочия управления типами пользователей вместо ограничения по самому наличию группы.
  • fn_exim_check_pattern_permissions($pattern, $get_for, $user_id) принимает строку или список альтернативных привилегий для операции и дополнительное permissions.condition с and/or; or не обходит явный запрет всех альтернатив, условие получает явный #user_id, а редакция и запрет фактического раздела компании остаются обязательными.
  • fn_import($pattern, $import_data, $options) и fn_export($pattern, $export_fields, $options) повторяют проверку прав формата перед обработкой, когда объявлен ключ permissions.condition; без этого ключа прежний путь запуска сохраняется.

Новые классы

  • \Tygh\Storefront\AddressManager — подготавливает и проверяет адреса витрин, определяя типы default и subfolder для явно переданных пользовательских адресов.
  • \Tygh\AccessTokens\AccessTokenService — выпускает и отзывает токены доступа и обслуживает их хранилище.
  • \Tygh\AccessTokens\AccessTokenPolicy — правила использования токенов доступа и управления ими.
  • \Tygh\AccessTokens\AccessToken — токен доступа: владелец, разрешённые приложению действия и срок работы; возвращается AccessTokenService::getToken(), getTokenByValue() и getTokens(), передаётся в хуке access_tokens_revoke_post.
  • \Tygh\AccessTokens\IssuedAccessToken — только что выпущенный токен доступа вместе с его значением, показываемым один раз.
  • \Tygh\AccessTokens\AccessTokenIssueException — возникает, когда токен доступа нельзя выпустить; getReason() возвращает языковую переменную причины.
  • \Tygh\AccessTokens\ScopeRegistry — реестр областей доступа токенов из схемы access_tokens/scopes.
  • \Tygh\AccessTokens\Authentication\AccessTokenAuthenticator — проверяет токен доступа запроса.
  • \Tygh\AccessTokens\Authentication\AuthenticationResult — результат проверки токена запроса: принятый токен с владельцем либо причина отказа; доступен как Tygh::$app['access_tokens.authentication'].
  • \Tygh\AccessTokens\Authentication\AccessTokenOwner — владелец токена запроса в том виде, в котором он прочитан при проверке: идентификатор, тип учётной записи, компания и язык.
  • \Tygh\AccessTokens\Persistence\AccessTokenRepository — читает и записывает таблицу access_tokens. Значение токена никогда не попадает в таблицу: хранилище вычисляет и сохраняет только его хеш. search(array $params, DateTimeImmutable $now, int $items_per_page = 0, ?array $owner_user_types = null): array принимает четвёртым аргументом тот же доверенный фильтр типов владельцев, что и AccessTokenService::getTokens().
  • \Tygh\AccessTokens\Persistence\AccessTokenOwnerRepository — читает владельца токена доступа и статус его компании.
  • \Tygh\Enum\AccessTokenTypes — типы токенов: персональные и токены приложений.
  • \Tygh\Enum\AccessTokenStatuses — состояния токена на заданный момент: активен, истёк, отозван.
  • \Tygh\Enum\PanelAccessRefusals — причины отказа пользователю сессии в доступе к административной панели; возвращаются fn_get_panel_access_refusal().
  • \Tygh\Enum\AccessTokenRefusals — причины отказа ядра в запросе входного скрипта с токенами: MISSING, INVALID, FORBIDDEN, OUT_OF_SCOPE; getHttpStatus($reason) возвращает статус отказа. Сама причина никогда не передаётся клиенту без преобразования.
  • \Tygh\Providers\AccessTokensProvider — регистрирует сервисы токенов доступа; статические методы getService(), getPolicy(), getScopeRegistry() и getAuthentication() возвращают типизированные сервисы или результат аутентификации запроса.
  • \Tygh\Addons\EntryScript — символическая ссылка из корня магазина на входной скрипт модуля.
  • \Tygh\Web\App\HttpApplication — приложение процесса, обслуживающего HTTP-запрос; serve() обслуживает запрос обработчиком PSR-15, указанным входным скриптом, а refuse() отклоняет его.
  • \Tygh\Web\App\Psr15RequestHandlerRunner — передаёт запрос процесса обработчику PSR-15, отправляет возвращённый ответ и передаёт ошибку обработчика платформе; send() по тем же правилам отправляет собственный ответ платформы.
  • \Tygh\Web\App\Psr7ResponseEmitter — отправляет PSR-7-ответ клиенту. Статус задаётся после заголовков: PHP самостоятельно устанавливает 401 для заголовка WWW-Authenticate и 302 для Location, а статус ответа должен иметь приоритет.
  • \Tygh\Web\Backoffice\PanelUrlBuilder — строит адреса страниц административной панели и панели продавца; доступен как Tygh::$app['backoffice.panel_url_builder'].
  • \Tygh\Logging\StoreLogger — логгер PSR-3, записывающий ошибки в журнал магазина.
  • \Tygh\Tools\SystemClock — серверные часы PSR-20; доступны как Tygh::$app['clock'].

Изменённые классы

  • Добавлено публичное свойство \Tygh\Storefront\Storefront::$address_type для хранения типа адреса: default, subfolder или custom.
  • Добавлено публичное свойство \Tygh\Storefront\Storefront::$relative_path для хранения пути относительно адреса установки.
  • \Tygh\DataKeeper — параметры резервного копирования теперь принимают show_progress => false для неинтерактивных вызовов. Параметр поддерживают backup($params), backupFiles($params), backupDatabase($params, $backupper) и populateBackupParams($params). Статический метод restore($filename, $base_path = '', bool $show_progress = true) и защищённый статический метод restoreFile($source, $destination, bool $show_progress = true) принимают тот же флаг; по умолчанию показ хода выполнения включён. restoreFile() возвращает логическое значение. Ошибки копирования файлов или импорта SQL возвращают неудачу вместо успешного результата копирования или восстановления. backup() возвращает путь резервной копии или false; restore() возвращает true, false либо сообщение об ошибке. Подклассы, переопределяющие методы восстановления, должны принимать необязательный аргумент.
  • \Tygh\BackendMenu — группа type => 'title' сохраняет разрешённые subitems под заголовком без ссылки, если пользователь не может открыть собственный href группы. Группа без разрешённых ссылок удаляется. Отключённый active_option по-прежнему скрывает всю группу; обычные пункты меню сохраняют прежнюю проверку прав родителя.
  • \Tygh\SoftwareProductEnvironment — новый метод isMultivendor() определяет, является ли продукт маркетплейсом, аналогично fn_allowed_for('MULTIVENDOR'). Коду, получающему окружение (Tygh::$app['product.env']), больше не нужна собственная глобальная проверка редакции.
  • \Tygh\Web\Session — новое свойство $accept_session_id_from_request определяет, можно ли передавать идентификатор сессии в параметрах запроса. Новое свойство $is_read_only и метод isReadOnly() показывают, что запрос не владеет сессией: она чужая либо собственной нет. Запрос может только читать её: write(), save(), gc(), destroy(), regenerateID() и resetID() ничего не делают, cookie сессии не отправляется, сборщик мусора отключён. Так работает каждый запрос входного скрипта с обработчиком. Новый метод isWritable($session_id = '', $session_data = ''): bool проверяет зарегистрированные обработчики возможности записи и возвращает false для сессии только для чтения.
  • \Tygh\Tools\SecurityHelper — новый статический метод getObjectSanitizationRules($object_type) возвращает правила очистки полей объекта, применяемые также sanitizeObjectData().
  • \Tygh\Tools\Url — новый статический метод isLoopbackHost(string $host) проверяет, является ли хост localhost или IP-адресом loopback-интерфейса, 127.0.0.0/8 либо ::1; IPv6-адрес может быть заключён в скобки, как в URL.
  • \Tygh\Tools\Formatter — новый метод asDecimalPrice($price, string $currency_code): string форматирует цену для программ, например платёжных шлюзов и API: десятичное число с точкой, без символа валюты и разделителя тысяч, округлённое до числа знаков валюты, например 1234.50. Цена в основной валюте пересчитывается по курсу указанной валюты, как в asPrice().
  • \Tygh\Backend\Database\Pdo — insertId() возвращает целое число согласно IBackend и поведению драйвера MySQLi; расширение возвращает строку. Поэтому \Tygh\Database\Connection::query() возвращает идентификатор вставленной строки целым числом для обоих драйверов: раньше код с проверкой is_int() принимал сохранённую строку за несохранённую.
  • \Tygh\Tools\DateTimeHelper — новый статический метод createPeriodRelativeTo(\DateTimeImmutable $now, string $start_date_definition, string $end_date_definition) создаёт период относительно переданного момента, а не текущего времени сервера, например createPeriodRelativeTo($now, 'today -6 days', 'today 23:59:59'). Границы — объекты \DateTimeImmutable в часовом поясе магазина; неразбираемое определение вызывает \InvalidArgumentException. Новый статический метод addSeconds(\DateTimeImmutable $moment, int $seconds) сдвигает момент на точное число секунд, чего календарный интервал не гарантирует при переводе часов. getPeriod() и createCustomPeriod() работают как прежде.
  • \Tygh\Registry — новый статический метод setCacheScope(string $scope): void отделяет кэшированные данные процесса от других процессов с иным представлением магазина: после вызова все ключи читаются и сохраняются на уровне кэша с указанной областью, поэтому ранее прочитанные данные не должны зависеть от различий. Кэш по времени остаётся общим, а изменение таблицы делает недействительными кэшированные данные во всех областях.
  • \Tygh\Addons\AXmlScheme — новый метод requiresNewerPhp(string $php_version): bool по умолчанию возвращает false; XmlScheme2 и его потомки переопределяют метод для сравнения переданной версии с минимальной версией PHP схемы.
  • \Tygh\Addons\XmlScheme2 — защищённое статическое свойство $_required_pref_scheme удалено. checkRequirements() читает PRODUCT_VERSION, PRODUCT_EDITION и CS_PHP_VERSION только при проверке требований модуля, поэтому классы схем, включая XmlScheme3 и XmlScheme4, загружаются без этих констант: в PHP 8 неопределённая константа вызывает ошибку, а не предупреждение. Версии расширений PHP по-прежнему сравниваются строго; проверка больше не читает для них неопределённый ключ массива. Подклассы, добавлявшие собственные проверки через это свойство, должны реализовать их в checkRequirements().
  • \Tygh\Tools\ErrorHandler::handleException() передаёт ошибки скриптов REQUEST_HANDLER HTTP-приложению через новый защищённый статический метод answerFailedRequest($exception); см. “Приложение HTTP-процесса”. Если приложение ещё не создано, резервная обработка устанавливает статус 500 без вывода страницы ошибки магазина.
  • \Tygh\SmartyEngine\Extensions\TyghExtension::getOutputFilters() возвращает пустой список фильтров для скрипта REQUEST_HANDLER, поэтому поля CSRF и ссылки панели не добавляются на отдельные страницы.
  • \Tygh\Providers\CommonProvider::register() добавляет сервисы clock и backoffice.panel_url_builder; \Tygh\Providers\SessionProvider::register() задаёт два новых флага сессии для скриптов REQUEST_HANDLER.

Изменения в классах

Новые классы

  • Tygh\Enum\PrivilegeAccessStates — определяет ALLOW = 'Y', DENY = 'N' и NEUTRAL = '' для решений групп; эти состояния отличаются от флага forbidden в БД.
  • Tygh\Enum\PrivilegeAccessStates::fromForbiddenFlag(?string $forbidden): string — для существующей строки преобразует только точное Y в Deny, а любое другое значение, включая null, в Allow; отсутствие записи необходимо обработать до вызова.
  • Tygh\Enum\PrivilegeAccessStates::toForbiddenFlag(string $state): ?string — преобразует Allow в пустой флаг БД '', Deny в Y, а Neutral и неизвестные состояния в null, означающий отсутствие сохраняемой строки.
  • Tygh\Providers\PrivilegeServiceProvider::register(\Pimple\Container $app) — регистрирует сервис расчёта прав в контейнере как privileges.
  • Tygh\Providers\PrivilegeServiceProvider::getPrivilegeService(): \Tygh\Security\PrivilegeService — статический метод получения общего экземпляра сервиса для прикладных проверок; сохраняет отложенное создание и время жизни сервиса в контейнере.
  • Tygh\Security\PrivilegeService::__construct(\Tygh\Database\Connection $db, array $dependencies, array $usergroup_types, bool $improved_access_management = true, string $uncovered_access = 'forbidden', array $system_privileges = [], array $catalog = []) — получает зависимости расчёта прав явно; основные методы: getState(int $user_id, string $privilege): string, isAllowed(int $user_id, string $privilege, ?string $expected_user_type = null): bool, isRootAdministrator(int $user_id): bool, hasUnrestrictedVendorAccess(int $user_id): bool. Дополнительные методы hasUnrestrictedAccess(int $user_id): bool и hasExplicitPermission(int $user_id, string $privilege): bool различают прежний неограниченный доступ и явное разрешение без fallback. СП и каталог передаёт provider один раз на запрос. Снимки пользователей и решений групп хранятся только в памяти Registry текущего PHP-запуска, без регистрации постоянного кеша. Повторные проверки и другие экземпляры сервиса используют общий снимок, включая root и пустые результаты. Новый HTTP-запрос читает БД заново; активный запрос и долгоживущий CLI сохраняют загруженный снимок до конца своего контекста. Ручного метода сброса нет.

Изменённые классы

  • Tygh\Api\AEntity::isAccessable($method_name) поддерживает списки альтернатив в результате privileges() наряду со строкой и boolean.
  • Tygh\Api\Entities\Users проверяет конкретные типы и записи пользователей; общий допуск к методу не разрешает все типы аккаунтов. В create() административная область требует соответствующих прав, витринная допускает только покупателя C после проверки доступа к методу, неизвестная область отклоняется.
  • Installer\Setup::setupData() заполняет сессию установщика данными реального root перед установкой модулей, в том числе при повторном шаге; Installer\App регистрирует PrivilegeServiceProvider для общих проверок прав.
  • Tygh\Api\Entities\Usergroups добавляет поле forbidden_privileges; отсутствие поля при обновлении сохраняет соответствующий прежний список, переданный пустой список очищает его, конфликт с privileges разрешается в пользу запрета.
  • Tygh\Tools\SecurityHelper::shouldSanitizeUserHtml() при Improved и auto опирается на привилегию обхода HTML-санитизации; продавцу нужен явный grant СП/группы. При выключенном Improved сохраняется прежний auto Store Builder. Значения true и false задают базовое решение; хук should_sanitize_user_html может только принудительно включить санитизацию.
  • Tygh\Settings::updateValueById(...) допускает изменение двух настроек доступа только реальным root A; при Improved также защищает init_addons, чтобы массовое отключение модулей не обходило СП продавцов.
  • Tygh\Addons\VendorPrivileges\Privileges поддерживает списки альтернативных привилегий при разборе permissions-схем и исключает административные действия площадки из прав продавца; новый защищённый метод getPermissionNames($permissions) извлекает имена действий из вложенных списков и карт HTTP-методов.

Изменения в хуках

Новые хуки

  • fn_set_hook('ai_mcp_core_tools_search_products_includes', $includes); — позволяет модулям объявлять дополнительные связанные данные в схеме поиска товаров MCP, расширяя $includes.
  • fn_set_hook('ai_mcp_core_tools_search_products_post', $context, $arguments, $result); — позволяет модулям дополнять разрешённую страницу кратких данных товаров запрошенными связями своего модуля в $result.
  • fn_set_hook('ai_mcp_core_tools_update_feature_pre', $context, $feature_id, $feature_data); — позволяет модулям проверять или корректировать изменения характеристик перед их сохранением инструментом MCP.
  • fn_set_hook('ai_mcp_core_tools_update_promotion_pre', $context, $promotion_id, $promotion); — позволяет модулям защищать промоакции, жизненный цикл которых связан с другой сущностью платформы, перед изменением через MCP.
  • fn_set_hook('ai_mcp_server_instructions', $user, $instructions); — расширяет инструкции MCP-сервера для аутентифицированного \Tygh\Addons\AiMcpServer\Dialect\ExecutionContext\McpToolExecutionUserContext без загрузки каталога инструментов. Выполняется при создании сервера для запроса; изменяйте английскую строку $instructions по ссылке. Одни и те же инструкции доступны через initialize и server/discover.
  • fn_set_hook('access_tokens_revoke_post', $tokens); — выполняется после отзыва токенов доступа. Позволяет модулю, выпустившему токены, отозвать связанные данные, например подключение приложения. $tokens — объекты \Tygh\AccessTokens\AccessToken в состоянии после отзыва. О токене может быть сообщено дважды, если два запроса отзывают его одновременно, поэтому обработчик должен быть идемпотентным.
  • fn_set_hook('access_tokens_authenticate_post', $token, $is_refused); — выполняется при аутентификации запроса входного скрипта с помощью токена доступа, в первом стеке инициализации: $token — проверенный \Tygh\AccessTokens\AccessToken, а его владелец ещё не вошёл в систему. Позволяет модулю отклонить токен, например модулю, выпустившему его, когда соответствующий способ выпуска отключён. Хук доступен только неуправляемым модулям; обработчик может лишь выполнять запросы к базе данных.
  • fn_set_hook('access_tokens_deny_request', $request, $scopes, $reason, $response); — выполняется, когда ядро отклоняет запрос входного скрипта, принимающего токены доступа, перед отправкой отказа. Позволяет модулю протокола, выпускающего токены, описать причину отказа клиенту, например в параметрах запроса аутентификации Bearer, или вместо этого отправить другой ответ PSR-7, например общедоступный документ, сообщающий клиенту без токена, где его получить. Хук может выполняться уже в первом стеке инициализации, поэтому только неуправляемые модули получают все отказы.
  • fn_set_hook('should_sanitize_user_html', $result); — выполняется в \Tygh\Tools\SecurityHelper::shouldSanitizeUserHtml(), когда настройки магазина и права пользователя позволяют оставлять введённый пользователем HTML без изменений. Решение магазина и хук обрабатываются при каждом вызове. Позволяет модулю принудительно включить очистку для части запроса, например когда HTML поступает из источника, в котором пользователь не вводит его напрямую, такого как ИИ-ассистент. Хук не выполняется, если HTML и так очищается, поэтому обработчик не может отключить очистку.
  • fn_set_hook('ai_mcp_server_check_vendor_access', $company_id, $is_allowed); — позволяет модулям ограничивать доступ к MCP для компании продавца, например в зависимости от её текущего тарифного плана. Начальное значение $is_allowed — true; изменение на false запрещает доступ. Хук выполняется после проверки глобальных переключателей сервера и доступа продавцов и не может обойти права пользователя. Модуль vendor_plans обрабатывает его с помощью fn_vendor_plans_ai_mcp_server_check_vendor_access($company_id, &$is_allowed) и требует наличия флага ai_mcp_server в текущем плане. list_vendor_plans включает этот флаг в каждый план как логическое значение. Общая политика сервера проверяется один раз при построении списка инструментов; последующие проверки доступности заново считывают текущие ограничения продавца.
  • fn_set_hook('ai_mcp_server_diagnostics_checks', $checks, $now, $server_answer, $http_client); — выполняется после завершения диагностических проверок MCP-сервера. $checks — строки страницы диагностики, $now — момент выполнения проверок (\DateTimeImmutable), $server_answer — ответ публичного адреса MCP-сервера на запрос без токена: адрес, статус и заголовки; пока сервер отключён, значение равно null. $http_client (\Tygh\Addons\AiMcpServer\Capabilities\Diagnostics\SelfCheckHttpClient) обращается к публичным адресам магазина так же, как ИИ-клиенты. Позволяет модулю, участвующему в подключении, добавлять собственные проверки; создавайте строку с помощью \Tygh\Addons\AiMcpServer\Capabilities\Diagnostics\DiagnosticCheck.
  • fn_set_hook('ai_mcp_core_tools_get_inventory_report_post', $items, $report); — выполняется после поиска товаров для отчёта об остатках MCP-сервера. $items — товары отчёта с идентификаторами товаров в качестве ключей, $report — low_stock, out_of_stock или no_sales. Позволяет модулям добавлять собственные данные об остатках, например остатки на складах.
  • fn_set_hook('checkout_place_orders_post', $cart, $auth, $params, $order_id); — выполняется сразу после создания заказов при оформлении, пока корзина ещё содержит отправленные покупателем данные и до того, как оплата может передать управление запросом.

Изменённые хуки

  • fn_set_hook('sanitize_html', $config_instance, $raw_html); — сигнатура не изменилась, но теперь хук выполняется только один раз за запрос: SecurityHelper::sanitizeHtml() кеширует конфигурацию очистки, созданную для первого значения. Обработчик настраивает общий механизм очистки и не должен рассчитывать на получение каждого HTML-поля в $raw_html.
  • fn_set_hook('execute_as_company_after_restore_company_id', $action, $company_id); — сигнатура не изменилась; теперь хук выполняется из блока finally функции fn_execute_as_company(), в том числе если действие выбрасывает исключение. К моменту выполнения хука предыдущая компания и уровни кеша уже восстановлены.
- fn_set_hook('uninstall_addon_pre', $addon_name, $show_message, $allow_unmanaged, $execute_schema_queries);
+ fn_set_hook('uninstall_addon_pre', $addon_name, $show_message, $allow_unmanaged, $execute_schema_queries, $can_uninstall);

- fn_set_hook('update_addon_status_pre', $addon, $status, $show_notification, $on_install, $allow_unmanaged, $old_status, $scheme);
+ fn_set_hook('update_addon_status_pre', $addon, $status, $show_notification, $on_install, $allow_unmanaged, $old_status, $scheme, $can_update);

Новые последние флаги изначально true; обработчик может присвоить false по ссылке, чтобы отменить операцию до изменения данных. Модуль Vendor privileges использует их для защиты обязательной СП от отключения не-root. Существующие обработчики, не объявляющие дополнительный аргумент, сохраняют совместимость.

- fn_set_hook('check_permission_manage_profiles', $result, $user_type);
+ fn_set_hook('check_permission_manage_profiles', $result, $user_type, $action);

Параметр $action позволяет расширению различать просмотр (view) и управление (manage) профилями.

fn_set_hook('post_delete_user', $user_id, $user_data, $result) сохраняет сигнатуру; $user_data дополнительно содержит user_type, используемый проверками удаления.

Изменения в схемах

Новые схемы

  • permissions/privilege_dependencies — отображение идентификатора действия в список необходимых привилегий; расширения используют его для общей серверной проверки и интерфейса. update_order_details требует view_orders, но не edit_order; требование действует при выполнении и сохранении группы, включая прямые запросы небольших изменений.

Изменённые схемы

  • exim_data_feeds/* — необязательный ключ data_feed_field_groups задаёт первые группы источников в формате group_id => ['title' => 'language.key', 'fields' => [source_id => 'caption']]. Ключи fields, features, options зарезервированы. В группы попадают только доступные источники; строковые ключи, числовые ID и классы опций сохраняются. Google-схема помещает свою группу первой; характеристики старых установок без реестра ID остаются в обычной группе.
  • exim_data_feeds/google_export — признак is_google_export позволяет определить семейство Google-схем до начала экспорта. Метаданные google_export_mode задают режим Custom. Выбранный продавец хранится в params.google_export_company_id; режим определяется только layout_id, а не параметрами фида.
  • exim_data_feeds/general_data_feeds, exim_data_feeds/google_export — опция export_empty задаёт действие при отсутствии товаров: N сохраняет старый файл, Y создаёт CSV только с заголовком. По умолчанию Standard использует N, Google — Y.

В permissions/admin поле condition поддерживает карты GET/POST и оператор replace, результат которого заменяет проверку permissions. В карте condition отсутствие нужного метода даёт отказ; в карте permissions отсутствующий метод означает false. Условия могут запрашивать аргументы #request_variables и #user_id из явного контекста. Некорректный тип condition даёт правило отказа, а некорректный тип permissions приводится к false. Для выбранных действий profiles обработчик fn_check_profile_access() проверяет настоящую запись, тип и исключение собственного профиля; статические permissions сохраняются для каталога прав продавцов. Полный контракт описан в каноническом документе по ссылке ниже.

В ExIm дополнительное правило доступа задаётся в permissions.condition как массив с operator = and или or и function. and требует прав операции и истинного условия; or допускает права операции либо условие; путь через условие закрыт, если все альтернативы операции имеют итоговый явный запрет. При этом Forbidden обязательной зависимости также считается запретом альтернативы, нейтральное решение не запрещает путь через условие, а независимое разрешение не отменяется запретом другой альтернативы. Условие исполняется через fn_execute_permission_condition() с контекстом user_id из аргумента проверяющей функции. Ограничение редакции и запрет раздела компании не обходятся через or. Другие операторы, включая replace, и значение, не являющееся массивом, включая явный null, дают отказ. Для форматов с этим ключом учитывается запрет фактического section из vendor-схемы компании, а прямые fn_import() и fn_export() выполняют ту же проверку до обработки данных. Отсутствие ключа сохраняет прежнее поведение формата. Корневое поле condition остаётся SQL-условием. В exim/users новое условие требует exim_access; имена users в общей проверке не используются.

Изменения в базе данных

system_privileges(user_type, privilege, forbidden) хранит СП отдельно от групп, с составным первичным ключом (user_type, privilege). Движок таблицы — MyISAM; замена всей карты не атомарна. Формат forbidden совпадает с usergroup_privileges. СП не включается в API обычных групп и не создаёт назначений. Новые настройки Security глобальны: improved_access_management и privileges_not_covered_by_usergroups. При обновлении режим выключен, СП_A нейтральна, СП_V копируется из прежней выбранной группы модуля.

В usergroup_privileges добавлено forbidden CHAR(1) NOT NULL DEFAULT '': только точное Y означает явный запрет, любое другое значение существующей строки — разрешение, отсутствие строки — нейтральное решение. Для новых разрешений записывается ''; прежнее N, X и строчное y также читаются как разрешения. Старые строки и вставки без указания новой колонки сохраняют смысл разрешения. В форме и fn_update_usergroup() по-прежнему передаются состояния Y для разрешения и N для запрета; списки privileges и forbidden_privileges в API также не меняют формат.

Прямые SQL-потребители обязаны отличать разрешение от запрета: наличие строки больше не означает разрешённое действие. Для строк отдельной группы нужно исключать только точное Y с учётом регистра, например применяя PrivilegeAccessStates::fromForbiddenFlag() после проверки наличия строки. Нечувствительное к регистру SQL-сравнение с Y нарушает этот контракт для строчного y. Для прикладной авторизации пользователя следует использовать сервис или fn_check_user_access(), учитывающий запреты других групп и зависимости, а не объединять строки разрешений самостоятельно.

view_users и manage_users относятся к покупателям. Добавлены view_administrators, manage_administrators, install_addons_manually; в Multi-Vendor также view_vendor_administrators, manage_vendor_administrators.

Изменения в шаблонах

Новые хуки шаблонов

  • {hook name="access_tokens:scope_group"}{/hook} в design/backend/templates/views/access_tokens/components/issue_form.tpl — позволяет модулю показать подсказку после областей доступа одной группы. $scope_group содержит group (языковую переменную заголовка группы) и scopes (объявления областей доступа, включая id, name, description и requires). Этот хук относится к форме персонального токена; страница согласия OAuth отображает собственный выбор областей доступа.
  • product_data:back_in_stock_checkbox_label в design/themes/responsive/templates/views/products/subscription_form.tpl — обрамляет подпись флажка “Сообщить мне, когда товар появится в наличии”, чтобы модуль мог добавить к ней свой текст.
  • settings_fields:disable_input в design/backend/templates/common/settings_fields.tpl — позволяет модулю сделать поле настройки доступным только для чтения, присвоив $disable_input значение scope="parent".

Новые шаблоны

  • design/backend/templates/views/access_tokens/list.tpl отображает вкладку профиля; manage.tpl в том же каталоге отображает список в панели администрирования. Шаблоны components/issue_form.tpl, components/search_form.tpl и components/tokens_table.tpl предоставляют форму, фильтры и таблицу. $access_tokens содержит подготовленные контроллером массивы для представления, а не объекты AccessToken; каждая строка содержит status и сгруппированные access. Таблица принимает $show_user, $owners, $target_id и $redirect_url; $issued_access_token передаётся только в ответе, выпускающем токен. $access_token_issue_refusal_reason содержит языковой ключ сообщения, которое показывается вместо формы выдачи, если текущему владельцу запрещено выпускать токены, в том числе при обязательной смене пароля.
  • design/backend/templates/views/access_tokens/components/access_list.tpl отображает сгруппированные области доступа, переданные в $access, — результат ScopeRegistry::group(). Шаблон используется строками токенов ядра и подключениями OAuth.
  • В design/backend/templates/addons/ai_mcp_server/ шаблоны views/ai_mcp_server/connect.tpl, calls.tpl и diagnostics.tpl отображают инструкции по персональному подключению, журнал вызовов и диагностику. Журнал вызовов использует views/ai_mcp_server/components/calls_table.tpl и search_form.tpl. settings/server_url.tpl показывает публичную конечную точку. components/access_token_hint.tpl и hooks/access_tokens/scope_group.post.tpl добавляют подсказку MCP в форму токена; hooks/menu/profile_menu_extra_item.post.tpl добавляет ссылку на персональное подключение в меню профиля.
  • design/backend/templates/addons/oauth_server/views/oauth_server/authorize.tpl отображает отдельную страницу согласия, ожидания или ошибки на основе $oauth_server_step и $oauth_server_page. connections.tpl в том же каталоге отображает вкладку подключённых приложений. Отдельная страница авторизации не использует макет панели и её фильтры вывода.
  • Шаблоны модуля MCP addons/vendor_plans/hooks/vendor_plans/vendor_plans_params.post.tpl и update_restrictions.post.tpl в корневом каталоге шаблонов панели администрирования отображают его флаг тарифного плана продавца. Соответствующий design/themes/responsive/templates/addons/ai_mcp_server/addons/vendor_plans/hooks/vendor_plans/vendor_plan_params.post.tpl отображает его в карточках планов на витрине. Эти шаблоны реализуют существующие хуки модуля “Тарифные планы для продавцов”.
  • views/usergroups/system_privileges.tpl — общий modal системной карты; root редактирует, остальные видят отключённые элементы и Close.
  • views/usergroups/components/system_usergroup.tpl — ссылка просмотра и заголовок окна используют system_administrator_usergroup (“Default administrator privileges”) / system_vendor_usergroup (“Default vendor privileges”), метка без статуса назначения — system_group (“System group”); параметр system_usergroup_link_class позволяет общему списку передать link--monochrome, в профиле сохраняется синий цвет. Класс system-usergroup в таблицах использует минимальную высоту штатных элементов управления.

Удалённые хуки

  • design/themes/responsive/templates/addons/gdpr/hooks/checkout/edit_profile_fields.post.tpl — удалён; переопределения этого шаблона больше не применяются.
  • design/themes/responsive/templates/addons/gdpr/hooks/product_data/back_in_stock_email.post.tpl — удалён; согласие на обработку персональных данных теперь является частью подписи флажка подписки, а не отдельным флажком.

Изменённые шаблоны

  • views/access_tokens/components/tokens_table.tpl и addons/oauth_server/views/oauth_server/connections.tpl проверяют POST-разрешение на отзыв для конкретного владельца перед выводом общей кнопки, в том числе для неограниченных администраторов в прежнем режиме управления доступом. Переопределения должны сохранять эту проверку, URL действия и AJAX target.
  • addons/data_feeds/views/data_feeds/update.tpl, addons/vendor_data_premoderation/hooks/data_feeds/additional_options.pre.tpl — блок datafeed_additional_options обновляется при смене типа фида. Переменная datafeed_exclude_products_default задаёт начальное состояние исключения выключенных и неодобренных товаров только для нового фида; сохранённые настройки и ручной выбор между Google-типами сохраняются.
  • addons/google_export/hooks/data_feeds/feed_type_details.post.tpl — выбор продавца в Single-seller обёрнут в cm-field-container inline-block, чтобы штатный валидатор показывал сообщение обязательного поля справа от выбора продавца.
  • views/storefronts/components/picker/presets.tpl — ссылки логотипов витрин и “Все витрины” удаляют одноразовый параметр meta_redirect_url из текущего URL перед переключением витрины. Сторонним переопределениям шаблона следует учитывать эту очистку.
  • views/usergroups/manage.tpl, views/profiles/update.tpl — системные строки перед обычными группами; СП передаётся отдельно от usergroups.
  • addons/vendor_privileges/addons/vendor_plans/components/select_vendor_plans_usergroups.tpl — при Improved показывает СП вместо обязательного выбора старой default-группы.
  • views/usergroups/components/privileges_group.tpl — вместо checkbox действия используется select с двумя состояниями при legacy и тремя при Improved и данными о зависимостях; переопределения должны передавать Y, N или пустое значение.
  • views/usergroups/components/privileges_access_level_controls.tpl, privileges_section.tpl и get_privileges.tpl — добавлен Forbidden, режимы выводятся по состояниям отдельных действий; для подписи запрета используется privilege.forbidden.
  • views/profiles/manage.tpl, views/profiles/components/profiles_account.tpl, addons/suppliers/views/suppliers/manage.tpl — элементы просмотра и управления используют права конкретного типа пользователя.
  • views/addons/components/manage/manage_buttons.tpl — загрузка архива зависит от install_addons_manually.

Удалённые шаблоны

  • addons/product_reviews/hooks/usergroups/general_content.post.tpl — отдельная загрузка скрипта зависимостей привилегий отзывов заменена общей схемой; удалён js/addons/product_reviews/backend/usergroup_privileges.js.

Полный контракт состояний, контекстных исключений, доверенных назначений и миграции описан в каноническом документе о привилегиях.

Изменения в модулях

access_restrictions

  • fn_access_restrictions_deny_access($message) — завершает запрос, запрещённый ограничением доступа. Запрос входного скрипта, обслуживаемого обработчиком запросов, получает отказ приложения со статусом 403.
  • fn_domain_is_blocked($domain) и fn_access_restrictions_user_init(&$auth, &$user_info) используют этот отказ для заблокированных доменов, IP-адресов и ограничений по обратному определению IP. Обычные страницы, обрабатываемые диспетчером, сохраняют текстовый отказ.

full_page_cache

  • Новый fn_full_page_cache_get_entry_script() возвращает \Tygh\Addons\EntryScript для корневого скрипта esi.php.
  • fn_full_page_cache_install(), fn_full_page_cache_uninstall() и \Tygh\Addons\FullPageCache\Addon::canBeEnabled() используют этот объект для управления входным скриптом и его проверки. При установке создаётся относительная символическая ссылка и сообщается о конкретных ошибках файловой системы; обычный файл администратора сохраняется. При удалении модуля удаляется только ссылка с относительным путём назначения модуля; копии и другие ссылки остаются без изменений.

ai_mcp_server

Новый модуль “MCP-сервер” (ai_mcp_server) подключает ИИ-ассистентов к магазину по протоколу Model Context Protocol: он предоставляет сервер и основу для инструментов MCP. Сам модуль содержит только служебный инструмент MCP get_store_context; инструменты MCP для данных магазина поставляются с модулем ai_mcp_core_tools, а любой другой модуль регистрирует собственные инструменты таким же образом. Модуль требует PHP 8.2 или новее и использует синтаксис этой версии; библиотеки протокола находятся в app/addons/ai_mcp_server/lib/vendor и загружаются адаптером протокола по мере необходимости.

  • Входной скрипт mcp.php — символическая ссылка из корневого каталога магазина на app/addons/ai_mcp_server/mcp.php. Он обслуживается обработчиком запросов модуля (addons.ai_mcp_server.request_handler), а его запросы аутентифицируются токенами доступа с областью mcp:read или mcp:write. Модуль объявляет обе области; для изменения данных требуется доступ на чтение.
  • Транспорт — Streamable HTTP с ответами JSON. Поддерживаются как initialize с сессиями протокола, принадлежащими пользователю, так и server/discover без сохранения состояния. Сессии протокола отделены от сессий панели и истекают после 24 часов бездействия. Сервер предоставляет инструменты; ресурсы, промпты, автодополнение и управляемое клиентом логирование не поддерживаются. Запросы с непустым заголовком Origin отклоняются со статусом 403.
  • После установки server_enabled и allow_vendors отключены. allow_changes включён по умолчанию, allow_deletions отключён, а значение personal_data_masking по умолчанию — partial. Настройка mcp_tool_groups управляет аналитикой, каталогом, заказами, маркетплейсом и контентом; служебная группа всегда включена, а маркетплейс доступен только в Multi-Vendor.
  • Модуль не зависит от модуля oauth_server: ИИ-клиенты подключаются с помощью персональных токенов доступа, а при активном модуле OAuth — также через OAuth. Протокол OAuth, включая метаданные защищённого ресурса (RFC 9728), относится к oauth_server: MCP-сервер о нём ничего не знает.
  • Новая привилегия “Использование MCP” (use_ai_mcp_server) для групп пользователей администраторов и продавцов.
  • Карточка Настройки → Сервер MCP открывает вкладку Настройки модуля и предоставляет доступ к журналу вызовов (ai_mcp_server.calls) и диагностике (ai_mcp_server.diagnostics) через стандартное меню subitems. Карточка использует описанные выше права для групп заголовков: разрешённые дочерние ссылки остаются под заголовком без ссылки для пользователей, которые не могут редактировать модули. Инструкции по персональному подключению (ai_mcp_server.connect) появляются как Подключить ИИ-ассистента в меню профиля через существующий хук шаблона menu:profile_menu_extra_item, пока MCP доступен текущему пользователю. Администратор с правом настройки модулей получает ссылку на настройки, если открывает инструкции при недоступном MCP. Инструкции и журнал доступны администратору и продавцу: пользователи с правом чтения журналов магазина видят вызовы всех пользователей, продавец — вызовы компании, остальные — собственные вызовы. Диагностика доступна только администратору и показывает названия и описания инструментов, а также локализованные названия модулей. Продавцу нужна привилегия “Использование MCP” для обеих страниц: одного права чтения журналов недостаточно для доступа продавца к журналу компании.
  • Представление персонального подключения (design/backend/templates/addons/ai_mcp_server/views/ai_mcp_server/connect.tpl) содержит URL сервера, инструкции по входу через OAuth, заголовок с персональным токеном, ссылку на собственные токены пользователя и примеры запросов для администраторов, продавцов и их сотрудников. Возможности ассистента ограничены правами учётной записи и доступом, предоставленным при подключении.
  • Новые таблицы: ai_mcp_server_calls (журнал вызовов) и ai_mcp_server_mcp_protocol_sessions (сессии протокола MCP). Журнал вызовов сохраняет, кто вызвал какой инструмент MCP, аргументы, отфильтрованные согласно настроенному уровню маскирования, статус и ошибку, длительность и факт возврата немаскированных персональных данных. Результат никогда не сохраняется: результаты содержат данные покупателей, и журнал не должен становиться ещё одним местом их хранения.
  • Модуль самостоятельно удаляет вызовы старше значения настройки “Хранить журнал вызовов, дней” и неактивные сессии протокола не чаще одного раза в сутки при обработке запросов сервером (ключ хранилища ai_mcp_server_next_cleanup). Настраивать плановую задачу не требуется.
  • Настройка “Разрешить удаление через MCP” (allow_deletions) на вкладке Инструменты, отключённая по умолчанию. Инструменты MCP, удаляющие объекты, доступны только при её включении вместе с настройкой “Разрешить изменения через MCP”.
  • Инструменты MCP, работающие с данными витрины, принимают аргумент storefront_id: вызов выполняется в контексте витрины (fn_execute_as_storefront()), к которой у пользователя должен быть доступ.
  • Страница диагностики проверяет сам MCP-сервер и запрашивает проверки у модулей, участвующих в подключении, через хук ai_mcp_server_diagnostics_checks. Хук получает ответ сервера на запрос без токена (null, пока сервер отключён) и HTTP-клиент самопроверки. \Tygh\Addons\AiMcpServer\Capabilities\Diagnostics\DiagnosticCheck создаёт строку страницы: create() — обычную строку, answer() — строку с результатом проверки ответа публичного адреса ИИ-клиентам. DiagnosticCheck::STATUS_INFO обозначает информационный результат. Таким образом модуль oauth_server добавляет проверки своего входного скрипта, вспомогательного компонента и обнаружения, поэтому модули не знают о файлах, настройках и ключах хранилища друг друга. При самопроверке сервера ожидается отказ магазина на запрос без токена: статус 401 и запрос аутентификации по схеме Bearer без тела ответа.
  • Диагностика привилегий показывает явные правила MCP для поддерживаемых типов учётных записей администраторов и продавцов, а также их активных или скрытых групп пользователей; эффективный доступ отдельных пользователей не рассчитывается. При включённом улучшенном управлении доступом любой явный системный или групповой запрет вызывает предупреждение. Если запретов нет, явное разрешение для каждого поддерживаемого типа учётной записи даёт результат OK, а неполный набор явных разрешений — информационный результат. В прежнем режиме учитываются только разрешения обычных групп: системные решения и запреты игнорируются, поэтому результат бывает OK или информационным, но не предупреждением о запрете. Последние два аргумента конструктора \Tygh\Addons\AiMcpServer\Capabilities\Diagnostics\DiagnosticsEnvironment обязательны: $improved_access_management и $system_privileges — карта системных решений MCP по типам учётных записей.
  • Вызовы с витриной выбирают её через штатный контекст панели и проверяют точный идентификатор и доступ пользователя. В Store Builder новые общие объекты получают компанию этого контекста через штатную схему совместного использования.

Регистрация инструментов MCP

Модули регистрируют инструменты MCP в файле schemas/ai_mcp_server/mcp_tools.post.php. Ключ схемы — имя инструмента MCP:

$schema['my_addon_get_things'] = [
    'class'   => \Tygh\Addons\MyAddon\McpTools\GetThingsMcpTool::class, // created with the services of the base class only
];
$schema['my_addon_update_thing'] = [
    'factory' => static function (\Tygh\Application $app) {             // or created by a factory
        return new \Tygh\Addons\MyAddon\McpTools\UpdateThingMcpTool(
            $app['addons.ai_mcp_server.mcp_tool_exec_services'],
            $app['db']
        );
    },
];

return $schema;

Ключ схемы — имя инструмента MCP, а схема объединяется, как и любая другая: модуль может объявить имя, уже используемое другим модулем, и полностью заменить этот инструмент MCP — класс, а вместе с ним требования, входную схему и поля персональных данных заменяемого инструмента MCP. Замена разрешена, как и для любой переопределяемой схемы платформы, но не происходит незаметно: в журнал магазина добавляется запись с названиями модулей, объявляющих одно и то же имя инструмента MCP, а таблица Установленные инструменты в диагностике модуля перечисляет все инструменты MCP с обслуживающими их классами и модулями, которым принадлежат классы. Проверяйте их, если инструмент MCP ведёт себя не так, как зарегистрированный вами.

Пространство имён модуля указывает назначение класса. \Tygh\Addons\AiMcpServer\Dialect описывает инструменты MCP: интерфейс, определение, группу (McpToolGroup), классы персональных данных (PersonalDataClass), требования, результат и исключение инструмента MCP. Dialect\BaseImpl содержит базовые классы и их сервисы, Dialect\ExecutionContext — контекст вызова: момент времени и пользователя. \Tygh\Addons\AiMcpServer\Capabilities содержит сервисы модуля; инструмент MCP может принимать два из них в конструкторе: Capabilities\ContentSafety\ContentGuard и Capabilities\AdminPanel\PanelPermissions. \Tygh\Addons\AiMcpServer\SdkOrchestration адаптирует библиотеку протокола MCP; инструменты MCP никогда от него не зависят.

Инструмент MCP реализует \Tygh\Addons\AiMcpServer\Dialect\McpToolInterface и соблюдает его нативные типы параметров и возвращаемых значений. Модуль, поддерживающий минимальную версию PHP платформы, может сохранять соответствующий синтаксис в собственных классах MCP, но загружает их только через эту интеграцию, когда ai_mcp_server активен на PHP 8.2 или новее. Код, загружающий классы MCP иным способом, должен объявить соответствующую зависимость от модуля.

  • getName(): string — стабильное имя в формате snake_case, равное ключу схемы. McpToolRegistry::NAME_PATTERN требует, чтобы первым символом была строчная латинская буква, за которой следуют не более 63 строчных букв, цифр или подчёркиваний. Входная JSON Schema должна объявлять type: object; некорректные объявления вызывают \Tygh\Exceptions\DeveloperException.
  • getDefinition(): McpToolDefinition — \Tygh\Addons\AiMcpServer\Dialect\McpToolDefinition: название и описание на английском языке, JSON Schema аргументов, группа инструмента MCP (\Tygh\Addons\AiMcpServer\Dialect\McpToolGroup) и аннотации (читает ли инструмент MCP данные, изменяет существующие данные и является ли идемпотентным).
  • getRequirements(): McpToolRequirements — \Tygh\Addons\AiMcpServer\Dialect\McpToolRequirements: эквивалентные действия панели администратора, разрешение использования инструмента MCP продавцами, признак удаления объектов ($is_deletion, третий аргумент конструктора) и способ работы инструмента MCP с витринами ($storefront_mode, четвёртый аргумент: константы STOREFRONT_NONE, STOREFRONT_OPTIONAL и STOREFRONT_REQUIRED). Инструмент MCP разрешён, если пользователь может выполнить хотя бы одно из действий в панели администратора; действия проверяются схемами прав панели в контексте действия. Инструмент MCP, удаляющий объекты, должен быть объявлен разрушающим и доступен только при разрешённом удалении через MCP. Инструмент MCP, работающий с витринами, объявляет аргумент storefront_id: механизм вызова проверяет доступ пользователя к витрине и выполняет вызов в её контексте. В режиме STOREFRONT_REQUIRED пользователь, управляющий всеми витринами магазина, в котором объекты принадлежат витринам, должен передать витрину, поскольку панель администратора просит такого пользователя выбрать её. Каждое действие панели принимает controller, mode, необязательный method (по умолчанию GET), типичные params и arguments — соответствие имён параметров запроса панели именам аргументов MCP. При построении списка используются типичные параметры; при вызове проверка повторяется с фактическими значениями аргументов. Пустой список действий не требует прав панели. Режим витрины требует как действия панели, так и входного свойства storefront_id.
  • getPersonalDataFields(): array — пути полей результата с персональными данными и их классы (\Tygh\Addons\AiMcpServer\Dialect\PersonalDataClass), например ['orders.*.email' => PersonalDataClass::Email]. Пути с разделителем-точкой используют * для каждого элемента списка. \Tygh\Addons\AiMcpServer\Capabilities\ContentSafety\PersonalDataMaskingLevel (Full, Partial, None) управляет фильтрацией; зарезервированные ключи из PersonalDataFilter::SECRET_KEYS рекурсивно удаляются на всех уровнях. В полях свободного текста при включённом маскировании фильтруются адреса электронной почты и номера телефонов. Новые инструменты должны объявлять собственные поля персональных данных.
  • execute(McpToolExecutionContext $context, array $arguments): McpToolResult — контекстом служит \Tygh\Addons\AiMcpServer\Dialect\ExecutionContext\McpToolExecutionContext; возвращает \Tygh\Addons\AiMcpServer\Dialect\McpToolResult или выбрасывает \Tygh\Addons\AiMcpServer\Dialect\McpToolException с сообщением для ИИ-ассистента. Инструмент MCP самостоятельно проверяет принадлежность объектов продавцам, как это делают контроллеры панели администратора. Инструмент MCP никогда не получает текущее время самостоятельно: McpToolExecutionContext::getCalledAt() — момент вызова (\DateTimeImmutable), и “сегодня” и “N дней назад” отсчитываются от него, чтобы все периоды одного вызова рассчитывались от одного момента, сохранённого в журнале вызовов. McpToolExecutionContext::getPanelUrl(string $url): string создаёт ссылку на панель владельца; его getUser() предоставляет сессию, идентификационные данные, области доступа, токен и язык через McpToolExecutionUserContext. McpToolExecutionUserContext::hasScope(Scope $scope): bool использует \Tygh\Addons\AiMcpServer\Capabilities\Access\Scope: Read (mcp:read) и Write (mcp:write).

McpToolException::invalidArguments(string $message): self, notFound(string $message): self и accessDenied(string $message): self создают ошибки для некорректных входных данных, недоступных объектов и отказа в доступе. Их сообщения поступают ассистенту после фильтрации текста; getType(): string отличает отказ в доступе от других ошибок в журнале вызовов.

Инструменты MCP вызываются через \Tygh\Addons\AiMcpServer\Capabilities\Invocation\McpToolInvoker::invoke(), который проверяет доступ, принудительно очищает HTML для инструментов MCP, изменяющих данные, маскирует персональные данные и записывает вызов в журнал. Аргументы поступают уже проверенными по входной схеме: их проверяет библиотека протокола MCP, а клиент получает некорректные аргументы как результат инструмента MCP с ошибкой согласно спецификации MCP для ошибок проверки входных данных. Такие отклонённые вызовы также попадают в журнал: \Tygh\Addons\AiMcpServer\Capabilities\CallLog\CallRecorder::recordRejected(). pattern входной схемы должен соответствовать подмножеству регулярных выражений, рекомендуемому документацией JSON Schema, поскольку клиенты компилируют схему собственными движками; более сложные ограничения проверяйте в инструменте MCP. При прямом вызове McpToolInvoker::invoke() вызывающая сторона должна проверить аргументы по схеме инструмента до вызова.

Инструменты MCP, изменяющие данные, никогда не допускают незаметного удаления текста при очистке. \Tygh\Addons\AiMcpServer\Capabilities\ContentSafety\ContentGuard заранее проверяет поля схем security/object_sanitization (checkObjectData()), а поля без схемы — по типу, объявленному инструментом MCP (checkHtml(), checkText()):

  • HTML с опасными элементами, обработчиками событий, неразрешёнными атрибутами data-* или исполняемыми конструкциями URL/CSS отклоняется, а сообщение указывает соответствующую разметку;
  • HTML, который механизм очистки перестроил бы с потерей видимого текста, отклоняется;
  • HTML, который механизм очистки только нормализовал бы — закрыл тег, удалил неправильно расположенный тег, атрибуты оформления или отфильтрованные свойства стиля, — принимается. Сохраняется очищенное значение: checkHtml() возвращает его, а поля схемы в любом случае очищаются ядром. McpToolInvoker добавляет уведомления о нормализованной разметке в результат вызова как markup_notices, с предварительным просмотром нормализованного значения;
  • поля обычного текста не принимают HTML-теги.

checkNoMaskedPersonalData() отклоняет замаскированные персональные данные. Базовый класс \Tygh\Addons\AiMcpServer\Dialect\BaseImpl\AbstractMcpTool преобразует ошибки, о которых функции ядра сообщают уведомлениями, в ошибки инструмента MCP: resetCoreNotifications(), getCoreErrors() и createCoreError(). Он также предоставляет getIntListArgument() (список идентификаторов объектов из аргументов: положительные целые числа без повторов), checkCategoriesExist(), isDate() (проверку даты в формате YYYY-MM-DD вне поля схемы формата date), isStorefrontAvailable() и isStoreBuilderObjectAvailable() (границы доступа к объектам панели администратора), isStoreBuilderCustomerAvailable() (границу доступа к общим покупателям Store Builder), isOrderAvailable() (передаёт полное правило витрины, компании и продавца в PanelPermissions), getPeriod(array $arguments, $default_days, \DateTimeImmutable $now) (период аргументов period_from и period_to, который по умолчанию заканчивается в день указанного момента) и getDaysAgoStart($days, \DateTimeImmutable $until) (начало периода заданной длины, заканчивающегося в день указанного момента). Обе функции принимают момент вызова и считают дни в часовом поясе магазина с помощью \Tygh\Tools\DateTimeHelper::createPeriodRelativeTo(). formatMoney($value) форматирует сумму в основной валюте для результата: число округляется до количества десятичных знаков валюты с помощью \Tygh\Tools\Formatter::asDecimalPrice(), как при отображении суммы в магазине. Форматируйте таким образом каждую сумму результата и указывайте в результате валюту: суммы инструментов MCP выражены в основной валюте.

Вспомогательные методы базового класса получают сервисы через его конструктор: \Tygh\Addons\AiMcpServer\Dialect\BaseImpl\McpToolExecServices, сервис addons.ai_mcp_server.mcp_tool_exec_services. Сервисы передаются одним аргументом, поэтому добавление нового сервиса вспомогательных методов не меняет конструкторы инструментов MCP. PanelPermissions — четвёртая зависимость конструктора, доступная через getPanelPermissions(); инструменты заказов и RMA совместно используют его полное правило isOrderAvailable(). Набор также предоставляет продукт, на котором работает магазин: getProductEnvironment() базового класса возвращает \Tygh\SoftwareProductEnvironment, и инструмент MCP запрашивает у него, является ли магазин маркетплейсом, вместо получения флага редакции через конструктор. Инструмент MCP с собственным конструктором принимает этот аргумент первым и передаёт его родительскому конструктору, а его фабрика передаёт сервис. Инструмент MCP, объявленный через класс, получает сервис из реестра как единственный аргумент конструктора.

\Tygh\Addons\AiMcpServer\Dialect\BaseImpl\AbstractDeleteMcpTool — базовый класс инструментов MCP, удаляющих объект: он получает идентификатор из аргументов, отклоняет вызов, если объект не найден, вызывает удаление подкласса и возвращает удалённый объект и ссылку на список в панели администратора. Подкласс задаёт свой объект в константах ID_ARGUMENT, OBJECT_LABEL, RESULT_KEY и LIST_DISPATCH и реализует findObject() и deleteObject().

Сервисы

  • Tygh::$app['addons.ai_mcp_server.access_policy'] (\Tygh\Addons\AiMcpServer\Capabilities\Access\AccessPolicy) — правило доступа к MCP-серверу: тарифный план лицензии, переключатель сервера, тип пользователя, настройка для продавцов, ограничения компании и привилегия. isAvailableTo($session) сообщает, может ли пользователь сессии использовать сервер. areChangesAllowed() и areDeletionsAllowed() сообщают, разрешены ли инструменты MCP, изменяющие и удаляющие данные. Конструктор принимает необязательный последний аргумент ?\Closure $vendor_access_checker = null, вызываемый с идентификатором компании продавца; некорректная или отсутствующая компания приводит к отказу. Провайдер использует этот обработчик для запуска хука ai_mcp_server_check_vendor_access.
  • Tygh::$app['addons.ai_mcp_server.content_guard'] (\Tygh\Addons\AiMcpServer\Capabilities\ContentSafety\ContentGuard) — проверяет текст, который инструменты MCP собираются записать.
  • Tygh::$app['addons.ai_mcp_server.logger'] (\Tygh\Logging\StoreLogger, PSR-3) — записывает ошибки сервера MCP и его библиотеки протокола в журнал магазина (тип general, действие runtime) без данных запроса; адреса электронной почты и номера телефонов удаляются из сообщений.
  • Tygh::$app['addons.ai_mcp_server.mcp_tool_registry'] (\Tygh\Addons\AiMcpServer\Capabilities\Invocation\McpToolRegistry) и Tygh::$app['addons.ai_mcp_server.mcp_tool_invoker'] (\Tygh\Addons\AiMcpServer\Capabilities\Invocation\McpToolInvoker) — инструменты MCP схемы ai_mcp_server/mcp_tools и их вызовы. Реестр создаёт объект инструмента MCP только при необходимости: getMcpTool($name) создаёт один инструмент MCP, и только getMcpTools() создаёт их все. Tygh::$app['addons.ai_mcp_server.mcp_tool_availability'] (\Tygh\Addons\AiMcpServer\Capabilities\Invocation\McpToolAvailability) определяет, какие инструменты MCP может вызывать пользователь: findAvailableMcpTool($user, $name) проверяет один инструмент MCP, а getAvailableMcpTools($user) — каждый зарегистрированный инструмент MCP.
  • Tygh::$app['addons.ai_mcp_server.mcp_tool_inventory'] (\Tygh\Addons\AiMcpServer\Capabilities\Invocation\McpToolInventory) — getMcpTools(): array выводит зарегистрированные инструменты MCP с сортировкой по имени. Каждая строка содержит name, title, description, class и addon для активной реализации; addon равен null, если класс находится вне каталога модуля.
  • Tygh::$app['addons.ai_mcp_server.model_write_scope'] (\Tygh\Addons\AiMcpServer\Capabilities\ContentSafety\ModelWriteScope) — часть запроса, в которой данные, сохраняемые функциями ядра, поступают от модели. execute($action) выполняет действие внутри неё, и там модуль принудительно включает очистку введённого пользователем HTML через хук should_sanitize_user_html независимо от прав пользователя и настроек магазина. McpToolInvoker выполняет внутри неё каждый инструмент MCP, изменяющий данные.
  • \Tygh\Addons\AiMcpServer\Dialect\McpToolResult содержит как данные инструмента MCP, так и сообщение о неудачном вызове: инструмент MCP возвращает данные, а McpToolInvoker::invoke() возвращает тот же класс с заполненными isError() и getError().
  • Tygh::$app['addons.ai_mcp_server.prompt_prose'] (\Tygh\Addons\AiMcpServer\Capabilities\Prose\PromptProse) — все тексты, которые отправляет сам MCP-сервер: инструкции сервера, описания общих аргументов инструментов MCP, сообщения об отклонённых и неудачных вызовах и ошибки протокола. Для каждого сценария предусмотрен отдельный метод; значения, определённые кодом, такие как формат даты и имена аргументов, передаются в аргументах. Эти тексты являются промптами, поэтому написаны на английском языке и не являются языковыми переменными. AbstractMcpTool получает сервис среди сервисов конструктора и предоставляет подклассам через getPromptProse(). Инструменты MCP других модулей определяют собственные тексты. Инструкции сервера требуют от ассистента обращаться к соответствующей документации продукта перед объяснением сущностей, поведения или настроек либо планированием изменений, ссылаться на использованные страницы и отмечать утверждения, которые не удалось проверить. URL документации поступает из config.resources.docs_url: настроенные адреса сохраняются; заполнитель x.x.x в исходном коде преобразуется в ту же серию документации major.minor.x, что и в дистрибутивах. Текущие возможности магазина и права всё равно необходимо подтверждать через инструменты. Значения, упомянутые в текстах, являются константами: AbstractMcpTool::DATE_NOTATION, AbstractMcpTool::PERIOD_FROM_ARGUMENT, AbstractMcpTool::PERIOD_TO_ARGUMENT, McpToolRequirements::STOREFRONT_ARGUMENT и \Tygh\Addons\AiMcpServer\McpTools\Service\GetStoreContextMcpTool::NAME.
  • Tygh::$app['addons.ai_mcp_server.personal_data_filter'] (\Tygh\Addons\AiMcpServer\Capabilities\ContentSafety\PersonalDataFilter) — маскирование персональных данных в результатах инструментов MCP.
  • Tygh::$app['addons.ai_mcp_server.panel_permissions'] (\Tygh\Addons\AiMcpServer\Capabilities\AdminPanel\PanelPermissions) — права текущего пользователя в панели администратора. isAllowed($controller, $mode, $method = 'GET', array $params = []) проверяет ещё одно действие текущего пользователя по схемам прав панели, например когда инструмент MCP изменяет данные, которые панель изменяет отдельным действием с собственной привилегией. findStorefront($storefront_id) получает витрину, с которой может работать пользователь, isStorefrontAvailable() проверяет доступ к витрине так же, как панель администратора, а isStorefrontRequired() сообщает, должен ли пользователь выбрать витрину для работы с принадлежащими витринам объектами. Контекст запроса действия панели, необходимый для проверок и вызовов, воспроизводится через \Tygh\Addons\AiMcpServer\Capabilities\AdminPanel\PanelRequestEmulator (Tygh::$app['addons.ai_mcp_server.panel_request_emulator']), включая dispatch в контролируемых параметрах запроса. После вызова предыдущий контекст запроса восстанавливается; инструменты MCP не используют эмулятор напрямую.

ai_mcp_core_tools

Новый модуль “MCP-сервер: инструменты магазина” (ai_mcp_core_tools) добавляет к MCP-серверу инструменты для данных магазина: каталога, заказов и покупателей, контента витрины, продавцов маркетплейса и аналитики продаж, а также локальных резервных копий магазина. Модулю принадлежат инструменты, сервисы аналитики с ограничением области данных и их регистрация в schemas/ai_mcp_server/mcp_tools.post.php и schemas/ai_mcp_server/mcp_tools_multivendor.post.php; он требует PHP 8.2 или новее и модуль ai_mcp_server. Пока он отключён, MCP-сервер продолжает работать с инструментами MCP других модулей.

Зарегистрированные инструменты MCP

Все перечисленные ниже инструменты и классы реализации — новые. Имена классов в таблице указаны относительно \Tygh\Addons\AiMcpCoreTools\McpTools\; регистрация находится в двух схемах выше. Схема маркетплейса загружается только в Multi-Vendor. Фактическая доступность инструментов также зависит от пользователя, областей доступа и настроек сервера.

Инструмент MCP Класс реализации
get_abandoned_carts Analytics\GetAbandonedCartsMcpTool
get_analytics_capabilities Analytics\GetAnalyticsCapabilitiesMcpTool
get_customer_analytics Analytics\GetCustomerAnalyticsMcpTool
get_financial_report Analytics\GetFinancialReportMcpTool
get_inventory_report Analytics\GetInventoryReportMcpTool
get_order_status_overview Analytics\GetOrderStatusOverviewMcpTool
get_product_analytics Analytics\GetProductAnalyticsMcpTool
get_sales_details Analytics\GetSalesDetailsMcpTool
get_sales_report Analytics\GetSalesReportMcpTool
bulk_update_products Catalog\BulkUpdateProductsMcpTool
create_category Catalog\CreateCategoryMcpTool
create_feature Catalog\CreateFeatureMcpTool
create_product Catalog\CreateProductMcpTool
create_product_filter Catalog\CreateProductFilterMcpTool
create_product_option Catalog\CreateProductOptionMcpTool
delete_category Catalog\DeleteCategoryMcpTool
delete_feature Catalog\DeleteFeatureMcpTool
delete_product Catalog\DeleteProductMcpTool
delete_product_filter Catalog\DeleteProductFilterMcpTool
delete_product_option Catalog\DeleteProductOptionMcpTool
get_category Catalog\GetCategoryMcpTool
get_feature Catalog\GetFeatureMcpTool
get_feature_configuration Catalog\GetFeatureConfigurationMcpTool
get_product Catalog\GetProductMcpTool
get_product_filter Catalog\GetProductFilterMcpTool
get_product_option Catalog\GetProductOptionMcpTool
list_categories Catalog\ListCategoriesMcpTool
list_customer_groups Catalog\ListCustomerGroupsMcpTool
list_features Catalog\ListFeaturesMcpTool
list_product_filters Catalog\ListProductFiltersMcpTool
list_product_options Catalog\ListProductOptionsMcpTool
search_products Catalog\SearchProductsMcpTool
set_product_features Catalog\SetProductFeaturesMcpTool
set_product_option_links Catalog\SetProductOptionLinksMcpTool
update_category Catalog\UpdateCategoryMcpTool
update_feature Catalog\UpdateFeatureMcpTool
update_product Catalog\UpdateProductMcpTool
update_product_filter Catalog\UpdateProductFilterMcpTool
update_product_option Catalog\UpdateProductOptionMcpTool
create_page Content\CreatePageMcpTool
create_promotion Content\CreatePromotionMcpTool
delete_menu_item Content\DeleteMenuItemMcpTool
delete_page Content\DeletePageMcpTool
delete_promotion Content\DeletePromotionMcpTool
get_page Content\GetPageMcpTool
get_promotion Content\GetPromotionMcpTool
get_promotion_rule_schema Content\GetPromotionRuleSchemaMcpTool
list_menu_blocks Content\ListMenuBlocksMcpTool
list_menus Content\ListMenusMcpTool
list_pages Content\ListPagesMcpTool
list_promotions Content\ListPromotionsMcpTool
set_menu_block_menu Content\SetMenuBlockMenuMcpTool
update_menu_items Content\UpdateMenuItemsMcpTool
update_page Content\UpdatePageMcpTool
update_promotion Content\UpdatePromotionMcpTool
update_seo Content\UpdateSeoMcpTool
get_vendor Marketplace\GetVendorMcpTool
get_vendor_balance Marketplace\GetVendorBalanceMcpTool
get_vendor_performance Marketplace\GetVendorPerformanceMcpTool
list_payouts Marketplace\ListPayoutsMcpTool
search_vendors Marketplace\SearchVendorsMcpTool
update_vendor_status Marketplace\UpdateVendorStatusMcpTool
add_order_note Orders\AddOrderNoteMcpTool
create_shipment Orders\CreateShipmentMcpTool
get_customer Orders\GetCustomerMcpTool
get_order Orders\GetOrderMcpTool
search_customers Orders\SearchCustomersMcpTool
search_orders Orders\SearchOrdersMcpTool
update_customer Orders\UpdateCustomerMcpTool
update_order_status Orders\UpdateOrderStatusMcpTool
create_backup System\CreateBackupMcpTool
list_backups System\ListBackupsMcpTool
restore_backup System\RestoreBackupMcpTool

Резервные копии магазина

  • create_backup создаёт полный ZIP-архив через \Tygh\DataKeeper: стандартные файлы приложения, изображения, загруженные файлы, вложения и языки, а также схему и данные всех таблиц базы данных, включая таблицы модулей. Параметры частичного резервного копирования не предоставляются. Имена файлов начинаются с mcp_backup_ и включают отметку времени и случайный суффикс.
  • list_backups возвращает метаданные локальных резервных копий с постраничной разбивкой, начиная с самых новых: штатный тип архива, размер, время изменения файла в поле created_at, маркер MCP в имени файла и возможность восстановления архива этого формата. Содержимое архивов не возвращается.
  • restore_backup восстанавливает файл с точным локальным именем из списка с помощью штатного механизма восстановления. Полное восстановление затрагивает весь магазин, включая других продавцов и витрины, а также токены доступа и подключения; это не выборочная отмена изменений. Пути, URL и символические ссылки отклоняются. Параллельные операции резервного копирования и восстановления через MCP запрещены.

Это инструменты служебной группы, доступные только администраторам со штатной привилегией backup_restore. Просмотр списка требует доступа на чтение; создание — доступа MCP на запись и разрешённых изменений; восстановление дополнительно требует разрешённых удалений через MCP. Продавцам инструменты резервного копирования магазина недоступны. Экспорт товаров и заказов продавца отделён от восстановления всего магазина. Операции выполняются синхронно и могут длиться дольше тайм-аута HTTP клиента: если результат создания неясен, проверьте список резервных копий, а если неясен результат восстановления — панель администратора, прежде чем повторять операцию.

Tygh::$app['addons.ai_mcp_core_tools.backups'] (\Tygh\Addons\AiMcpCoreTools\Backups\BackupManager) адаптирует штатный механизм резервного копирования для инструментов. createBackup(DateTimeImmutable $called_at) и restoreBackup(string $filename) возвращают \Tygh\Addons\AiMcpCoreTools\Backups\BackupInfo; listBackups() возвращает список этих объектов, а BackupInfo::toArray() сериализует их метаданные для ответов инструментов. HookHandlers\ServerInstructionsHookHandler расширяет ai_mcp_server_instructions: администраторам ассистент предлагает резервную копию перед сложными или массовыми изменениями, если инструмент доступен, создаёт её только с согласия пользователя и восстанавливает только после явного одобрения выбранной копии и восстановления всего магазина. Продавцам не предлагается резервное копирование всего магазина. Сам MCP-сервер остаётся независимым от модуля инструментов магазина.

Инструменты MCP для маркетплейсов

Инструменты MCP, имеющие смысл только в маркетплейсе, регистрируются в файле модуля schemas/ai_mcp_server/mcp_tools_multivendor.post.php: search_vendors, get_vendor, get_vendor_performance, get_vendor_balance, list_payouts, update_vendor_status, get_financial_report. Другие новые инструменты MCP включают get_inventory_report, get_abandoned_carts и update_customer. Инструменты аналитики описаны ниже. \Tygh\Addons\AiMcpCoreTools\McpTools\Marketplace\AbstractVendorMcpTool предоставляет выбор продавца и вспомогательные методы для штатных данных продавца: продавцы работают со своей компанией, а администраторы выбирают компанию явно.

Аналитика продаж и счетов

Модуль предоставляет следующие инструменты MCP для аналитики:

  • get_analytics_capabilities: разрешённые показатели и измерения, модуль-владелец, участвующие модули, единицы измерения, основа расчётов и ограничения. Отключённые расширения отсутствуют. Ограниченные поля скрыты от продавцов; права на продажи, счета и только покупателей формируют разные каталоги и доступность специализированных отчётов.
  • get_sales_report: набор данных orders или items, до трёх измерений группировки, фильтры с логикой И между фильтрами и ИЛИ между значениями, сортировка, постраничная разбивка, сравнение периодов, доли групп и вклад в общее изменение.
  • get_sales_details: та же разрешённая выборка и расчёты на уровне заказа или позиции.
  • get_customer_analytics: доступная история оплаченных оформлений заказа, новые и повторные покупатели за период, оценки RFM, неактивность, наблюдаемые продажи за всё время, интервалы между покупками и месячные когорты. Гости не объединяются по предполагаемой идентичности.
  • get_product_analytics: ABC-анализ по чистой сумме продаж позиций и пары товаров с поддержкой и направленной достоверностью правил.
  • get_financial_report (Multi-Vendor): начальный баланс, движение и конечный баланс счетов продавцов, финансовые компоненты, группированная детализация и подтверждающие записи. Список accounts с постраничной разбивкой содержит начальный баланс, движение и конечный баланс каждой разрешённой компании, отсортированные сначала по возрастанию конечного баланса, затем по идентификатору компании. Это учёт расчётов с продавцами, а не банковская выписка или чистая прибыль бизнеса.
  • get_return_analytics регистрируется модулем RMA, когда инструменты магазина активны: заявки, созданные за период, в том числе по более ранним заказам, с группировкой по текущему статусу, действию, причине, товару и дальнейшей обработке позиции.

\Tygh\Addons\AiMcpCoreTools\McpTools\Analytics\AbstractAnalyticsMcpTool предоставляет общие входные свойства отчётов, требования к правам и защищённые вспомогательные методы createQuery(McpToolExecutionContext $context, array $arguments): ReportQuery и createComparison(McpToolExecutionContext $context, array $arguments, ReportQuery $query): ?ReportQuery.

Отчёты сохраняют ограничения компании и витрины независимо от пользовательских фильтров и добавляют их после расширяемого поиска заказов ядра. Родительские заказы маркетплейса исключаются; количество оформлений заказа объединяет только разрешённые выбранные части. История покупателей, товарные корзины и сравнения используют ту же область данных. Отдельные корректировки счёта не привязаны к витрине и исключаются из финансового отчёта, ограниченного витриной. Старые инструменты для всего счёта отклоняют вызовы с ограничением по витрине; get_vendor не возвращает для них баланс всего счёта. Группы отчёта включают dimension_labels рядом со стабильными идентификаторами измерений; товары в ABC-анализе, парах и детализации позиций имеют названия. Названия товаров используют fn_get_product_name() с его хуками и текущими переопределениями витрины. Названия запрашиваются только для идентификаторов, уже присутствующих на разрешённой странице результатов. В StoreBuilder принадлежность к категории определяется в компании заказа, включая товары, предоставленные другой компанией. Группы RMA включают отображаемые названия причин и действий без требования отдельной привилегии чтения конфигурации.

Даты продаж означают создание заказа в часовом поясе магазина с текущими значениями заказа и статуса. Даты выплат означают сохранённую дату записи по счёту с текущим подтверждением и подходящими статусами заказов. Эти отчёты не восстанавливают неизменяемое историческое состояние. Чистая сумма продаж позиций распределяет скидку на промежуточный итог пропорционально в минимальных единицах валюты с сохранением общей суммы скидки. Списанные бонусные баллы и сертификаты, уже учтённые в скидках или итогах заказа, повторно не вычитаются. Измерения групп покупателей включают только включённые и скрытые группы покупателей, но никогда внутренние группы привилегий. Описания категорий, групп вариаций, групп покупателей и правил обработки заказов отражают текущую принадлежность, а не исторический снимок. Финансовые компоненты используют сохранённые поля расчётов, а не текущие тарифы; отсутствующие исторические компоненты возвращают null с missing_records. Суммы платёжного обработчика в сохранённой иностранной валюте требуют группировки по этой валюте и не имеют общего итога по разным валютам. vendor_tax_basis — сохранённый налоговый компонент, учитываемый модулем тарифных планов продавцов, а не утверждение о фактическом сборе налогов и не дополнительное вычитание: исторический снимок не различает эти случаи. Фиксированная комиссия при возврате меняет знак своего сохранённого компонента. Списания, связанные с заказом, не являются снимками комиссии; их вклад в компоненты, применимые только к начислениям и возвратам по заказам, равен нулю.

Суммы отчётов накапливают десятичные значения до форматирования валюты. Балансы следуют отдельному округлению ядра: сначала доход, затем доход за вычетом списаний, отдельно для каждого продавца. Общая сверка движения по счетам суммирует эти балансы продавцов; rounding_adjustment объясняет разницу между движением в сверке и округлённой суммой влияния записей. Фильтры типа и подтверждения влияют на компоненты и транзакции, но не на сверку баланса или список счетов. Пустой настроенный список статусов выплат не накладывает ограничений по статусу заказа, включая незавершённые платежи. Записи, связанные с удалёнными или недоступными заказами, исключаются; отдельные записи по-прежнему ограничены областью доступных счетов.

Итоги, рейтинги, знаменатели когорт и доли рассчитываются до постраничной разбивки. Количество заказов, оформлений заказа и покупателей учитывает уникальные значения в каждой выборке и не обязано суммироваться между группами. При сравнении с нулевым предыдущим значением процентное изменение равно null, а при нулевом общем денежном изменении процентный вклад равен null. Исчезнувшие группы, включая группы с календарным измерением, всё равно отображаются с нулевыми текущими показателями и comparison_only. Предыдущие записи выравниваются до агрегации: previous_period и custom используют прошедшие локальные календарные дни, previous_year использует календарные даты и учитывает скорректированное начало периода 29 февраля. Более длинный пользовательский предыдущий период может создавать интервалы только для сравнения вне текущего периода; они сохраняются, чтобы суммы не терялись. Группировка сравнения принимает одно из измерений день/неделя/месяц/год и запрещает сочетать день с днём недели или несколько календарных уровней. Час и день недели — повторяющиеся измерения. Пустые временные интервалы подчиняются выбранным фильтрам измерений. Отчёты отклоняют выборку, превышающую лимиты точной агрегации (10 000 групп, 100 000 покупателей, оформлений заказа или пар в зависимости от отчёта), вместо возврата частичных итогов.

API расширений аналитики

Расширяющий модуль добавляет schemas/ai_mcp_core_tools/analytics.post.php. Базовый модуль инструментов магазина не содержит имён своих расширений и не проверяет их наличие. Каждый ключ схемы — идентификатор модуля-владельца, содержащий фабрику приложения, которая возвращает подкласс \Tygh\Addons\AiMcpCoreTools\Analytics\AnalyticsExtension:

$schema['my_addon'] = [
    'factory' => static function (\Tygh\Application $app) {
        return new MySalesAnalyticsExtension();
    },
];
return $schema;

Новые публичные классы находятся в \Tygh\Addons\AiMcpCoreTools\Analytics:

  • AnalyticsExtension::describe(AnalyticsCatalog $catalog): void объявляет поля и примечания; getOrderDataTypes(): array запрашивает типы данных заказа, не относящиеся к платежам; enrichOrders(array $orders): void получает пакет данных с разрешёнными идентификаторами заказов в качестве ключей; getPayoutFields(): array объявляет сохранённые столбцы выплат; enrichPayout(PayoutRecord $payout): void добавляет сохранённые компоненты счёта.
  • AnalyticsExtensionRegistry::getExtensions(): array загружает фабрики в детерминированном порядке ключей схемы; RegisteredAnalyticsExtension назначает владельцев полям, вкладам и примечаниям. Фабрика, возвращающая другой тип, вызывает \LogicException.
  • AnalyticsCatalog::addMetric(ReportField $field): void, addDimension(ReportField $field): void, contributeToMetric(string $name): void и contributeToDataset(string $grain): void регистрируют определения и их происхождение; вклады в набор данных применяются ко всем показателям соответствующего уровня детализации, включая зарегистрированные позже, независимо от порядка расширений. isPanelActionAllowed(string $controller, string $mode): bool проверяет внедрённую политику панели. Два владельца одного имени поля вызывают LogicException; страница диагностики сообщает конфликтующие имена и владельцев. Расширение должно использовать уникальное имя поля; намеренно заменить другое расширение можно только через контракт схемы.
  • ReportField описывает имя, смысл, уровень детализации (order, item, payout), единицу измерения, необязательное дополнительное право панели, основу расчёта, доступность продавцам и необязательное обязательное измерение валюты. Его describe(): array предоставляет addon и contributing_addons вместе с определением. Права и доступность продавцам распространяются на фильтрацию и группировку, а также на выбранные показатели. Имена полей образуют список разрешённых значений и никогда не превращаются в SQL, предоставленный пользователем.
  • SalesOrder и SalesItem содержат выбранные сохранённые поля, числовые показатели и строковые измерения. Расширения могут дополнять разрешённый пакет данных; они не должны загружать родительские или соседние заказы либо несвязанную историю продавцов и покупателей. SalesItem::$is_merchandise позволяет расширению помечать служебные позиции, исключаемые по умолчанию.
  • PayoutRecord::setOrderShares(float $deductions, float $operator_share): void задаёт сохранённые компоненты учёта один раз: повторные одинаковые объявления идемпотентны, конфликтующие вызывают LogicException. Это не позволяет двум интеграциям, распознавшим одну и ту же сохранённую комиссию, вычесть её дважды.
  • ReportScope, ReportQuery, ReportFilter, SelectedOrder, ReportBucket, ReportResult, SalesAnalyticsRepository, SalesReportService, CustomerHistory, CustomerAnalyticsService, ProductAnalyticsService, PayoutAnalyticsRepository, FinancialReportQuery, AccountBalance и FinancialReportService предоставляют общую реализацию выборки с ограничением области данных и агрегации. Отчёты модулей должны использовать эту выборку, а не принимать необработанные идентификаторы заказов от вызывающего клиента MCP. ReportScope::__construct(McpToolExecutionContext $context, array $arguments) определяет обязательные ограничения; SalesReportService::getSelection(ReportScope $scope, ReportQuery $query): Generator предоставляет разрешённую отфильтрованную выборку. SalesReportService::report(ReportScope $scope, ReportQuery $query, ?ReportQuery $previous = null): array возвращает группированный отчёт, а FinancialReportService::report(ReportScope $scope, DateTimeImmutable $from, DateTimeImmutable $to, array $arguments): array — отчёт по счетам продавцов.
  • AnalyticsLabelRepository::getLabels(string $dimension, array $values, string $lang_code): array определяет отображаемые названия через закрытое сопоставление измерений и внедрённый механизм ядра для получения названий товаров. Вызывайте его только с идентификаторами из разрешённой страницы результатов. SalesReportService::labelGroups(array $rows, ReportScope $scope): array добавляет отображаемые подписи на такую страницу; getLabels(string $dimension, array $values, ReportScope $scope): array поддерживает страницы специализированных отчётов. Для неизвестных или удалённых идентификаторов подписью остаётся сам идентификатор.

Сервисы доступны как addons.ai_mcp_core_tools.analytics.extensions, .catalog, .sales_repository, .labels, .reports и .finances (префикс повторяется для каждого суффикса). Репозитории SQL получают область видимости через поиск заказов ядра и отдельно применяют обязательные ограничения компании и витрины. Фабрики и классы схем расширений загружаются только при активном модуле инструментов магазина и поддерживающей его версии PHP. Расширения в старых модулях сохраняют минимальный синтаксис платформы и не повышают требуемую версию PHP этих модулей.

Встроенные расширения относятся к модулям Vendor Plans, PayPal Adaptive, Vendor Categories Fee, Direct Payments, Reward Points, Gift Certificates, Vendor Debt Payout, Stripe Connect, Order Fulfillment, Product Variations и RMA. Платёжные модули без отдельно сохранённых компонентов добавляют примечания по учёту через AnalyticsNoteExtension; они не создают вымышленные комиссии обработчиков или банковские расчёты. Показатели расширений раскрывают своих владельцев и участников в определениях отчётов.

Инструменты MCP для контента витрины

Инструменты MCP list_pages, get_page, create_page и update_page работают с информационными страницами и страницами-ссылками; update_seo обновляет SEO-имя, заголовок страницы и метаполя товара, категории или страницы; list_promotions, get_promotion, create_promotion и update_promotion работают с промоакциями по трём шаблонам: процентная скидка на товары категорий или отдельные товары, скидка по купону на заказ и бесплатная доставка; list_menus и update_menu_items работают с меню витрины. Новая страница создаётся отключённой. Инструменты страниц и промоакций используют общие классы \Tygh\Addons\AiMcpCoreTools\McpTools\Content\AbstractPageMcpTool и AbstractPromotionMcpTool соответственно. Оба сопоставляют входные поля со штатными данными и проверяют текст и принадлежность; базовый класс промоакций также создаёт поддерживаемые шаблоны промоакций.

Инструменты каталога и мерчандайзинга

Следующие классы в \Tygh\Addons\AiMcpCoreTools\McpTools\Catalog реализуют соответствующие инструменты MCP и зарегистрированы в schemas/ai_mcp_server/mcp_tools.post.php:

  • GetCategoryMcpTool, GetFeatureMcpTool и GetFeatureConfigurationMcpTool читают полные настройки категорий, варианты характеристик с постраничной разбивкой и активную конфигурацию назначения и стиля характеристик.
  • ListProductOptionsMcpTool, GetProductOptionMcpTool, CreateProductOptionMcpTool, UpdateProductOptionMcpTool, DeleteProductOptionMcpTool и SetProductOptionLinksMcpTool управляют штатными опциями товаров, глобальными опциями и связями. Их базовый класс — AbstractProductOptionMcpTool; частичное обновление вариантов сохраняет неуказанные варианты.
  • ListProductFiltersMcpTool, GetProductFilterMcpTool, CreateProductFilterMcpTool, UpdateProductFilterMcpTool и DeleteProductFilterMcpTool, основанные на AbstractProductFilterMcpTool, управляют штатными фильтрами и областью категорий. Значения выбора остаются вариантами характеристик и управляются через инструменты характеристик.

В маркетплейсе create_product требует company_id от администратора и использует компанию продавца для продавца. create_product и update_product принимают quantity_prices для ценовых уровней по количеству и цен групп покупателей; get_product возвращает их. При передаче заменяется весь список, а пустой список очищает его. Универсальная цена за одну единицу остаётся в поле товара price. list_customer_groups включает штатные группы всех покупателей, гостей и зарегистрированных покупателей, а также настроенные группы покупателей. Общий контракт записи товара принадлежит AbstractProductWriteMcpTool; вспомогательные классы записи категорий и характеристик — AbstractCategoryWriteMcpTool и AbstractFeatureWriteMcpTool в том же пространстве имён.

SearchProductsMcpTool принимает необязательные значения include: categories добавляет названия категорий и главную категорию; модули могут добавлять свои связи, не меняя стандартные краткие сведения о товарах. Необязательный storefront_id выбирает штатный контекст витрины. ProductDetails::getCategories(array $product_ids, string $lang_code, int $company_id = 0): array загружает связи категорий одним запросом и ограничивает их компанией выбранной витрины, если она указана. bulk_update_products (BulkUpdateProductsMcpTool) принимает до 50 отдельных category_updates, несовместимых с другими режимами выбора и изменения. Все строки проверяются до записи; каждый результат сообщает об успехе, фактическом изменении и ошибках. В магазине с витринами компаний отдельные изменения категорий требуют контекста витрины, используют её штатные границы записи категорий и сохраняют связи и главную категорию владельца других витрин. UpdateFeatureMcpTool принимает штатные настройки назначения и стиля, а update_variants — частичные изменения по идентификатору варианта.

\Tygh\Addons\AiMcpCoreTools\McpTools\Content\ListMenuBlocksMcpTool и SetMenuBlockMenuMcpTool предоставляют штатный выбор меню и размещения на витринах, сохраняя другие свойства блоков, языки и переопределения содержимого. ListMenusMcpTool сообщает о динамических источниках подменю категорий и страниц; UpdateMenuItemsMcpTool может изменять эти источники. GetPromotionRuleSchemaMcpTool описывает установленные штатные определения правил и доступные для выбора значения. UpdatePromotionMcpTool принимает ограниченные rule_updates, адресуемые через GetPromotionMcpTool.rule_paths или индексы бонусов. Публичный \Tygh\Addons\AiMcpCoreTools\Promotions\PromotionRuleEditor::apply(array $promotion, array $updates): array проверяет эти изменения перед одним штатным сохранением и сохраняет несвязанные ветви и поля расширений; PromotionRuleUpdate::fromArguments(array $arguments): self проверяет адрес и операцию одного изменения.

Инструменты заказов и покупателей

search_orders и get_order предоставляют разрешённые заказы; update_order_status, add_order_note и create_shipment используют штатные операции с заказами. search_customers, get_customer и update_customer работают с профилями покупателей в пределах видимости пользователя. update_customer сообщает added_usergroup_ids и removed_usergroup_ids вместе с итоговым usergroups. Их классы реализации перечислены выше в McpTools\Orders.

Поиск товаров

fn_get_products() принимает параметр ai_mcp_core_tools_missing_content, пока модуль активен: список содержимого, которого не хватает найденным товарам, — description, images, seo (метаописание).

fn_get_products() принимает параметр ai_mcp_core_tools_no_sales_since, пока модуль активен: отметку времени. Поиск находит товары, созданные раньше этого момента и с тех пор не имеющие заказов в статусах с полученной оплатой.

banners

  • Инструмент MCP delete_banner (\Tygh\Addons\Banners\McpTools\DeleteBannerMcpTool, основанный на \Tygh\Addons\AiMcpServer\Dialect\BaseImpl\AbstractDeleteMcpTool) зарегистрирован в schemas/ai_mcp_server/mcp_tools.post.php. Он доступен, пока модуль ai_mcp_server разрешает удаление через MCP.
  • \Tygh\Addons\Banners\McpTools\BannerOwnership::isAvailable() сообщает, может ли пользователь работать с баннером: в магазине, где витрины являются компаниями, владелец баннера хранится в таблице совместного использования, поэтому простая проверка компании неприменима. Инструменты MCP баннеров получают ответ от него, а AbstractBannerWriteMcpTool::checkBanner() отклоняет баннер, с которым пользователь не может работать.
  • Инструменты MCP list_banners, create_banner и update_banner (\Tygh\Addons\Banners\McpTools\ListBannersMcpTool, CreateBannerMcpTool, UpdateBannerMcpTool, базовый класс AbstractBannerWriteMcpTool) зарегистрированы в той же схеме. list_banners и create_banner принимают витрину баннеров. Ссылка баннера может быть URL с http или https, путём либо dispatch магазина; ссылки с другими схемами отклоняются. Операции записи, после которых невозможно прочитать сохранённый баннер на выбранной витрине, возвращают ошибку.

gift_certificates

  • Инструмент MCP delete_gift_certificate (\Tygh\Addons\GiftCertificates\McpTools\DeleteGiftCertificateMcpTool, основанный на \Tygh\Addons\AiMcpServer\Dialect\BaseImpl\AbstractDeleteMcpTool) зарегистрирован в schemas/ai_mcp_server/mcp_tools.post.php. Он доступен, пока модуль ai_mcp_server разрешает удаление через MCP.
  • Инструменты MCP list_gift_certificates и create_gift_certificate (\Tygh\Addons\GiftCertificates\McpTools\ListGiftCertificatesMcpTool, CreateGiftCertificateMcpTool, базовый класс AbstractGiftCertificateMcpTool) зарегистрированы в той же схеме. Инструменты MCP показывают только последние 4 символа кодов сертификатов и принимают витрину сертификатов.

product_reviews

  • Инструменты MCP list_reviews, reply_to_review и set_review_status (\Tygh\Addons\ProductReviews\McpTools\ListReviewsMcpTool, ReplyToReviewMcpTool, SetReviewStatusMcpTool) зарегистрированы в schemas/ai_mcp_server/mcp_tools.post.php. Они сохраняют ограничение по витрине аутентифицированного пользователя при просмотре списка, ответах и изменениях статуса. Возвращаемые ответы подчиняются той же политике маскирования персональных данных, что и отзывы.

product_variations

  • \Tygh\Addons\ProductVariations\McpTools\CreateProductVariationGroupMcpTool, UpdateProductVariationGroupMcpTool и DeleteProductVariationGroupMcpTool, основанные на AbstractVariationGroupWriteMcpTool, используют штатный сервис вариаций для создания, присоединения, отсоединения, переименования, изменения товара по умолчанию и расформирования групп без удаления товаров. Они регистрируются как create_product_variation_group, update_product_variation_group и delete_product_variation_group соответственно в schemas/ai_mcp_server/mcp_tools.post.php.
  • Модуль дополняет запрошенные результаты поиска MCP связями группы и родительского товара и запрещает менять назначение характеристики, используемой группой вариаций; расформируйте и создайте заново такие группы через штатный сервис. HookHandlers\ProductsHookHandler добавляет публичные обработчики хуков onMcpSearchProductsIncludes(&$includes): void, onMcpSearchProductsPost($context, $arguments, &$products): void и onMcpUpdateFeaturePre($context, $feature_id, $feature_data): void для этих интеграций.
  • Инструмент MCP get_product_variations (\Tygh\Addons\ProductVariations\McpTools\GetProductVariationsMcpTool) зарегистрирован в schemas/ai_mcp_server/mcp_tools.post.php. У инструмента MCP собственное пространство имён McpTools: пространство имён модуля Tools содержит вспомогательные методы запросов и не связано с MCP. Механизм чтения проверяет запрошенный товар и каждого участника группы по текущей компании и правилам совместного использования и сохраняет контекст текущей витрины при загрузке названий и цен.

product_bundles

  • Модуль регистрирует ListProductBundlesMcpTool, GetProductBundleMcpTool, CreateProductBundleMcpTool, UpdateProductBundleMcpTool и DeleteProductBundleMcpTool в своём schemas/ai_mcp_server/mcp_tools.post.php. Классы и AbstractProductBundleMcpTool находятся в \Tygh\Addons\ProductBundles\McpTools и используют штатный сервис комплектов, включая связанную промоакцию и связи товаров. Частичные обновления сохраняют неуказанные поля. Имена их инструментов: list_product_bundles, get_product_bundle, create_product_bundle, update_product_bundle и delete_product_bundle соответственно.
  • \Tygh\Addons\ProductBundles\HookHandlers\PromotionHookHandler::onMcpUpdatePromotionPre($context, $promotion_id, $promotion): void отклоняет прямое изменение промоакций комплектов через MCP; используйте инструменты комплектов.

reward_points

  • \Tygh\Addons\RewardPoints\McpTools\GetProductRewardPointsMcpTool и SetProductRewardPointsMcpTool предоставляют переопределения начисляемых за товар баллов, правила групп покупателей и предварительный просмотр штатного итогового расчёта через схему MCP модуля. Они не изменяют баланс покупателей или цену товара в баллах. Зарегистрированные имена — get_product_reward_points и set_product_reward_points.

rma

  • Инструменты MCP list_returns и update_return (\Tygh\Addons\Rma\McpTools\ListReturnsMcpTool, UpdateReturnMcpTool) зарегистрированы в schemas/ai_mcp_server/mcp_tools.post.php.
  • При активном ai_mcp_core_tools та же схема регистрирует get_return_analytics (\Tygh\Addons\Rma\McpTools\GetReturnAnalyticsMcpTool). ReturnAnalyticsRepository, ReturnAnalyticsService и ReturnReportBucket в том же пространстве имён обеспечивают агрегацию возвратов с ограничением области данных.

vendor_communication

  • Инструменты MCP list_threads, get_thread и send_message (\Tygh\Addons\VendorCommunication\McpTools\ListThreadsMcpTool, GetThreadMcpTool, SendMessageMcpTool, базовый класс AbstractCommunicationMcpTool) зарегистрированы в schemas/ai_mcp_server/mcp_tools.post.php. Они сохраняют текущее ограничение компании панели для администраторов и продавцов; явный фильтр компании доступен только администратору маркетплейса без ограничения по компании.

vendor_data_premoderation

  • Инструменты MCP list_pending_moderation и moderate_products (\Tygh\Addons\VendorDataPremoderation\McpTools\ListPendingModerationMcpTool, ModerateProductsMcpTool) зарегистрированы в schemas/ai_mcp_server/mcp_tools.post.php.

vendor_plans

  • Новый столбец ai_mcp_server таблицы ?:vendor_plans, также доступный как \Tygh\Models\VendorPlan::$ai_mcp_server, управляет доступом продавцов к MCP. Его значение по умолчанию — 0 как для существующих, так и для новых планов. Продавцу необходимы флаг в текущем плане, глобальная настройка allow_vendors и привилегия use_ai_mcp_server. Проверка применяется при выдаче областей доступа MCP и при каждом запросе MCP, включая существующие токены; смена плана не отзывает их. Без активного модуля тарифных планов продавцов сервер использует глобальную настройку и права пользователей; администраторы не ограничены планами.
  • fn_vendor_plans_ai_mcp_server_check_vendor_access($company_id, &$is_allowed) обрабатывает хук доступа продавцов к MCP с учётом текущего плана. Флаг отображается в настройках планов панели администрирования и в карточках планов на витрине.
  • Инструмент MCP list_vendor_plans (\Tygh\Addons\VendorPlans\McpTools\ListVendorPlansMcpTool) зарегистрирован в schemas/ai_mcp_server/mcp_tools.post.php и возвращает флаг как логическое значение.

warehouses

  • \Tygh\Addons\Warehouses\McpTools\ListWarehousesMcpTool, GetProductWarehouseStockMcpTool и SetProductWarehouseStockMcpTool, основанные на AbstractWarehouseMcpTool, зарегистрированы в схеме MCP модуля. Их имена — list_warehouses, get_product_warehouse_stock и set_product_warehouse_stock соответственно. Частичные обновления абсолютных значений количества сохраняют неуказанные склады и используют штатные хуки обновления товаров.
  • \Tygh\Addons\Warehouses\Manager::saveProductStocks(array $product_stocks, $remove_all = true) пересчитывает общее количество по всем сохранённым остаткам после частичной записи, включая неизменённые склады.
  • Модуль обрабатывает хук ai_mcp_core_tools_get_inventory_report_post модуля ai_mcp_core_tools (fn_warehouses_ai_mcp_core_tools_get_inventory_report_post(array &$products)): товары отчёта об остатках, запасы которых распределены по складам, получают общий остаток складов и остаток каждого склада.

oauth_server

Новый модуль “OAuth-сервер” (oauth_server) позволяет приложениям, например ИИ-ассистентам, подключаться к учётным записям пользователей через OAuth 2.1. Модуль выпускает токены доступа приложений в хранилище токенов ядра (тип A, модуль выступает эмитентом), поэтому входные скрипты проверяют их так же, как персональные токены. Ядро не реализует OAuth: коды ошибок протокола (\Tygh\Addons\OauthServer\Enum\OAuthErrors), форма адреса защищённого ресурса (\Tygh\Addons\OauthServer\ProtectedResources) и метаданные защищённого ресурса относятся к модулю. Модуль требует PHP 8.2 или новее: библиотека league/oauth2-server находится в app/addons/oauth_server/lib/vendor и загружается адаптером протокола по мере необходимости. Код модуля написан с использованием синтаксиса PHP 8.2.

  • Входной скрипт oauth.php — символическая ссылка из корня магазина на app/addons/oauth_server/oauth.php. Он обслуживается обработчиком запросов модуля (addons.oauth_server.request_handler); конечные точки, вызываемые приложениями, не используют сессию, а страница авторизации читает сессию панели браузера. oauth.php — конечная точка авторизации; oauth.php?token, oauth.php?revoke (RFC 7009) и oauth.php?metadata — конечные точки токенов, отзыва и метаданных. Конечные точки токенов и отзыва принимают только POST; конечная точка авторизации принимает GET и POST. Метаданные сервера авторизации (RFC 8414) также доступны по адресам /.well-known/oauth-authorization-server и /.well-known/openid-configuration. Последний — псевдоним адреса метаданных OAuth; модуль не выпускает ID-токены OpenID Connect. Эмитентом всегда является защищённый адрес установки магазина независимо от витрины, на которую поступил запрос, а метаданные публикуются только на хосте эмитента: магазин может отвечать на многих доменах, и клиент должен получать одного эмитента из каждого документа и ответа (RFC 8414 3.3, RFC 9207).
  • Настройка Подключать приложения через OAuth (server_enabled) — переключатель сервера. Пока она отключена, входной скрипт и стандартные адреса обнаружения отвечают статусом 404, а токены доступа подключений отклоняются. Ничего не отзывается: переключатель приостанавливает работу подключённых приложений, и они возобновляют её после включения. Страница настроек также содержит max_connection_lifetime; описание объясняет обновление часовых токенов доступа в пределах срока действия подключения.
  • Скрытый неуправляемый вспомогательный модуль oauth_server_unmanaged действует от имени сервера до загрузки обычных модулей, на этапе допуска ядром запросов входных скриптов, принимающих токены доступа. Он устанавливается и удаляется вместе с oauth_server; их физические статусы и требования PHP 8.2 синхронизированы. Оба останавливают обработчики при отключении. Во включённом состоянии вспомогательный модуль читает переключатель сервера и отклоняет токены приложений, если он отключён (хук access_tokens_authenticate_post). Состояние ссылки в ядре независимо сохраняет приоритет. Пока сервер работает, вспомогательный модуль сообщает клиенту без рабочего токена, где его получить: запрос аутентификации в отказе получает код error из RFC 6750, scope, принимаемые входным скриптом, и адрес resource_metadata (RFC 9728 5.1) — адрес самого входного скрипта с параметром resource_metadata. По этому адресу вспомогательный модуль отвечает клиенту без токена метаданными защищённого ресурса вместо отказа: ресурс — адрес, запрошенный клиентом, области доступа — принимаемые скриптом, сервер авторизации — эмитент магазина. Оба ответа формируются через хук access_tokens_deny_request. Документ содержит хост запроса, поэтому отправляется с no-store. Поиск по имени входного скрипта не выполняется: метаданные любого скрипта, принимающего токены, обслуживаются одинаково, а стандартный адрес обнаружения метаданных защищённого ресурса не публикуется. Вспомогательный модуль загружается до обычных модулей только в совместимых процессах, где пара включена. fn_settings_actions_addons_oauth_server(&$new_status, $old_status): void и fn_settings_actions_addons_oauth_server_unmanaged(&$new_status, $old_status): void проверяют активацию пары; fn_settings_actions_addons_post_oauth_server($new_status): bool и fn_settings_actions_addons_post_oauth_server_unmanaged($new_status): bool синхронизируют штатные переходы статусов.
  • Клиенты регистрируются только через документы метаданных клиента: идентификатор клиента — HTTPS-адрес документа на порту по умолчанию. Документ загружается через cURL с проверкой сертификата, без перенаправлений и распаковки, с ограничениями времени и размера, не более одного запроса к хосту одновременно и только с публичных IP-адресов: каждый адрес A и AAAA хоста должен принадлежать общедоступному Интернету, а соединение привязывается к проверенному адресу. При использовании исходящего прокси магазина имя хоста разрешает прокси, поэтому фильтрация адресов назначения возлагается на него; страница диагностики предупреждает об этом. Причина отклонения документа записывается в журнал магазина и не сообщается пользователю. Документ загружается при отображении страницы авторизации и повторно при отправке формы; клиент сохраняется только после предоставления пользователем доступа.
  • Клиенты являются публичными (token_endpoint_auth_method: none) либо аутентифицируются на конечных точках токенов и отзыва с помощью утверждений, подписанных их ключами (private_key_jwt, RFC 7523, RS256). Клиент указывает себя только в параметрах запроса: запрос с заголовком Authorization отклоняется. Ключи загружаются из jwks_uri клиента тем же строгим загрузчиком не чаще одного раза в пять минут независимо от результата и используются не более суток, если повторная загрузка невозможна; каждое утверждение принимается только один раз.
  • Поток с кодом авторизации требует PKCE с методом S256. Ответы авторизации включают параметр iss (RFC 9207), а ответ с токеном указывает области доступа выпущенного токена. Параметры авторизации и тела форм запросов токенов и отзыва проверяются на повторяющиеся имена. Код погашается после проверки остальных данных запроса токена — клиента, адреса перенаправления и проверочного значения PKCE, — поэтому тот, кто лишь увидел код, не может его израсходовать. Повторное предъявление кода отзывает токены, выпущенные по нему, включая все их обновления, и не затрагивает остальную часть подключения (RFC 6749 4.1.2). Токены обновления заменяются при каждом использовании. Повторное предъявление заменённого токена обновления позднее чем через 30 секунд после замены отзывает всё подключение; в пределах 30 секунд он только отклоняется, чтобы параллельные обновления одного клиента не отключали его. Каждый такой случай записывается в журнал магазина. Токен доступа действует для всего магазина: каждый входной скрипт принимает токены со своими областями доступа. Поэтому параметр resource (RFC 8707) может указывать адрес на хосте из конфигурации магазина или витрины и сравнивается в форме ProtectedResources::normalize(). В запросе токена он необязателен; если передан, он должен совпадать с нормализованным ресурсом подключения, если подключение привязано к ресурсу. Подключение, созданное без ресурса, не требует такого сравнения.
  • Страница авторизации работает в сессии панели браузера, которую инициализация предоставляет в режиме только для чтения, выполняет проверки панели администратора через fn_get_panel_access_refusal() и никогда не обращается к панели администратора. Пока такой сессии в браузере нет, страница ожидает вместо завершения работы: повторно запрашивает собственный адрес каждые десять секунд, пока пользователь не войдёт в панель в другой вкладке, предлагает кнопку для браузера, игнорирующего обновление, и прекращает ожидание через десять минут. Браузер с cookie сессии панели, которую невозможно распознать, получает отдельное сообщение, поскольку в этом случае помогает повторный вход.
  • Форма подтверждения показывает области доступа, которые пользователь может предоставить, в виде флажков по группам и предлагает минимальные доступ и срок действия: предварительно выбраны только запрошенные клиентом области и необходимые для них области, а срок действия — самый короткий из разрешённых. Пользователь осознанно расширяет доступ вместо подтверждения максимального доступа без чтения. На странице нет скриптов: область, выбранная пользователем без необходимых для неё областей, получает их при чтении формы.
  • Подтверждение, повторяющее доступ, уже предоставленный пользователем тому же клиенту, использует существующее подключение вместо создания нового, а владелец не получает повторного письма; более долгий срок, выбранный при подтверждении, продлевает существующее подключение, а более короткий оставляет его без изменений. Отозванное или истёкшее подключение никогда не используется повторно. Клиент запрашивает подтверждение при каждом подключении, а пользователь может нажать дважды; поиск и создание выполняются под блокировкой.
  • Доступ, предоставленный пользователем приложению, — это подключение с абсолютным сроком действия, выбранным пользователем в пределах настройки Максимальный срок действия подключения: 30, 90 или 180 дней. Токены доступа действуют не более часа, а коды авторизации — не более десяти минут; никакие выданные учётные данные не действуют дольше подключения.
  • Новая вкладка профиля пользователя “Подключённые приложения” (oauth_server.connections, oauth_server.revoke): пользователи отключают свои приложения, а администраторы — приложения других пользователей.
  • Новые события уведомлений oauth_server.connection_created.a и oauth_server.connection_created.v и шаблон электронной почты oauth_server_connection_created: письмо пользователю о новом подключённом приложении.
  • Новые таблицы: oauth_server_clients, oauth_server_connections, oauth_server_auth_codes, oauth_server_refresh_tokens и oauth_server_client_assertions (использованные утверждения клиентов). Модуль называет доступ, предоставленный пользователем клиенту, подключением; ядро знает его как ссылку выпущенного модулем токена (issuer и issuer_ref таблицы access_tokens), а \Tygh\Addons\OauthServer\Connections\AccessTokenAdapter сопоставляет эти ссылки подключениям. Ключ шифрования кодов и токенов обновления хранится в storage_data, зашифрованный секретным ключом магазина. Токены доступа — непрозрачные токены ядра; асимметричный ключ подписи токенов не создаётся.
  • Состояние ссылки в ядре немедленно останавливает отозванное подключение, в том числе когда оба модуля отключены. Существующие сервисы подключений и учётных данных применяют отложенное состояние ограниченными пакетами при следующем использовании; обычные запросы витрины не выполняют согласование состояния. Удаление пользователя применяется только к исходным поколениям его ссылок. Замена токенов использует retire() ядра и сохраняет ссылку. Удаление модуля удаляет оба модуля пары и их учётные данные; повторная установка не может восстановить предыдущие поколения.
  • Модуль самостоятельно удаляет устаревшие подключения, коды, токены обновления, утверждения клиентов и документы клиентов не чаще одного раза в сутки, когда приложение получает токены (ключ хранилища oauth_server_next_cleanup). Настраивать плановую задачу не требуется.
  • Модуль добавляет собственные строки на страницу диагностики модуля ai_mcp_server через хук ai_mcp_server_diagnostics_checks: наличие oauth.php в корне магазина и проверку, не является ли он копией старой версии скрипта вместо ссылки, наличие вспомогательного модуля, предупреждение об отправке запросов магазина через прокси или отключённом сервере, а также проверку, сообщает ли MCP-сервер клиенту без токена адрес метаданных защищённого ресурса и предоставляет ли их там. Модули остаются независимыми: ни один не знает входной скрипт, настройки или ключи хранилища другого.

Сервисы и классы

Новые классы находятся в \Tygh\Addons\OauthServer\; перечисленные ниже сервисы используют префикс контейнера addons.oauth_server.:

  • metadata (ServerMetadata) предоставляет getIssuer(): string, getEndpointUrl(string $endpoint = ''): string, getScopes(): array и getMetadata(): array для настроенного сервера авторизации и всех зарегистрированных областей доступа токенов. ServiceProvider::getServerMetadata() возвращает этот сервис.
  • protected_resources (ProtectedResources) предоставляет статические normalize(string $url): ?string и findStoreResource(string $url): ?string для индикаторов ресурсов. Нормализация использует HTTPS, переводит хост в нижний регистр, опускает порт по умолчанию и удаляет завершающие косые черты пути; кодирование пути и строки запроса сохраняется. Принимаются только адреса HTTPS или HTTP для loopback без фрагментов.
  • clients (Clients\ClientService) предоставляет loadClient(string $client_id): Client для проверенных удалённых метаданных, register(Client $client): void для сохранения одобренного клиента и findRegisteredClient(string $client_id): ?Client для его последних одобренных данных. Clients\ClientMetadataParser, Clients\ClientUrl и Clients\Client определяют правила метаданных, URL и аутентификации клиента; Clients\Documents\DocumentFetcher отвечает за удалённую загрузку с ограничениями; он отключает транспортные прокси из окружения и использует только явно заданные настройки прокси магазина. Документы клиента требуют совпадающий client_id и непустой список redirect_uris; client_name, token_endpoint_auth_method и token_endpoint_auth_signing_alg необязательны, а private_key_jwt требует jwks_uri. Адреса перенаправления должны точно совпадать с объявленным URI, за исключением нативных приложений: перенаправление на loopback может использовать другой порт. Поддерживаются перенаправления HTTPS, HTTP на loopback и разрешённые схемы нативных приложений.
  • connections (Connections\ConnectionService, также ServiceProvider::getConnections()) предоставляет connect(int $user_id, string $client_id, array $scopes, string $resource, int $lifetime_days): EstablishedConnection, findConnection(int $connection_id): ?Connection, findActiveConnection(int $connection_id): ?Connection, getUserConnections(int $user_id): array, revoke(array $connection_ids): int и deleteUserConnections(int $user_id): void. Connections\Connection содержит предоставленный доступ и абсолютный срок его истечения; Connections\EstablishedConnection также указывает, было ли подключение создано заново.
  • credentials (Connections\CredentialService) управляет погашением кодов, заменой токенов обновления и токенами доступа. Connections\AccessTokenAdapter сопоставляет идентификаторы подключений паре эмитент/ссылка токена ядра. Connections\ConnectionRepository и Connections\CredentialRepository отвечают за собственные хранилища.
  • authorization (Authorization\AuthorizationFlow) обрабатывает поток в браузере. Authorization\PanelSession, PanelUserPolicy, ConsentForm, PageSignature и WaitingPage реализуют допуск к панели, согласие и его защиту с привязкой к сессии независимо от CSRF-токенов панели.
  • RequestHandler::handle(ServerRequestInterface $request): ResponseInterface направляет запросы в Endpoints\AuthorizationEndpoint, TokenEndpoint, RevocationEndpoint или MetadataEndpoint. Они возвращают ответы PSR-7; платформа отправляет их. RequestParameters::parse(string $raw_params): array отклоняет повторяющиеся параметры и входные данные длиннее 16 КиБ с MalformedRequestException. Запросы метаданных не создают сервер протокола. Server\OAuthServer и его классы Server\Adapters / Server\Entities адаптируют библиотеку OAuth к подключениям и токенам доступа ядра.
  • logger — это \Tygh\Logging\StoreLogger, настроенный на включение предупреждений и ошибок; maintenance (Maintenance::cleanUpIfDue(): void) выполняет описанную выше очистку.

oauth_server_unmanaged

Скрытый вспомогательный модуль имеет те же требования к PHP и жизненный цикл, что и родительский модуль, и предоставляет только хуки раннего допуска:

  • fn_oauth_server_unmanaged_access_tokens_authenticate_post(\Tygh\AccessTokens\AccessToken $token, &$is_refused) отклоняет токены, выпущенные oauth_server, пока переключатель его сервера отключён. Аутентификация ядра независимо проверяет владельца ссылки, поколение, срок действия и отзыв.
  • fn_oauth_server_unmanaged_access_tokens_deny_request(\Psr\Http\Message\ServerRequestInterface $request, array $scopes, $reason, \Psr\Http\Message\ResponseInterface &$response) добавляет параметры запроса аутентификации OAuth Bearer либо заменяет отказ метаданными защищённого ресурса. Ответ с метаданными требует включённого сервера авторизации, GET-запроса с resource_metadata и отсутствия токена Bearer.
  • \Tygh\Addons\OauthServerUnmanaged\Installer запрещает отдельную установку и передаёт прямое удаление родительскому модулю. Действия настроек родителя синхронизируют оба статуса через штатные функции жизненного цикла. Очистка подключений и учётных данных относится к существующим сервисам и репозиториям основного модуля.

rus_sdek2

  • jms/serializer обновлён с версии 3.29.1 до 3.32.9, которая поддерживает phpstan/phpdoc-parser 2.x и по-прежнему требует PHP 7.4. Модуль использует phpstan/phpdoc-parser 2.3.5 и doctrine/deprecations 1.1.6 — те же версии, что и ai_mcp_server, поэтому оба модуля могут загружать один API парсера в одном запросе.
  • Модуль принимает psr/http-message 1.1 и 2.0 (^1.1 || ^2.0) и устанавливается с версией 2.0, как и ядро.

mobile_app

  • Модуль устанавливается с google/auth 1.27.0 вместо 1.26.0 и с psr/http-message 2.0, как и ядро: версия библиотеки 1.26.0 принимала только psr/http-message 1.x, а модуль загружает свои библиотеки раньше библиотек ядра, поэтому интерфейсы старой версии могли заменять интерфейсы ядра во всём запросе.

Новые функции

  • Tygh\Addons\Gdpr\Service::findOutdatedAgreementsForUserByType(array $auth, $agreement_type) — идентификаторы устаревших согласий одного типа.
  • Tygh\Addons\Gdpr\Service::getRevocableUserAgreements(array $auth = []) — согласия, отображаемые в списке отзыва на витрине, по одному на тип.
  • Tygh\Addons\Gdpr\Service::revokeAgreement($agreement_id, array $auth = [], $revoke_related_outdated = false, $status_reason = 'user_revoked') — отзывает одно согласие и выполняет побочные действия, зарегистрированные для его типа. С $revoke_related_outdated = true также отзывает все активные и устаревшие согласия того же типа в пределах разрешённого пользователя и витрины.
  • Tygh\Addons\Gdpr\Service::revokeAgreementsBulk(array $agreement_ids, array $auth = [], $revoke_related_outdated = false, $status_reason = 'user_revoked') — то же для нескольких согласий.
  • Tygh\Addons\Gdpr\Service::revokeAllUserAgreements($user_id) — отзывает все согласия пользователя; используется при обезличивании.
  • Tygh\Addons\Gdpr\Service::markDeletedUserAgreementsAsOutdated($user_id) — помечает согласия удалённого пользователя как устаревшие.
  • Tygh\Addons\Gdpr\Service::linkGuestAgreementsToUser($user_id, $email) — привязывает гостевые записи с указанным адресом электронной почты к учётной записи пользователя.
  • Tygh\Addons\Gdpr\Service::buildAuthFromParams(array $params) — формирует данные авторизации из параметров, с которыми сохраняется согласие.
  • fn_gdpr_get_submitted_agreement($agreement_type) — значение, отправленное покупателем для флажка согласия, либо null, если флажка не было в форме.
  • fn_gdpr_get_agreement_user_context(array $agreement) — идентификатор пользователя и адрес электронной почты, которым принадлежит согласие.
  • fn_gdpr_process_revoke_agreement_side_effects(array $agreement, array $auth) — выполняет обработчики, зарегистрированные для типа отозванного согласия в схеме gdpr/revoke_side_effects. Обработчик возвращает false только при ошибке.
  • fn_gdpr_clear_checkout_agreement_user_data($agreement_type = '') — очищает сохранённое состояние флажков согласий при оформлении заказа.

Изменённые функции

  • Tygh\Addons\Gdpr\Service::hasUserAgreement($agreement_type, array $auth = [], $check_in_cache = true) — параметр $auth теперь имеет тип array; передача другого значения вызывает TypeError. Кешированные проверки повторно используются только в текущем запросе, поэтому новый запрос видит изменения согласий, сделанные в другой сессии.
  • Tygh\Addons\Gdpr\Service::getFullAgreement($agreement_type, $lang_code = CART_LANGUAGE) — принимает язык, на котором загружается текст согласия.

Удалённые функции

  • fn_gdpr_checkout_place_orders_pre_route() — заменён на fn_gdpr_checkout_place_orders_post(), который записывает согласие при оформлении заказа до начала оплаты.

Новые классы

  • Tygh\Enum\Addons\Gdpr\AgreementStatuses — статусы согласий: активное, устаревшее, отозванное.
  • Tygh\Enum\Addons\Gdpr\AgreementStatusReasons — причины, по которым согласие устарело или было отозвано.