Characteristics: definitions, groups, templates, values and filters

Статус: current · проверенный: 2026-10-27, live Запросы с a catalog:* key На стенде, построенной из production (§10) и в каждом из них указаны section владелец: гладиатр API документация · Служить: GET /docs/characteristics · мастерство: vizen-catalog связанный: /docs/catalogue §8.3 (кто видит характерные черты)) · /docs/catalog-import (наполнение products, variants)

1.Что вы можете сделать здесь

Опишите, что такое shop Продажа в структурированном виде fields — material, width, власть, warranty — вместо того, чтобы free text, и Решать, где каждый field Появляется: product card, listing cards, тот filter панель из а section, тот таблица сравнения, variant Все нижеперечисленные устройства открыты для key с catalog:read / catalog:write; Единственным исключением является template's price layout (§7.4, pricing:*).

Характеристика является set один раз на shop и затем используется в четырех независимых местах. failed set-Ups Miss Один из них, получить 200 Везде и ничего не видно на витрине:

definition (/attributes) ── options (select/multiselect)
   │            └─ access: who sees it, on which surface (/attributes/{id}/access) ← new = hidden
   ├─ value on a product            PUT /products/{id}/attributes · import "attributes"
   ├─ binding to ONE section        PUT /categories/{id}/attributes     → card order + filter panel (§6)
   └─ row of a template ─ group     /char-groups · /spec-templates/{id}/items
          └─ template bound to a section, inherited down the tree  PUT /categories/{id}/spec-settings
                └─ values of a section ("model")                  PUT /categories/{id}/values

2. Решать first

3. Определение — /attributes

POST /attributes
{ "item": { "code": "width", "name": "Ширина", "data_type": "number", "unit": "см",
            "section": "Размеры", "is_filterable": true, "sort_order": 10 } }

3.1 Типы — что отправить и что видит покупатель

Измеряется на одном product, каждый type написанный через PUT /products/{id}/attributes:

Неправильная форма — это 400 называть field: attribute "width": expected number value, unknown option "zzz", invalid date "27.10.2026" (RFC3339 or YYYY-MM-DD). null, ан empty list и ан empty string В смысле нет value" — тот row не написаны, ибо color и url ан empty string это Запись, хранящаяся. set (group) принимает только list Документы (§5.1)).

Выбери type Что покупатель будет с этим делать: выбирать (select — фильтры, топоры, часы), compare а range (number с unit), читать (string). Характеристика должна быть как фактом, так и переключателем (width 140/180 на выбор, должен быть select с options 140, 180 и этикетки 140 см, 180 см — а number может never Стать осью (§9)).

3.2 Изменение определения, которое уже имеет values

• Имена, которые доходят до каждого card сразу (с 2026-10-28). А new name, вариант label, unit, section или sort_order, а deleted характерные и а new order из одного section's Обязательные знаки показывают на product cards без пересылки values. А. dev key's Изменения показывают after публикацию; до этого момента live cards keep тот старый text.
• меняться `data_type` Принято и сломает старое values. number → string На характерной для values ответы 200; тот cards keep Показаны старые number, и пересылать обратно products' старый values теперь Неудачи с expected string value. Создать new характерным вместо этого и move тот values.
• Рекорд set cannot изменение type, И никакая другая характеристика не может стать: 400 RECORDS_TYPE_LOCKED.

3.3 Кто это видит

Характеристика, сохраненная для first Время пришло hidden от покупателей (visibility: staff, version 0) - на card, в списках, в фильтрах и в таблице сравнения — до тех пор, пока не будет написана запись доступа. full правила есть /docs/catalogue §8.3 Короткометражный form:

GET /attributes/412/access                  # read version and flags first
PUT /attributes/412/access
{ "expected_version": 0,
  "access": { "visibility": "public", "show_storefront_card": true, "show_storefront_list": true,
              "show_admin_product": true, "show_admin_list": true, "show_api": true, "show_export": false } }

PUT Заменяет весь рекорд — флаг, который вы оставляете, становится false. show_storefront_card Это product page и сравнение; show_storefront_list это listing cards и filter панель (§6). Открытие а Характеристика открывает его на каждом product из shop Скажите это сразу же, owner first.

3.4 Где он приземляется на product card

