Для разработчиков

Модули

Разработка JS-модуля RetailCRM с AI-ассистентом

Разработка JS-модуля RetailCRM с AI-ассистентом

Скопировать ссылку на статью

Скопировано

Содержание

Что описывает статья
- Перед началом
Создание frontend-проекта через CLI
- Пример запуска
- Полезные флаги
Подготовка проекта для AI-ассистента
Как ставить задачу AI-ассистенту
Практический рабочий процесс с AI
- Минимальная рабочая проверка страницы
- Что фиксировать в задаче
Разработка виджетов и страниц
Проверка и публикация
Ограничения и контроль качества
Как сформулировать хороший промпт

1. Что описывает статья

AI-ассистент может ускорить подготовку frontend-части JS-модуля RetailCRM: создать стартовую структуру проекта, помочь выбрать target или паттерн страницы, подключить публичные компоненты Embed UI, добавить локализацию и выполнить базовые проверки. Чтобы результат был предсказуемым, ассистент должен опираться на источники проекта: документацию RetailCRM, документацию @retailcrm/embed-ui, локальный AGENTS.md, MCP-ресурсы и профили компонентов.

Главная практическая польза AI в такой задаче - не только генерация Vue-кода. Ассистент помогает быстрее пройти по контрактам платформы: сопоставить extensionrc.json, endpoint runner, target или page code, доступные contexts, компоненты Embed UI и проверки перед публикацией. Поэтому задачу лучше формулировать не как «сделай страницу», а как разработку небольшого сценария с явной цепочкой проверки.

Статья относится к frontend-части JS-модуля. Backend-часть, подключение и активация модуля, права API и общие требования к публикации необходимо готовить по статьям раздела «Публикация модуля в Маркетплейсе».

Перед началом

Перед разработкой необходимо определить:

какие задачи должен решать модуль;
нужна ли frontend-части отдельная страница внутри CRM или достаточно виджета в существующем интерфейсе;
какие API-методы и backend-ендпоинты понадобятся модулю;
какие targets, pages, contexts и actions используются во frontend-части;
какие локали поддерживаются в пользовательском интерфейсе.

Для JS-модулей действуют общие требования к модулям и дополнительные требования к frontend-части. Например, frontend-часть должна использовать публичные пакеты платформы, выполнять обмен с backend-частью через host.httpCall(), а тексты интерфейса должны быть подготовлены как минимум для ru-RU, en-GB и es-ES.

Host API - это публичный frontend-интерфейс, который CRM предоставляет JS-модулю во время работы внутри CRM. Через объект host frontend-часть модуля вызывает backend-часть, управляет переходами и изменяет query string страницы.

Важно!

AI-ассистент не заменяет проверку разработчика. Он может сгенерировать рабочий код, но итоговое соответствие требованиям Маркетплейса, API, дизайна и сценариям пользователя необходимо проверять вручную.

2. Создание frontend-проекта через CLI

Для подготовки frontend-части JS-модуля используется пакет @retailcrm/embed-ui. CLI можно запускать через npx.

Команда init создает или дополняет проект frontend-части расширения. Она может:

добавить package.json, если его еще нет;
добавить зависимости @retailcrm/embed-ui*, vue, pinia, vue-i18n и dev-зависимости для Vite, TypeScript и ESLint;
создать tsconfig.json, vite.config.ts, eslint.config.js, env.d.ts;
создать или дополнить .gitignore;
создать стартовые файлы endpoint worker, страницы настроек, виджета заказа и i18n-сообщений;
добавить extensionrc.json и скрипт публикации;
создать или дополнить AGENTS.md;
добавить MCP-настройки, если они не отключены флагами;
добавить project-level skills, если они не отключены флагами;
инициализировать Git-репозиторий, если включен --git или это выбрано в интерактивном режиме.

Без дополнительных флагов init выбирает стандартный набор пакетов, создает стартовые файлы, добавляет инструкции для AI-ассистента, project-level skills и MCP-настройки для пакетов, которым они нужны. Установка зависимостей запускается автоматически после изменения package.json. Project-level конфиги конкретных AI-клиентов, например .codex/config.toml, создаются только при явном указании --mcp-client-configs.

