Адаптация существующих модулей и тем под CS-Cart 4.22.1¶
- Изменения в ядре
- Изменились требования к версии PHP
- Обработчики сохранения сессий теперь регистрируются как объект
- Токены доступа
- Сессии с истёкшим сроком действия
- Входные скрипты с обработчиком запросов
- Токены защиты форм чужой сессии
- Сессии административной панели вне dispatch
- psr/http-message 2.0
- Приложение HTTP-процесса
- psr/http-server-handler 1.0
- psr/clock 1.0
- Логирование
- Адреса административной панели и панели продавца
- Модули с входными скриптами
- Модули, требующие более новой версии PHP
- Лицензирование
- Изменения в классе
Tygh\Http
- Функции ядра
- Изменения в классах
- Изменения в хуках
- Изменения в схемах
- Изменения в базе данных
- Изменения в шаблонах
- Изменения в модулях
- access_restrictions
- full_page_cache
- ai_mcp_server
- ai_mcp_core_tools
- banners
- gift_certificates
- product_reviews
- product_variations
- product_bundles
- reward_points
- rma
- vendor_communication
- vendor_data_premoderation
- vendor_plans
- warehouses
- oauth_server
- oauth_server_unmanaged
- rus_sdek2
- mobile_app
- Новые функции
- Изменённые функции
- Удалённые функции
- Новые классы
Изменения в ядре¶
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()и никогда не перенаправляет его: перенаправление в административную панель раскрыло бы её адрес, а программа всё равно не последовала бы ему. Ядро не реализует протокол скрипта и не объясняет причину отказа: клиент получает только статус без тела, будь то программа или пользователь страницы скрипта. Страницы с собственными отказами для пользователя формирует модуль, обслуживающий скрипт.Запрос скрипта, принимающего токены доступа, допускается или отклоняется в первом стеке инициализации, до загрузки обычных модулей:
fn_init_access_token()находит и проверяет Bearer-токен через аутентификатор: хеш, срок, отзыв, статус и тип владельца, доступность компании и наличие области скрипта. Тип учётной записи ещё неизвестен, поэтому выполняются только запросы к БД — без хуков, схем и кэшированных выборок. Результат сохраняется в контейнере приложения:access_tokens.authentication, принятый токен с владельцем либо причина отказа (\Tygh\Enum\AccessTokenRefusals).fn_init_account_type()определяет константуACCOUNT_TYPE: тип владельца токена для таких запросов иcustomerдля остальных, если константа ещё не определена.fn_init_unmanaged_addons()загружает неуправляемые модули: только они могут участвовать в допуске запроса на этом раннем этапе.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_HANDLERHTTP-приложению через новый защищённый статический метод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-parser2.x и по-прежнему требует PHP 7.4. Модуль используетphpstan/phpdoc-parser2.3.5 иdoctrine/deprecations1.1.6 — те же версии, что иai_mcp_server, поэтому оба модуля могут загружать один API парсера в одном запросе.- Модуль принимает
psr/http-message1.1 и 2.0 (^1.1 || ^2.0) и устанавливается с версией 2.0, как и ядро.
mobile_app¶
- Модуль устанавливается с
google/auth1.27.0 вместо 1.26.0 и сpsr/http-message2.0, как и ядро: версия библиотеки 1.26.0 принимала толькоpsr/http-message1.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— причины, по которым согласие устарело или было отозвано.