Карта («О чем-то») product") Список product's собственный значения, сгруппированные по определению's section text. У ордена есть один ключ: sort_order характеристической's связывание с product's section (§6.1 когда есть Это одно, иначе определение's sort_order; галстуки идут id. Новый порядок достигает карты сразу; перемещение product к другому section Меняет порядок только тогда, когда его значения снова записаны.Когда есть два или более разделов, каждый получает заголовок — и Заголовок - это section string Сама по себе. characteristics напечатано как есть, так писать `section` в покупателе's язык ("Размеры", "Материалы"). Группы и шаблоны (§7) не Изменить обычную карту.

4.Варианты — The values из select и multiselect

"options": [ { "value": "oak", "label": "Дуб", "sort_order": 0 },
             { "value": "black", "label": "Чёрный", "color_hex": "#222222" },
             { "value": "walnut", "label": "Орех", "image_id": "<file uuid of an icon>" } ]

• value Это машина key products магазин: ^[a-z0-9][a-z0-9_-]{0,63}$ (цифрой first допускается: 128).
• Всегда посылать `label`. Без этого card Отпечатки сырой value (c), и а variant переключатель рисует empty button (unit Кнопки тоже не добавляются — пишите 140 см входить label).
• color_hex краски a swatch; image_id является icon от shop's files для icon / photo.
• Варианты являются a replace-set. Чтобы добавить один, прочитайте определение и отправьте full Список плюс new вариант. Варианты получают new ids На каждой записи — products keep Работают потому, что хранят value, Но все, что вы Оставлено по выбору id должен быть перечитан.
• Удаление опции, которая products использование отказано: 400 OPTION_IN_USE:<values>. Переместите их products то другой value first.
• "options": [] в PUT /attributes/{id} означает "оставить" options Как они есть, не "удалить все". Нет Это позволяет опустить список существующих характеристик..

5.Ценности на products

Оба пишут replace тот set: а product это было material, цвет и width и получает только warranty только держит warranty. PUT …/attributes с "items": [] Проясняет product. Ан import row Заменяются только когда attributes не является-empty; ан empty Список оставляет values неприкосновенность и очищение "attributes": [], "attributes_replace": true. Изменить одну характеристику на многие products, Читать каждый product's set и отправить обратно Все вместе с одним value Меняется.-side Списки не return hidden characteristics навалом (attribute_codes Ответы как покупатель, так что чтение - это одно из GET /products/{id} за product.