Пример запуска

Для первого запуска удобно использовать интерактивную настройку проекта:

npx -y @retailcrm/embed-ui init ./src --interactive --package-manager npm --mcp-client-configs codex --git --verbose

В этом примере:

init ./src создает frontend-часть в каталоге ./src;
--interactive открывает пошаговый режим настройки, где можно выбрать, какие части проекта создавать и какие пакеты подключать;
--package-manager npm явно выбирает npm;
--mcp-client-configs codex создает project-level конфигурацию MCP для Codex CLI;
--git инициализирует Git-репозиторий, если каталог еще не является репозиторием;
--verbose выводит подробную сводку изменений.

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

После успешного выполнения команды в проекте должны появиться инструкции для AI-ассистента (AGENTS.md), MCP-конфигурация (.mcp.json) и, если выбран Codex CLI, project-level конфигурация .codex/config.toml. Если skills не отключены, также создается каталог .agents/skills/*. Дополнительно команда устанавливает зависимости, если установка не отключена флагом --no-install.

Для проверки созданного проекта выполните:

npm run build
npm run eslint

Полезные флаги

Перед записью файлов полезно посмотреть, что сделает CLI:

--dry-run - показать план изменений без записи файлов;
--verbose - вывести подробную сводку созданных, обновленных и пропущенных шагов.

Для выбора режима запуска используйте:

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

Для управления зависимостями и местом установки используйте:

--package-manager <manager> - явно выбрать менеджер пакетов, например npm, yarn или pnpm;
--no-install - не запускать установку зависимостей после изменения package.json;
--cwd <path> - указать корень проекта, если команда запускается не из него;
--packages embed-ui,components,contexts,types,endpoint - явно выбрать пакеты для установки и настройки;
--version <version> - использовать указанную версию пакетов;
--exact - записывать точные версии пакетов вместо диапазонов.

Для нового проекта обычно стоит оставить стандартный набор действий CLI: он создает конфиги, стартовые файлы, инструкции, skills и MCP-настройки. Флаги --no-* полезны при работе в уже существующем репозитории: ими можно не трогать части, которые уже настроены вручную.

--no-configs - не создавать tsconfig.json, vite.config.ts, eslint.config.js и env.d.ts;
--no-template - не создавать стартовые Vue-файлы, extensionrc.json и скрипт публикации;
--no-agents - не создавать и не дополнять AGENTS.md;
--no-skills - не создавать и не обновлять project-level skills;
--no-mcp - не добавлять MCP-настройки.

Для MCP и project-level skills есть отдельные рычаги:

--mcp-client-configs codex,cursor,junie,vscode - создать project-level конфиги поддерживаемых AI-клиентов;
--skills-only - установить только project-level skills без изменения зависимостей, шаблонов и AGENTS.md;
--force-skills - обновить уже существующие управляемые project-level skills.

Для установки или принудительного обновления skills в уже существующем проекте можно использовать отдельную команду:

npx @retailcrm/embed-ui init-skills
npx @retailcrm/embed-ui init-skills --force

Если init повторно запускается в существующем проекте, CLI не перезаписывает существующие файлы без явного разрешения. Для управляемого обновления используйте:

--force - обновить управляемые секции и записи, учитывая флаги --no-*;
--force-deps - заменить несовместимые версии зависимостей;
--fix-sections - перенести зависимости в ожидаемые секции dependencies и devDependencies;
--force-files - перезаписать генерируемые стартовые файлы.

Примечание

Если проект уже содержит src, для нового frontend-каталога расширения удобнее выбрать отдельный путь, например ./web. CLI не перезаписывает существующие файлы без явного разрешения.

3. Подготовка проекта для AI-ассистента

Проект должен содержать правила и машинно-читаемые источники, по которым AI-ассистент принимает решения. Для этого используются AGENTS.md, MCP-ресурсы и, когда они доступны в проекте, project-level skills.

AGENTS.md

AGENTS.md - это файл инструкций для AI-ассистентов в проекте. В нем фиксируются правила работы с публичными API пакетов, порядок чтения документации, ограничения на импорты и проверочные шаги.

CLI @retailcrm/embed-ui init создает или дополняет AGENTS.md, если генерация инструкций не отключена. Для v1-components также доступна отдельная команда:

npx @retailcrm/embed-ui-v1-components init-agents

Если нужно добавить или обновить только секции инструкций для v1-contexts и v1-endpoint, используйте отдельные команды:

npx @retailcrm/embed-ui-v1-contexts init-agents
npx @retailcrm/embed-ui-v1-endpoint init-agents

Если проект создается через @retailcrm/embed-ui init без флага --no-agents, CLI добавляет в AGENTS.md инструкции по выбранным пакетам. Если файл создается вручную или дополняется в существующем проекте, проверьте, что в нем есть правила для frontend-части:

импортировать UI-компоненты из @retailcrm/embed-ui-v1-components/remote;
импортировать icons и assets из @retailcrm/embed-ui-v1-components/assets/...;
не импортировать из dist/* и внутренних путей пакета;
не использовать @retailcrm/embed-ui-v1-components/host в обычном frontend-коде модуля, если задача не относится к host-runtime;
читать профили компонентов перед использованием сложных компонентов;
использовать @retailcrm/embed-ui-v1-endpoint/remote и runner: "worker" для новых модулей со страницами;
использовать публичный Host API для навигации и query string.

Полезный AGENTS.md должен описывать не только предпочтения по стилю, но и условия, при которых ассистент обязан остановиться и явно назвать неопределенность. Например: если target, context, action, route или API компонента не подтверждены документацией, профилем или MCP-ресурсом, их нельзя придумывать по аналогии; если источник данных не определен, тестовые данные допустимы только как временный слой для интерфейсной проверки.

MCP-ресурсы

Пакеты v1-contexts и v1-endpoint предоставляют MCP-серверы для работы с AI-ассистентами. Через них ассистент получает структурированные сведения о targets, contexts, actions и custom contexts без ручного поиска по node_modules.

При выборе пакетов v1-contexts и v1-endpoint CLI может добавить .mcp.json с серверами:

retailcrm-embed-ui-v1-contexts;
retailcrm-embed-ui-v1-endpoint.

Для Codex CLI при флаге --mcp-client-configs codex создается .codex/config.toml, например:

[mcp_servers.retailcrm-embed-ui-v1-contexts]
command = "./node_modules/.bin/embed-ui-v1-contexts-mcp"

[mcp_servers.retailcrm-embed-ui-v1-endpoint]
command = "./node_modules/.bin/embed-ui-v1-endpoint-mcp"

Основные resources:

embed-ui-v1-endpoint://targets;
embed-ui-v1-endpoint://targets/<encoded-target>;
embed-ui-v1-contexts://contexts;
embed-ui-v1-contexts://contexts/<encoded-context>;
embed-ui-v1-contexts://actions;
embed-ui-v1-contexts://actions/<encoded-scope>;
embed-ui-v1-contexts://custom-contexts;
embed-ui-v1-contexts://custom-contexts/<encoded-entity>.

После обновления пакетов MCP-конфигурацию можно переинициализировать:

npx @retailcrm/embed-ui-v1-contexts init-config . --force --mcp-client-configs codex
npx @retailcrm/embed-ui-v1-endpoint init-config . --force --mcp-client-configs codex

После этого перезапустите AI-клиент или переподключите MCP-серверы. Иначе текущая сессия может продолжить использовать уже запущенный MCP-процесс и profiles, загруженные до обновления пакетов.

Если после перезапуска AI-клиента resources по-прежнему выглядят устаревшими или в системе осталось несколько MCP-процессов, можно завершить запущенные процессы Embed UI MCP и затем снова открыть проект в AI-клиенте:

pkill -f 'embed-ui-v1-(contexts|endpoint)-mcp'

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

Примечание

В Codex команда /mcp показывает список MCP tools, а серверы Embed UI публикуют MCP resources. Поэтому строки No MCP tools available, Tools: (none) и Auth: Unsupported сами по себе не означают ошибку настройки. Работоспособность таких серверов проверяется чтением resources: targets, contexts, actions и custom contexts. После обновления пакетов новые данные появляются в resources и документации, например в profiles для endpoint targets, а не обязательно в списке MCP tools.

Project-level skills

Project-level skills - это локальные инструкции для AI-ассистента по отдельным типам задач. AGENTS.md задает общие правила проекта, MCP-ресурсы дают справочные данные о targets, contexts и actions, а skills описывают порядок работы: какие источники прочитать, какие решения проверить и какие ограничения учесть перед изменением UI, contexts или endpoint. Эти файлы не входят в runtime модуля и не меняют поведение приложения.

При обычном init CLI создает project-level skills в каталоге .agents/skills/*/SKILL.md, если установка не отключена флагом --no-skills. Для установки или обновления skills в существующем проекте используйте:

