4cms-resolve

⚡ Этот скилл — для вызова через тул Skill(4cms-resolve), не через Read .../SKILL.md.

4cms Resolve

Превращает имя или ссылку в реальные идентификаторы сущностей витрины (id, slug, url), которые потом кладутся в bindings блоков PageCraft и в ссылки лендинга.

Зачем: у блока есть SSR-источник вроде catalog.products с параметром rubric_id, а в плейсхолдере — ссылка на бренд. Чтобы их заполнить, нужен настоящий id рубрики и настоящий url бренда с витрины клиента. Этот скилл их находит.

Граница доменов. Это 4cms — «на какие реальные сущности витрины ссылаемся». Создание/сборка/публикация самой страницы — это PageCraft (pagecraft-pages и пр.). Не путай: здесь мы только находим сущности, мы их не создаём и не публикуем.

Предусловие

В .env нужен домен витрины (FOURCMS_DOMAIN). Обычно его не задают руками — 4cms-env выводит его из ключа через /info и кэширует. Если скрипт падает с FOURCMS_DOMAIN not set — вызови Skill(4cms-env). Сам токен API для резолва по имени/URL не нужен (ручки публичные) — достаточно домена.

Установка зависимостей (один раз): npm install --prefix .claude/skills/4cms-resolve

Основной инструмент

node .claude/skills/4cms-resolve/scripts/resolve.js "<имя или url>" [--type brand|rubric|product]

Скрипт сам выбирает путь:

• имя («adidas», «кепки») → поиск по витрине, на выходе кандидаты с id/slug/url;
• url или путь («https://site/r-fashion», «/brand-nike») → прямой резолв ссылки в сущность.

--type фильтрует выдачу по типу, когда заранее известно, что ищем именно бренд / рубрику / товар.

Формат выдачи

{
  "query": "кепки",
  "count": 4,
  "candidates": [
    { "type": "rubric", "id": 1288464, "name": "Кепки", "slug": "mens-caps",
      "url": "https://bjjd.ru/r-mens-caps", "note": "Аксессуары / Головные уборы",
      "variation_code": "", "source": "suggest" }
  ]
}

• id — то, что чаще всего идёт в bindings (rubric_id, brand_id, id товара).
• url — для ссылок в плейсхолдерах блока.
• note — хлебные крошки/контекст; используется для дизамбигуации (см. ниже).
• exact_match — true, если имя/slug кандидата точно совпали с запросом. Кандидаты отсортированы: точные совпадения первыми. Поиск часто подмешивает похожие (на «adidas» → «adidas Originals», «adidas neo»). Правило: ровно один exact_match: true → это он; несколько exact_match: true (как одноимённые рубрики «Кепки») → настоящая неоднозначность, см. п. 2 ниже; ни одного → ищи ближайший по смыслу или уточни.
• variation_code — код вариации сайта (часто пустой = дефолтная).

Как пользоваться результатом

1. Один кандидат нужного типа → бери его id/url. Готово.
2. Несколько кандидатов одного типа (как 4 рубрики «Кепки» с разными note) — это неоднозначность. Не угадывай молча: покажи пользователю варианты по note и спроси, какой из них имелся в виду. Карточка-вопрос с коротким списком — один вопрос, в конце сообщения.
3. Товаров из поиска приходит немного (автокомплит, ~5). Этого достаточно, чтобы зарезолвить конкретный товар по названию. Для выборок товаров (все товары бренда/рубрики с фильтрами и сортировкой) поиск не годится — это задача источника catalog.products в bindings (туда кладётся rubric_id/brand_id, а сами товары подтянет рендерер).

Что кладём в bindings (стыковка с PageCraft)

Скилл отдаёт идентификаторы — а что именно просит блок, определяет paramsSchema его источника (узнаётся через PageCraft, напр. GET /api/v1/blocks/{id}/placeholder-schema). Типичные сопоставления:

Хочет источник/плейсхолдер	Берём из кандидата
params.rubric_id	id рубрики
params.brand_id / filter_brands	id бренда
ссылка на бренд/рубрику в плейсхолдере	url
конкретный товар	id товара

Кладём в bindings только то, что реально есть в paramsSchema источника. 4cms и реестр источников PageCraft — независимы: если источник принимает только rubric_id, резолвим рубрику, даже если витрина умеет больше.

Когда уже есть ссылка

Если пользователь дал ссылку с витрины — передай её скрипту напрямую (без поиска): resolve.js "https://site/r-...". Это и резолвит сущность, и заодно валидирует ссылку (что она ведёт на реальную рубрику/бренд/товар) и сообщает page_type.

Подробности и разбор ошибок

references/resolve-chain.md — как устроена цепочка suggest → url/info, префиксы URL витрины, частые проблемы (пустая выдача, дубли имён, товар без slug).

Если резолв не находит — проверь источники руками (оба публичные, без ключа):

• url/info (по URL): Swagger https://siteapi.4partners.io/, либо прямо в браузере: https://<FOURCMS_DOMAIN>/i/url/info/https://<FOURCMS_DOMAIN>/<path>.
• suggest (по имени): сваггера нет — открой в браузере https://<FOURCMS_DOMAIN>/atlas/webapi/suggest.json?query=<строка> и посмотри сырой ответ.
• Каталог по id (детали) — в Swagger 4cms https://api.4partners.io/ (нужен X-Auth-Token).

Что не делает этот скилл

• Не создаёт и не публикует страницы — это PageCraft (pagecraft-pages).
• Не тянет полные карточки/тексты товаров — только идентификаторы (контент подтянет рендерер по id).
• Не делает фильтрованные выборки товаров и не обходит дерево рубрик целиком — это планируются отдельные скиллы (4cms-products, 4cms-catalog), они ходят в аутентифицированный API.
• Не настраивает .env — это 4cms-env.