рекорд sets являются исключением. Рекорд set (§5.1. что запрос не name Хранит свои записи, в live в каталоге и в draft, Даже если это было написано кем-то раньше. else: Обновление цвета и width через key never - стирает отзывы. - Два писателя то же самое set: Последний выигрывает. Удалить set, Отправьте его с null или []. The для тех же целей, что и для PUT /categories/{id}/values. Импорт не пишет и не очищает записи sets: а row с а set получает row error "<code>" is a record set.

5.1 Рекорд sets (group)

Рекорд set ведет повторяющиеся записи — галерею, обзоры, вопросы и ответы, авторов, документы — внутри product или section: data_type: "group", тот schema Один рекорд в ui_settings.records, Список как value. Рекорды не являются наследственной, а set не имеет default и является never а filter; sets выбывший из а values запросить keep Их записи. site Прочитал их через public GET /record-sets (Базовый 64 конверт, always проход code). Все — schema, values, Доступ покупателя, чтение для site, компонент, который показывает set — в `/docs/record-sets`.

6 Фильтры в section

Витрина спрашивает GET /products?filter.category_id=<id> и вытаскивает панель из filterable_attributes Ответ: Панель построена в одном из два пути — Второй же, безмолвно заменяющий first.

6.1 Без этого template: тот section's own связывание

Характеристика появляется в панели только тогда, когда Все три держать:

1. Он обязан это section — PUT /categories/{id}/attributes;
2. Его определение имеет is_filterable: true;
3. Доступ открыт в списках (visibility: public или сравнительный audience, show_storefront_list: true).

PUT /categories/12/attributes
{ "items": [ { "attribute_id": 38, "sort_order": 0 },
             { "attribute_id": 41, "sort_order": 1 } ] }

Обязательства являются a replace-set за section (Всех их посылать и не наследуемый: подраздел created В разделе «Таблицы» есть empty Пока не получит свой own связывание. is_required и default_value на Связывание хранится для шкафа form и не applied то products. Обязательный's sort_order также orders тот card (§3.4).

6.2 С помощью template: тот template's rows

Когда section имеет эффективную template (§7.3 - его own или унаследованных от предков, то эта панель является template's rows обозначенный filterable_here: true, в template order, фильтруется доступом, как указано выше. is_filterable и section's own Тогда связывания ignored. Измерение: а section фильтруемый material через Обязательная потеря, что filter момент a template только с width Шаблоны наследуются, так что один template На корне section В каждом подразделе одна и та же панель.

6.3 Что такое filter может совпадать

GET /products?filter.category_id=12&attribute_filters[0].attribute_id=38&attribute_filters[0].values=oak
GET /products?filter.category_id=12&attribute_filters[0].attribute_id=41&attribute_filters[0].min=100&attribute_filters[0].max=160

Индексированный синтаксис, до 20 фильтров, в сочетании с AND (/docs/catalogue §4; с curl добавлять -g, или Скобки принимаются как шар). values Каждый матч type по его хранимой форме (с 2026-10-28)): select вариант values, точный string values, любой из них options из одного multiselect, true/false для bool, YYYY-MM-DD для date, точный text из color и url; min/max матч number. Покупатель, фильтрующий по характеристике, скрытой от списков, получает 400 ATTRIBUTE_FILTER_NOT_AVAILABLE.

Фильтры соответствуют product's own values только. А. value а product наследуется от его section или от одного default (§8) находится в /products/{id}/spec Но не найдено в filter — писать values вводить products Если покупатели должны filter Ими же. model section's own listing фильтров в его products' fields; тот model's Справочные характеристики являются фильтруется на родителя section.

7. Группы и шаблоны

Используйте их, когда несколько sections Один из структурированных set (автомобили: двигатель, трансмиссия, габариты, когда values должны быть унаследованы от section (§8, или когда одна ветвь нуждается в own filter панель (§6.2)).

7.1 Группы — /char-groups

По имени block из characteristics внутри template (Двигатель, Размеры):

POST /char-groups
{ "item": { "code": "dimensions", "label": { "ru": "Размеры", "en": "Dimensions" }, "sort_order": 1 } }

GET /char-groups Перечислите их; PUT /char-groups/{id} является частичным; DELETE Это мягко.Читать return id, code, sort_order и а name взятый из label.ru (или любой не-empty Язык) — не сохраненный label, description или display, И не читается ни одного group через id: keep Что ты написал. group используется только через template rows — регулярно product card Сохраняйте группировку section (§3.4).

7.2 Шаблоны — /spec-templates

POST /spec-templates
{ "item": { "code": "tables", "name": "Столы", "applies_to": "product" } }

PUT /spec-templates/1/items                       # replace-set, up to 500 rows
{ "items": [
  { "char_group_id": 1, "attribute_id": 43, "group_sort_order": 0, "attribute_sort_order": 0,
    "is_summary": true, "filterable_here": true },
  { "char_group_id": 1, "attribute_id": 42, "group_sort_order": 0, "attribute_sort_order": 1,
    "default_value": "массив" } ] }

applies_to на template это free text для тебя own бухгалтерия; платформа не действует на нее;.

`GET /spec-templates/{id}/items` не return `default_value`. Чтение rows и писать их обратно стирает каждый row default. Держите дефолты на своем side И посылать их всем вместе. PUT …/items.

7.3 Обязательная связь template в section — /categories/{id}/spec-settings

PUT /categories/12/spec-settings
{ "mode": "append", "bindings": [ { "template_id": 1, "sort_order": 0 } ] }

append и replace Необходимо хотя бы одно связывание (SPEC_MODE_REQUIRES_TEMPLATES). Прочти result с GET /categories/{id}/spec: каждый row перевозить source: "category:<id>" — тот level Оно пришло из.

7.4 Цена rows в template

А. template Также можно носить price fields рядом с characteristics. Это смешало layout это GET|PUT /spec-templates/{id}/layout и потребности pricing:read / pricing:write; описывается в /docs/pricing. PUT …/layout заменять оба части сразу: а body с характерным rows только удаляет тот template's price rows. PUT …/items характерные прикосновения rows только. GET …/layout Также читается возвращает row дефолт.

8. значения a section ("model") и эффективного value

А. section может нести values Сама по себе — эталонные характеристики автомобиля model Каждый listing Под его акциями:

PUT /categories/12/values                         # replace-set, up to 500
{ "items": [ { "attribute_id": 43, "state": "value", "value": 99 },
             { "attribute_id": 42, "state": "clear" } ] }

GET /products/{id}/spec решает каждый row Эффективное template, first победа в матче:

the product's own value  >  nearest section  >  ancestor sections  >  template default_value  >  definition default_value

state: "clear" Остановить поиск: The row решает "нет" value" Даже если предок или default имеет один. state: "value" с ан empty или null value не хранится — row Возвращается к наследованию. product cannot clear унаследованный value: его own values не иметь clear Государство, только value его own переопределение. value_source Названия победителей: product, category:<id>, template_default, definition_default. Измерение: а product без своей own вес resolved 99 из category:79; а product с 12.5 его own хранить 12.5.

Покупатели не видят section values на регулярной product card или в таблице сравнения — Оба списка только тот product's own values (§3.4. Раздел values Покупатели могут получить только через model blocks из model sections (GET /categories/{id}/spec, тот is_summary плитка); GET /products/{id}/spec Это shop команда's Читать.Показать разделяемый value На каждый регулярный card, Запишите его в каждый product (один import).

9. Характеристики переключателей

• 2.1.1 Ось вариантов (Выбор внутри одного product): только select. PUT /products/{id}/variant-axes, затем PUT /products/{id}/variants — набор без is_active находится, false переключать его off (before 2026-10-28 комплект без него сохранился off). Полный сценарий — /docs/catalog-import §5.
• ось группировки (отдельные продукты, связанные с одним коммутатором: только select; /product-groups. Один Характеристика не может быть как вариантной осью, так и группирующей осью одного и того же product.
• Взгляд переключателя является характеристикой's widget и ui_settings; а product Ось может сузить его с помощью own display ("" · text · icon · swatch).
• А. product's вариант и его own Характеристика одного и того же name Независимость: стул с цветом переключатель и характерная Цвет: Натуральный Не сохраняйте один и тот же факт в обоих.
• number → Коммутатор: создайте отдельный select характерный (table_width, options 140/180, этикетки 140 см/180 см) Используйте его как ось; решайте с владельцем, является ли старый number оставаться на карточка.

10. Рецепт: одна характеристика, конец-конец

Цель: «ширина, см» на каждом столе, фильтруемая на столах section и его подразделы.

1. GET /attributes — повторно использовать существующий width before Создание одной «ширины» сбивает с толку каждого читателя.
2. POST /attributes {"item":{"code":"width","name":"Ширина","data_type":"number","unit":"см","section":"Размеры","is_filterable":true}}.
3. Доступ: GET /attributes/{id}/access → PUT с public, show_storefront_card, show_storefront_list, show_api — after говорить owner Он открывается на каждом product.
4. Ценности: один POST /products/import с каждым столом's full attributes (§5).
5. Filter: один section → PUT /categories/{id}/attributes с все фильтры; ветвь → template row с filterable_here прикреплен к корню ветви с append.
6. Проверить, а не 200:
   • GET /products/{id} → attribute_sections иметь Ширина 140 см;
   • без key: GET /products?filter.company_id=<shop_id>&filter.category_id=<category_id>&page.number=1&page.limit=1 → filterable_attributes список width (Без ключа список без filter.company_id ответы 403 AUTH_COMPANY_PROBLEM);
   • с помощью key: curl -g '…/products?filter.category_id=<category_id>&attribute_filters[0].attribute_id=<attribute_id>&attribute_filters[0].min=100&attribute_filters[0].max=160&page.number=1&page.limit=1' → total капли;
   • тот section page На витрине магазина показывается панель.

Обратный путь: Unbind (PUT /categories/{id}/attributes с предыдущим списком или с предыдущим spec-settings),

• закрытый доступ, удаление ценностей из продуктов (импорт с их оставшимися) attributes, или

"attributes": [], "attributes_replace": true Когда ничего не остается, и только после этого исключить определение.

11.Безмолвно ignored или удивительный

12. Ограничения и ошибки

• options По определению: 10000; values за product Писать и писать section Написать: 500; template rows: 500; переплетение на spec-settings: 100; фильтры на list Запрос: 20.
• А. variant ось на product card и в списках переносит весь словарь до 200 options; выше 200, только values тот product's sets или группировать members использовать.
• Определения и options: 400 INVALID_CODE · INVALID_DATA_TYPE · INVALID_WIDGET · INVALID_OPTION_VALUE · INVALID_UI_SETTINGS · OPTION_IMAGE_NOT_FOUND · OPTION_IN_USE:<values>; 409 ATTRIBUTE_CODE_TAKEN · OPTION_VALUE_TAKEN:<value> (Дублированный вариант value, нечувствительный к делу).
• Значения и связывания: 400 DUPLICATE_ATTRIBUTE_IN_SET · а value-форма message Назвать характеристику; 400 ATTRIBUTE_FILTER_NOT_AVAILABLE для покупателя's filter на hidden характерный.
• Шаблоны: 400 DUPLICATE_ATTRIBUTE_IN_TEMPLATE · SPEC_TEMPLATE_LAYOUT_INVALID · TEMPLATE_NOT_FOUND · SPEC_MODE_REQUIRES_TEMPLATES. топоры: 400 AXIS_MUST_BE_SELECT · AXIS_ALREADY_GROUP_AXIS (variant Ось уже a ось группировки) · AXIS_IS_MEMBER_VARIANT_AXIS (обратное) · INVALID_AXIS_DISPLAY · DUPLICATE_AXIS_IN_SET.
• рекорд sets: 400 RECORDS_SCHEMA_INVALID: <field path>: <reason> · RECORDS_VALUE_INVALID: <code>[<n>].<field>: <reason> · RECORDS_TOO_MANY · RECORDS_TOO_LARGE · RECORDS_NOT_FILTERABLE · RECORDS_NO_DEFAULT · RECORDS_TYPE_LOCKED; GET /record-sets: 400 RECORDS_FIELD_UNKNOWN (тот field это unknown или hidden) · RECORDS_RESPONSE_TOO_LARGE, 403 RECORDS_ALL_NEEDS_ROLE.
• Доступ: 409 ATTRIBUTE_ACCESS_VERSION_CONFLICT.
• Другой shop's или deleted характерный: 404 ATTRIBUTE_NOT_FOUND из product values, section связывание, оси и доступ; 404 not_found из PUT/DELETE /attributes/{id}; 400 UNKNOWN_ATTRIBUTE из PUT /categories/{id}/values.

13.Как это было проверено

2026-10-27, стенд, построенный из production (d506644a), Свежий магазин и ключ от catalog:* + storage:*. Каждый тип §3.1 был создан и написан на одном из них. product и перечитывать их; переименовывать и data_type Изменения измерялись на одном и том же product (§3.2; переименование, label и удалить повторно измеренные на 2026-10-28 после Ремонт, с ключом dev и иностранным магазином's ключ); OPTION_IN_USE отбрасывая использованный вариант; фильтры читать filterable_attributes без ключа после каждого шага — без привязки, привязки с закрытым доступом, доступом открытый, подраздел, шаблон, связанный с append, Открыт шаблонный ряд (§6); соответствие граней для каждого типа с собственник's ключ и в качестве покупателя (§ 6.3)); section ценностей и /products/{id}/spec Источники по двум продуктам (§8)); DELETE /attributes/{id} против карточки А product удерживая его value (§3.2) Пределы проекции на чтение группы и шаблонные строки, макет replace Исключительность оси прослеживается в code независимой Проверка только в тот же день (set_spec_template_items, spec_template_layout.go, list_char_groups.go, set_product_variant_axes.go, set_group_axes.go). Источники: internal/core/domain/attribute.go, internal/api/catalog/attributes_repack.go, edit_attribute.go, get_products.go (categoryFilterableAttributes), internal/adapters/repositories/pg/attributes.go (buildAttributeSections, GetCategoryFilterableAttributes), internal/core/services/spec/resolve.go, vizen-market/storefront/src/blocks/SystemProductCard.tsx.