npx @retailcrm/embed-ui init-skills --dry-run
npx @retailcrm/embed-ui init-skills

Для принудительного обновления уже установленных управляемых skills используйте:

npx @retailcrm/embed-ui init-skills --force

Skills также можно установить через init, ограничив команду только установкой project-level skills:

npx @retailcrm/embed-ui init ./web --skills-only

Для отдельных пакетов используйте пакетные команды:

npx @retailcrm/embed-ui-v1-components init-skills
npx @retailcrm/embed-ui-v1-contexts init-skills
npx @retailcrm/embed-ui-v1-endpoint init-skills

Для пакетов v1-components, v1-contexts и v1-endpoint доступны следующие project-level skills:

embed-ui-v1-components-ui - для разработки UI на @retailcrm/embed-ui-v1-components: выбор паттерна страницы, чтение component/page profiles, правила стилизации, формы, таблицы, pagination, widget UI и разбор дизайн-замечаний;
embed-ui-v1-contexts-usage - для работы с contexts, actions, custom contexts, custom fields и custom dictionaries: проверка доступности context в target, выбор public import, различение readonly и writable полей, fallback на YAML profiles при недоступном MCP;
embed-ui-v1-endpoint-runtime - для endpoint wiring: страницы, виджеты, runners, targets, menu hierarchy, page descriptors, publishing payload, Host API и проверка страницы в CRM host.

