Руководство Melbis Shop: оглавление

3. Описание MCP-сервера › 3.7 Витрина › Концепция

Семья shop работает с магазином снаружи: открывает страницу витрины так, как её получает посетитель, открывает веб-модуль так, как его открывает программа, запускает на витрине собственный модуль агента и копирует код магазина на этот компьютер.

shop_page, shop_module и shop_agent прав не требуют: они идут на сайт, а не в движок, и права на модуль проверяет сам модуль. Одно исключение: shop_page с debug=true спрашивает у движка код отладчика и поэтому требует права «Получить конфигурацию». shop_download требует права «Экспорт → Магазин».

Все запросы MCP-сервера — к страницам, к agent.php и к core/mcp.php — уходят с этого компьютера с User-Agent MelbisShop-MCP. Если в магазине задан код доступа и у пользователя есть лицензия на сегодня, сервер дописывает его в User-Agent, и прокси перед сайтом пропускает запросы по нему. Код сервер берёт перед каждым запросом из настроек магазина, где его хранит программа, — «Установка магазина», раздел «Безопасность».

Правила

У семьи свои правила — shop.md в папке Engine\MCP. Первый вызов любого инструмента shop_* в сессии отказывает с ними; после подтверждения через session_rules_accept работают все инструменты семьи.

Страница

shop_page запрашивает страницу, как браузер посетителя, и сохраняет HTML в pages\ папки разговора.

Посетителя определяют его куки и заголовки. Без cookies чтение — новый визит, без кук и без сессии. Ответ возвращает куки после запроса вместе с тем, что записал сайт, и следующий вызов с ними продолжает того же посетителя. Так открывают страницу с заранее заданными куками — например, с выбранной версией витрины или валютой — и видят, что сайт пишет в куки. Заголовки запроса задаёт headers: User-Agent телефона и Sec-CH-UA-Mobile: ?1 открывают мобильную версию там, где витрина выбирает её по устройству. Заголовки ответа сайта приходят в поле headers ответа.

Страница может прийти из кеша. Сохранение файла модуля сбрасывает кеш только этого модуля — что очищается само, описано в «Конфигурации и кеше». Если правка на странице не видна, причиной бывает кеш другого модуля, который выводит изменённое место.

Это разметка, а не картинка. По HTML видно, что изменилось в коде страницы; как она выглядит, видит только человек в браузере.

Отчёт отладчика. С debug страница запрашивается в машинном виде отладчика («Средства отладки»): весь отчёт сохраняется рядом со страницей, в ответ приходят главные числа и модули страницы. Код отладчика сервер берёт из конфигурации магазина, поэтому такой вызов требует права «Прямой доступ → Разработка → Получить конфигурацию». В ответ и в имена файлов код не попадает. Если кода нет, его задаёт владелец: «Проектирование → Инсталляция», поле «Пароль отладчика». Подписи на оригинальном языке могут отличаться.

Форма

С полем post вызов становится отправкой формы. Так работает всё живое на витрине: корзина, заявка, отзыв, заказ. В отличие от чтения, отправка меняет магазин — появляются строки корзины, заявки, письма менеджеру, а в работающем магазине и настоящий заказ. Тестового режима у витрины нет.

Отправки подряд — один посетитель, если передавать куки дальше: следующий вызов идёт с cookies из ответа предыдущего. В демо-магазине корзина отвечает на поля func и id:

{"url": "/?mod=melbis_basket", "post": {"func": "Plus", "id": 12}}
{"url": "/?mod=melbis_basket", "post": {"func": "Goods"}, "cookies": {"MELBIS_SHOP": "k3fq9…"}}

Поля формы называются так, как их пишет разметка страницы. Список значений уходит как имя[]=… по одному на значение — так браузер отправляет флажки и множественный выбор, и только так PHP читает поле массивом. Токен формы, если он есть, сам не берётся: сначала читают страницу.

Веб-модуль

shop_module открывает встроенный или внешний веб-модуль так, как его открывает программа: POST от имени пользователя сессии — login, stamp и sign сервер добавляет сам — с полями окна, которые передал агент. Так проверяют и разрабатывают модули, которые менеджер видит в окнах программы. Ответ сохраняется в modules\ папки разговора; с debug приходит отчёт отладчика, как у страницы.

Куки у shop_module — как у страницы: сессия модуля длится, пока агент передаёт куки из ответа в следующий вызов.

Функция модуля пишет настоящие данные от имени пользователя сессии: вызов с func в работающем магазине — то же действие, что нажатие кнопки в окне программы.

Какие поля передаёт каждое окно и как модуль авторизует пользователя — «Веб-модули».

Модуль агента

shop_agent запускает модуль через точку входа agent.php в корне сайта и возвращает ответ витрины. Так выполняется работа, для которой нет AI-инструмента: отчёт по нескольким таблицам, проверка всего каталога, разовая правка со своей логикой.

Точка входа запускает модуль, только если:

1. подходит ключ сессии — его выдаёт session_connect;
2. имя модуля начинается с agent_;
3. модуль есть в units/;
4. модуль — точка входа: entry_point: 1 в манифесте, в программе — «Модуль входной точки».

Ключ сессии один на логин: параллельные сессии одного пользователя делят его. Сервер магазина хранит ключ в памяти сутки, каждый session_connect продлевает срок, а перезапуск сервера ключ стирает.

Параметры уходят так же, как поля формы, — список приходит массивом, — и модуль получает их одним сериализованным аргументом: в манифесте объявлено post: serial, значения лежат в $mVars['post'] — см. «Модульный скрипт». Служебные login, secret и mod точка входа убирает до запуска модуля.

Ответ проходит через парсер, как любая страница: шаблоны, теги, кеш. Весь он сохраняется в runs\<модуль>.txt папки разговора. Если модуль упал, сообщение, файл и строку движок записывает в журнал витрины core/log/melbis/front.log.

Прав на запуск нет. Запустить готовый модуль agent_* может любой, кто вошёл в магазин; создать или изменить модуль — пользователь с правом «Прямой доступ → Разработка → Изменение данных».

shop_agent и tool_run

Оба запускают PHP-код магазина, но это разные двери.

tool_run — рабочий вызов, shop_agent — мастерская. Черновик из мастерской нередко становится AI-инструментом: «AI-инструменты».

Копия магазина

shop_download — единственный инструмент семьи, который берёт из движка данные. Архив он собирает так же, как «Копирование» в программе, и распаковывает на этом компьютере:

config.json в копию не попадает никогда. Файлов элементов из files/ среди видов копии нет: их скачивает engine_files_load.

Копия — снимок на момент вызова. Правка в ней не уходит на сервер, а поздние правки магазина в неё не попадают: файлы магазина меняют инструменты engine_*.