AI-ассистент использует skills по name и description, когда задача совпадает с их областью применения. В задаче также можно сослаться на skill явно, например: «используй embed-ui-v1-endpoint-runtime перед правкой endpoint runner» или «используй embed-ui-v1-contexts-usage перед работой с actions». После установки или обновления skills перезапустите AI-сессию, чтобы клиент перечитал проектный контекст.

Если skills в проекте еще не установлены или были отключены флагом --no-skills, их можно добавить позже командами из этого раздела. До этого основной контекст для AI-ассистента остается в AGENTS.md, MCP-ресурсах и профилях компонентов.

4. Как ставить задачу AI-ассистенту

В задаче для AI-ассистента необходимо указать не только желаемый результат, но и границы, в которых этот результат должен быть реализован. Для JS-модуля это особенно важно: ассистент должен выбрать подходящий target или страницу, использовать публичные API Embed UI, собрать интерфейс из стандартных компонентов и не придумывать платформенные контракты по аналогии.

Хорошая постановка задачи содержит:

пользовательский сценарий, который должен закрывать модуль;
тип интерфейса: виджет в target, собственная страница, модальное окно или боковая панель;
данные, которые должны прийти из CRM, backend-части модуля или временного тестового набора;
действия пользователя, которые должны менять данные;
состояния интерфейса: загрузка, пустой список, ошибка, нет прав;
требования к локализации.

Перед реализацией попросите ассистента:

прочитать AGENTS.md;
прочитать документацию RetailCRM по JS-модулям, собственным страницам, targets и навигации;
прочитать README и AI-документацию установленных пакетов @retailcrm/embed-ui*;
проверить MCP-ресурсы, если они настроены;
выбрать target или паттерн страницы;
перечислить профили компонентов и страниц, которые понадобятся;
указать, какие styling-правила из документации Embed UI относятся к задаче;
явно отделить подтвержденные источниками решения от проектных допущений.

Для интерфейса лучше задавать не формулировку «сделай как в CRM», а конкретный стандартный ориентир: «используй паттерн страницы со списком из профилей Embed UI», «для формы используй UiField и подходящие form controls», «для виджета в target оставь компактный inline UI». Если задача затрагивает отступы, типографику, классы или CSS-переменные, ассистент должен свериться с node_modules/@retailcrm/embed-ui-v1-components/docs/STYLING.md и профилями компонентов.

Если нужного правила нет в документации Embed UI, профиле компонента или STYLING.md, это не должно становиться догадкой ассистента. Такое решение необходимо записать в задаче как проектное уточнение, чтобы при ревью было понятно, где заканчивается стандарт Embed UI и начинается решение конкретного модуля.

5. Практический рабочий процесс с AI

Ниже описан практический прием работы с AI-ассистентом. Это не отдельное требование платформы, а способ снизить риск ошибок при агентской разработке.

Сначала попросите ассистента собрать короткий технический план без изменения файлов. В плане должны быть указаны:

выбранный тип интерфейса: widget target или собственная page;
page code или target;
доступные contexts и actions;
список компонентов Embed UI и профилей, которые нужно прочитать;
изменения в extensionrc.json и endpoint runner;
проверки, которые должны подтвердить результат.

Удобно проверять работу как одну связку: descriptor в extensionrc.json, соответствующий runner в endpoint, Vue-компонент, build/lint, публикация в тестовой CRM и фактическое открытие URL страницы или отображение виджета в target. Если в этой цепочке нет явного соответствия хотя бы в одном месте, AI-ассистент может сгенерировать корректный TypeScript, но нерабочий модуль.

После этого переходите к реализации небольшими шагами. Для AI-ассистента это важнее, чем большой запрос «сделай весь модуль»: чем меньше шаг, тем проще проверить, что ассистент не перепутал формат descriptor, page code, target или API компонента.

Минимальная рабочая проверка страницы

Для новой страницы сначала соберите минимальную рабочую версию и проверьте, что она открывается в CRM:

добавить page descriptor в конфигурацию модуля;
зарегистрировать тот же page code в endpoint runner;
создать минимальный Vue-компонент без сложной бизнес-логики;
выполнить npm run build и npm run eslint;
опубликовать или зарегистрировать модуль в тестовой CRM;
открыть страницу по /modules/<moduleCode>/<pageCode>.

Только после этого стоит добавлять таблицу, фильтры, запросы к backend-части и сложные состояния. Такой порядок помогает рано поймать ошибки формата pages, отсутствующего menu, несовпадения page code и runner или проблемы с entrypoint.

Что фиксировать в задаче

MCP-ресурсы и профили компонентов отвечают на вопрос «что технически доступно». Они не определяют бизнес-смысл модуля. Поэтому в задаче для AI-ассистента отдельно фиксируйте:

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

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

Демонстрационные данные лучше отделять от продуктовой логики с самого начала. Если для проверки интерфейса нужны временные записи, храните их отдельно от API-слоя, помечайте как mock или fixture и заранее фиксируйте, какие места должны быть заменены реальными backend-вызовами через host.httpCall().

6. Разработка виджетов и страниц

JS-модуль может регистрировать frontend-интерфейс двух типов: виджеты в существующих разделах CRM и собственные страницы внутри CRM.

Для новых JS-модулей рекомендуется использовать @retailcrm/embed-ui-v1-endpoint/remote. В дескрипторе frontend-части для такого сценария необходимо указывать:

{
  "runner": "worker"
}

Legacy-сценарий runner: "iframe" не рекомендуется использовать для новых модулей.

Виджеты на существующих страницах CRM

Виджет используется, когда модулю нужно добавить компактное действие или небольшой информационный блок в уже существующий экран CRM. Он размещается не на произвольной странице, а только в выделенной точке встраивания (target), где такая вставка разрешена платформой.

Подробный список targets и доступных в них данных описан в статье «Точки встраивания JS-модулей». Здесь достаточно зафиксировать практическое правило для агентской разработки: target нельзя выбирать по догадке из названия страницы. Укажите его в задаче сами или попросите AI-ассистента свериться со справочником.

Для подключения виджета в конфигурации модуля указывается target, а в endpoint runner регистрируется компонент, который должен отрисоваться в этом месте интерфейса. Например, order/card:common.after означает конкретную область карточки заказа.

В разных targets доступны разные contexts, custom contexts и actions. Перед генерацией кода попросите ассистента проверить, какие данные доступны в выбранной точке встраивания, и не использовать contexts или actions, которые не подтверждены справочником, target profile или MCP-ресурсом.

Если MCP настроен, ассистент может прочитать список targets и профиль нужного target перед генерацией кода. Например, для order/card:common.after он должен обратиться к resources:

embed-ui-v1-endpoint://targets
embed-ui-v1-endpoint://targets/order%2Fcard%3Acommon.after

По этим данным ассистент проверяет, где будет отрисован виджет и какие данные действительно доступны в этом месте интерфейса.

Собственные страницы модуля

Собственные страницы подходят, если модулю нужен отдельный экран внутри CRM: список сущностей, карточка, настройки или сложная форма. Для страниц используется конфигурация pages, endpoint запуска и адрес вида:

/modules/<moduleCode>/<pageCode>

Для страницы, которая должна открываться в CRM и добавляться в навигацию, используйте объектную форму pages с menu-настройками:

{
  "pages": [
    {
      "code": "order-review-requests",
      "menu": "activity_main_menu",
      "menuItemOrdering": 15,
      "menuItemTitle": {
        "ru": "Проверка заказов",
        "en": "Order reviews",
        "es": "Revisiones"
      },
      "pageHelpLink": null
    }
  ]
}

Коды разделов навигации для поля menu и доступные пункты меню приведены в справочнике навигации JS API. Используйте этот справочник, чтобы выбрать раздел CRM, в котором должен отображаться пункт собственной страницы модуля.

В endpoint этот же pageCode должен быть связан с Vue-компонентом:

import {
  definePageRunner,
  runEndpoint,
} from '@retailcrm/embed-ui-v1-endpoint/remote'

import OrderReviewRequestsPage from './pages/OrderReviewRequestsPage.vue'

const pageRunner = definePageRunner({
  'order-review-requests': definePageRunner(OrderReviewRequestsPage),
})

runEndpoint(pageRunner)

Примечание

Короткая запись страницы строкой задает только page code и не описывает пункт меню. Если страницу нужно открыть в CRM через навигацию, используйте объектную форму с menu-настройками. В окружениях, где API ожидает объект ConfigurationPage, строковая запись может быть отклонена при публикации; объект только с code может пройти регистрацию, но не создать пункт меню для открытия страницы.

Для списков сущностей используйте паттерн страницы со списком: UiPageHeader, фильтры над таблицей, UiTable, UiTableColumn, UiTableFooterSection, UiTableFooterButton. Состояние поиска, фильтров, сортировки и пагинации рекомендуется хранить в query string, если для страницы используется маршрутизация.

Навигация и query string

Для навигации и query string используйте публичный Host API:

import { useHost } from '@retailcrm/embed-ui'

const host = useHost()

host.goTo('crm_orders')
host.replaceQuery({ status: 'new' }, { preserveExisting: true })
host.pushQuery({ page: 2 }, { preserveExisting: true })

Для генерации ссылок по имени Symfony-маршрута используется useRouter(). Перед использованием useRouter() необходимо инициализировать context settings, потому что router использует settings.system.routing.

Для поддерживаемых переходов внутри CRM используйте Host API или useRouter(). Не собирайте URL страниц CRM вручную.

7. Проверка и публикация

Проверку после изменений удобно разделить на локальные команды, проверку конфигурации и проверку в CRM. В агентском workflow локальные команды и статическую проверку файлов можно поручить AI-ассистенту. Публикацию и проверку результата в тестовой CRM выполняет разработчик или ассистент, если у него есть необходимые доступы и явно указана команда публикации.

После изменений во frontend-части попросите ассистента выполнить базовые проверки проекта и показать результат:

npm run build
npm run eslint

Перед публикацией попросите ассистента проверить согласованность extensionrc.json, endpoint worker и build-артефактов. Это можно проверить по файлам проекта без доступа к CRM:

targets из extensionrc.json зарегистрированы в defineWidgetRunner;
pages из extensionrc.json зарегистрированы в definePageRunner;
для frontend-части указан runner: "worker";
для собственных страниц используется объектная форма pages;
для страницы, которая должна открываться в CRM, задан menu-конфиг;
entrypoint указывает на JS-файл endpoint;
stylesheet указан, если frontend-часть публикует CSS.

Пример дескриптора frontend-части:

{
  "code": "retailcrm-extension-frontend",
  "version": "1.0.0",
  "targets": [
    "order/card:common.after"
  ],
  "pages": [
    {
      "code": "order-review-requests",
      "menu": "activity_main_menu",
      "menuItemOrdering": 15,
      "menuItemTitle": {
        "ru": "Проверка заказов",
        "en": "Order reviews",
        "es": "Revisiones"
      },
      "pageHelpLink": null
    }
  ],
  "entrypoint": "extension.js",
  "runner": "worker",
  "stylesheet": "extension.css"
}

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

виджет отображается в нужном target;
страница открывается по адресу /modules/<moduleCode>/<pageCode>;
пункт меню появился в ожидаемом разделе, если страница должна быть доступна из навигации;
тексты отображаются на поддерживаемых локалях;
запросы frontend-части к backend-части выполняются через разрешенный механизм;
ошибки выводятся пользователю понятным текстом.

8. Ограничения и контроль качества

AI-ассистент может ошибаться в деталях интерфейса, если в доступных источниках нет точного правила. По результатам проверки работы с Embed UI особенно важно контролировать:

не использует ли ассистент нативные button, input, select, table, a, когда есть компонент Embed UI;
нет ли импортов из @retailcrm/embed-ui-v1-components/dist или внутренних путей пакета;
не используется ли @retailcrm/embed-ui-v1-components/host в обычном frontend-коде модуля;
не стилизуются ли внутренние .ui-v1-* классы без подтвержденного правила из профиля или STYLING.md;
не задан ли произвольный font-family, например Arial или Inter, вместо наследования стилей host/компонентов;
совпадают ли отступы, размеры, line-height, font-weight и состояния с профилем компонента и STYLING.md;
есть ли локали ru-RU, en-GB, es-ES;
синхронизированы ли extensionrc.json, endpoint runner и фактические страницы/виджеты.

Если в задаче есть требование к интерфейсу, которого нет в профиле компонента или STYLING.md, не выдавайте его за стандарт Embed UI. Зафиксируйте его как отдельное требование конкретного модуля и проверьте вручную при ревью.

9. Как сформулировать хороший промпт

Универсальный промпт для всех JS-модулей быстро становится слишком длинным и неточным. Лучше собирать запрос из понятных частей: задача, источники, ограничения и ожидаемая проверка результата.

При постановке задачи AI-ассистенту используйте следующие правила:

описывайте пользовательский сценарий, а не только экран: что пользователь должен увидеть, сделать и получить в результате;
указывайте тип интерфейса: виджет в target, собственная страница, модальное окно или боковая панель;
называйте target, page code и route, если они уже выбраны; если не выбраны, попросите ассистента предложить вариант и подтвердить его по документации или MCP-ресурсам;
отдельно указывайте, откуда берутся данные: из contexts, backend-части модуля, CRM API или временного тестового набора;
просите ассистента заранее перечислить профили компонентов, page profiles, MCP-ресурсы и документы Embed UI, которые он использует;
задавайте UI-ориентир через стандартные компоненты и профили Embed UI, а не через общую формулировку «сделай как в CRM»;
запрещайте неподтвержденные импорты, ручную сборку URL CRM, нативные контролы вместо компонентов Embed UI и стилизацию внутренних .ui-v1-* классов без правила из профиля;
просите перед изменением файлов коротко описать план: что будет изменено в extensionrc.json, endpoint runner, компонентах и локалях;
просите после реализации выполнить доступные проверки и явно указать, какие проверки не были выполнены из-за отсутствия доступа к тестовой CRM;
просите короткую самопроверку результата: какие решения подтверждены источниками, какие допущения сделаны, какие команды выполнены и какие места требуют ручного ревью.

Благодарим за отзыв.

Была ли статья полезна?

Нет

Да

Предыдущая статья

Доступные для JS-модулей роуты страниц

Справочник роутов, доступных для js-модулей, для создания ссылок на страницы системы

Разработка JS-модуля RetailCRM с AI-ассистентом Скопировать ссылку на статью Скопировано