Record sets: repeating records in products and sections

Статус: current · проверенный: 2026-10-31, tools/mcpcheck/scenarios/record-sets.json (REST steps через key) и трех компонентов, построенных на key на позиции (§7)) владелец: гладиатр API документация · Служить: GET /docs/record-sets · мастерство: vizen-catalog связанный: /docs/characteristics (definitions, Доступ §3.3, шаблоны §7) · /docs/components (многоразовый blocks)

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

Держите galleries, отзывы, вопросы и ответы, авторы, команда members документы как структурированные записи внутри а product или section, и показать их в site. Рекорд set является характеристикой type group: тот Определение содержит fields по одной записи, каждая product или section держится за own Список записей. site читать через один public конечный пункт, для многих products сразу, только с fields показывает.

2. Решать first

Записи есть never наследственное: а product показывает его own set, а section его own. А. set не имеет default value и является never а filter.

3. Объекты и где они находятся live

Определение. POST /attributes с data_type: "group"; тот schema это ui_settings.records:

{"item": {"code": "faq", "name": "Questions", "data_type": "group",
 "ui_settings": {"records": {
   "fields": [
     {"code": "question", "name": {"ru": "Вопрос", "en": "Question"}, "type": "text", "required": true},
     {"code": "answer", "name": "Ответ", "type": "textarea", "required": true},
     {"code": "note", "name": "Заметка", "type": "text", "internal": true}],
   "columns": ["question"], "title": "{{question}}", "max_items": 50,
   "views": [{"code": "acc", "kind": "accordion", "default": true}]}}}}

• Типы полей: text (≤ 500 персонажей), textarea (≤ 10,000), number (min/max), bool, select (options: [{value, label}]), date (YYYY-MM-DD), url (https://, http:// или /…), image и file ({"file_id": "<uuid>"}; image Также берется alt, file брать title), product и category (ан id из это shop). max_len сужается a text field. Неизвестные ключи в schema является error.
• columns и title форма row в заднем офисе; views и seo Они являются намеками на site, спина Офис не редактирует их.
• `internal: true` — возвращенный обратно, по возвращении source читать ниже, never через /record-sets покупателям.
• is_filterable → 400 RECORDS_NOT_FILTERABLE; а default value → 400 RECORDS_NO_DEFAULT; меняя type или от group → 400 RECORDS_TYPE_LOCKED.

ценности. Чтобы изменить несколько записей, используйте PATCH …/records/{code} (§4.5: касается только ваших записей name. То replace целое set: а product — PUT /products/{id}/attributes. А. section: PUT /categories/{id}/values — каждый row также потребности "state": "value":

PUT /products/7/attributes
{"items": [{"attribute_id": 42, "value": [
  {"question": "Other colours?", "answer": "24 colours, 7 extra days."},
  {"_id": "q2", "question": "Assembly?", "answer": "Free in town.", "_active": false}]}]}

PUT /categories/9/values
{"items": [{"attribute_id": 42, "state": "value", "value": [{"question": "Delivery?", "answer": "Two days."}]}]}

• Рекорд set который отсутствует в запросе, ведет свои записи. Удалить запись set, отправлять [] как бы value.
• Обычный characteristics Заменяются: отправляют values в том же запросе, в противном случае они будут (/docs/characteristics).
• Когда вы меняете запись set с PUT, присылайте весь список его записей. Записи, которые отсутствуют в new список deleted.
• POST /products/import Не записывать рекорды sets: а row Если один не справляется. products, Затем заполнить sets с PATCH …/records/{code} или PUT.
• Сервер выдает каждый new рекорд _id (8 символов) и _created; Измененный рекорд _created и получает _updated. Твой own _id (^[a-z0-9]{1,16}$) - делает повторную идемпотентную. без _id это new: это получает new id и date, так always Отправьте существующие записи обратно _id.
• Неизменный рекорд принимается, как есть. after тот schema изменены; а new или измененная запись проверяется против current schema (а field удаленный из schema должен быть исключен из измененного списка).
• Файлы, products и sections должны принадлежать к shop Живой (живой) – draft file только в его own draft. Ан image field сделать снимок: MIME type или расширение говорит так, или - правильно after Загрузка, в то время как оба empty — а file created с fileType: "image".

Чтение source before Вы редактируете (file ids, internal fields, переключатель-off Записи: один set — GET /products/{id}/records/{code} или GET /categories/{id}/records/{code} (§4.5). Все. values — а product: GET /products/{id}/spec (тот template's characteristics плюс product's own sets снаружи template); а section: GET /categories/{id}/values.

4. Рецепты

4.1 Открыть set покупателям

А. new Характеристика закрытая; /record-sets Ответы без этого set. Читать GET /attributes/{id}/access, Затем отправьте целое рекордсменом PUT /attributes/{id}/access и expected_version Из прочитанного — опущено Флаги становятся false:

{"expected_version": 3, "access": {"visibility": "public", "show_storefront_card": true,
 "show_storefront_list": true, "show_admin_product": true, "show_admin_list": true, "show_api": true}}

потребности catalog:read/catalog:write и ан owner или администратором за key. visibility: "audience" limits тот set на один audience: all (Все), authenticated (зарегистрированных покупателей) или roles (клиент roles). управление аудитории и roles это customers:* (чувствительный, закрытый для draft key) — а public компонент never нуждается в.

4.2 Читать далее site — GET /record-sets

Публично. key без catalog:read Получить анонимный ответ, только all=true Позвоните по телефону. API происхождение (api_base из GET /v1/account/token), Не на витрине: витрина не имеет /record-sets Проверь витрину магазина. page Это происхождение доступно для посетителя. (CORS позволяет витрина, HTTPS на HTTPS page); 127.0.0.1 Работает только на одной машине.

Более 10 ресурсов требуют именно одного. code и limit ≤ 20. HTTP Ответ: {"result": "<base64>"}. Декодировать result от базовой 64 до bytes, декодировать bytes как UTF-8, затем разберите JSON. Не использовать JSON.parse(atob(…)): Разбивает кириллические буквы.

const url = new URL('/record-sets', apiBase);
url.search = new URLSearchParams({company_id: '1', product_ids: '7', code: 'reviews',
  fields: 'author,rating,text', stats: 'rating', limit: '20'});
const res = await fetch(url, {credentials: 'omit'});
if (!res.ok) throw new Error('record sets ' + res.status);
const {result} = await res.json();
const bytes = Uint8Array.from(atob(result), (c) => c.charCodeAt(0));
const data = JSON.parse(new TextDecoder('utf-8').decode(bytes));
const set = data.resources.find((r) => r.kind === 'product' && r.id === 7)?.sets.find((s) => s.code === 'reviews');

{"resources": [{"kind": "product", "id": 7, "name": "Sofa", "url": "/sofas/island",
  "sets": [{"code": "reviews", "name": "Reviews", "total": 12, "offset": 0, "limit": 20, "next_offset": null,
    "view": {"code": "cards", "kind": "cards"}, "stats": {"rating": {"count": 12, "avg": 4.7, "min": 3, "max": 5}},
    "items": [{"_id": "q1", "author": "Ira", "rating": 5, "text": "Great sofa"}]}]}]}

• Ответ имеет только то, что видит покупатель. products и sections Покупатель может открыть. записи с _active и fields без internal. Он имеет sets Открыт для этого покупателя. set для подписанных покупателей или для role Показы только с этот покупатель's Торговец, торговец key или staff сеанс без all=true читать Как анонимный покупатель, так и cannot доказать role set.
• image/file как будто {"url", "alt"|"title"}; product/category как {"id", "name", "url"}, или null когда покупатель cannot Открой..
• Другой shop's, hidden или unknown Ресурсы отсутствуют без error; а resource не заполненный sets приходить с "sets": []. Тяжелая просьба → 400 RECORDS_RESPONSE_TOO_LARGE: узко code, fields или limit.
• Читать из The live каталог: draft записи показывают after публикация.

4.3 Показать только то, что вам нужно

Q&A: список с fields=question, Один ответ на клик с item_ids=<_id>&fields=answer. Отзывы о a listing: product_ids=1,2,…&code=reviews&limit=3. Средний рейтинг: stats=rating. Страницы: Следуйте next_offset до тех пор, пока null.

4.4 Компонент, подкрепленный записью set

1. Читать GET /v1/account/token: capabilities.html_level3_allowed должен быть true. А. ZIP Освобождение от потребностей catalog:write и storage:write плюс owner/admin.
2. Наполнить, заполнить и открыть set (§3, §4.1).
3. создавать POST /html-documents с kind: "component", level: 3 (level 1 полоска скриптов. index.html, component.json, CSS и JS; Объявлять такие параметры, как company_id, resource_kind, resource_id, code, api_base и а heading. Никогда не ставьте торговца key входить folder или вставки.
4. The script звонки /record-sets Как в §4.2 (public прогноз, credentials: 'omit', never all=true), рендеринг погрузка, error и empty государства ( empty set Скрывает block), инициализирует каждый корень один раз и выживает в мягкой форме навигационная система (/docs/components §5). Длинный set загружены в pages: просить limit=10–20, Шоу «Show» more» в то время как next_offset не является null и просьба offset=<next_offset>; never load 200 рекордов для first экран.
5. Скачать The Release (POST /html-documents/{id}/releases/zip?publish=1 — 200 когда activated, 201 без publish), перечитать active_release_id, Затем нажмите на вставку на page (/docs/components §4.7.1).
6. Проверить на витрине магазина page в браузере: сетевой ответ, визуализируемый text, mobile width, и это переключатель-off записи и internal fields не заявляйте о наличии серверных записей или SEO.

4.5 Редактировать записи key — GET / PATCH …/records/{code}

Один set из одного product или section, адресованный его code. GET Каждый из них возвращается в исходное состояние (в виде сквозняка).-off рекорды, internal fields, file_id), тот field Список и а revision. PATCH Применяет операции к current set; другие записи, другие sets и обыкновенный characteristics Оставайтесь такими, какие они есть.

GET /products/7/records/faq            (a section: /categories/9/records/faq)
→ {"set": {"attribute_id": "42", "code": "faq", "revision": "3f2a…", "total": 2,
           "items": [{"_id": "q1", "question": "…", "answer": "…", "_active": true, "_created": "…"}, …],
           "schema": {"fields": […]}}}

PATCH /products/7/records/faq
{"ops": [
  {"op": "add",    "record": {"question": "Warranty?", "answer": "Two years."}, "position": 0},
  {"op": "update", "id": "q1", "set": {"answer": "Yes, 24 colours.", "note": null}},
  {"op": "remove", "id": "q2"},
  {"op": "move",   "id": "q1", "position": 0}]}
→ the same answer as GET, with the new records' `_id`

PATCH /products/7/records/faq        (refuse if someone changed the set since your GET)
{"expected_revision": "<revision from GET>", "ops": [{"op": "update", "id": "q1", "set": {"answer": "Updated"}}]}

• add закладывает record в position (0 - это first; default — последний). update слияние set входить record: null Удалить A field, _active включите его или off. move потребности position. Операции проводятся в order.
• The result проверяется как PUT (schema, files, links). Ан error имена record или операция: ops[1].id → 404 RECORD_NOT_FOUND, Плохая операция → 400 RECORDS_OP_INVALID.
• параллельный PATCH Звонки безопасны: если set изменяется, пока выполняется ваш запрос, сервер перечитывает его и применяет Ваши операции снова (after 3 Попробуйте ответ 409 И тоже. PUT всей set — Задний офис спасает Так и есть — все равно заменят. expected_revision от вашего GET Отказаться: изменено set → 409 RECORDS_REVISION_CONFLICT и никакой операции не applied; GET И снова решать, а не просто повторять.
• Безопасный для повторного использования add: положите own _id в record. Повторение затем ответы 400 RECORDS_OP_INVALID … duplicate _id — тот record Уже есть. Без _id повторяющийся add Создает вторую record.
• Удаление последнего record Удалить The set (revision: "0"). А. draft key читать и писать его own draft.
• потребности catalog:read для GET, catalog:write для PATCH. Другой shop's или deleted product → 404 PRODUCT_NOT_FOUND, section → 404 CATEGORY_NOT_FOUND, ан unknown code → 404 ATTRIBUTE_NOT_FOUND.

5.Безмолвно ignored

• А. set выброшенный из PUT …/attributes или PUT /categories/{id}/values не расчищается, не расчищается (по design).
• _created/_updated Ты посылаешь ignored.
• В PATCH …/records/{code}: id в add (тот record's own _id считать), position в update и remove, record снаружи add и set снаружи update.
• А. closed set (нет buyer Доступ отсутствует /record-sets с 200; просить о его fields через name это 400.
• Торговец key без catalog:read Получить анонимный ответ от /record-sets; только cannot использовать all=true.
• views и seo - хранят намеки; ничто на платформе не передает их само по себе.

6. Пределы

ошибки: RECORDS_SCHEMA_INVALID, RECORDS_VALUE_INVALID, RECORDS_TOO_MANY, RECORDS_TOO_LARGE (с помощью field address after тот code, e.g. faq[0].answer: required), RECORDS_NOT_FILTERABLE, RECORDS_NO_DEFAULT, RECORDS_TYPE_LOCKED, RECORDS_FIELD_UNKNOWN, RECORDS_OP_INVALID, RECORD_NOT_FOUND, RECORDS_REVISION_CONFLICT, RECORDS_ALL_NEEDS_ROLE, RECORDS_RESPONSE_TOO_LARGE, DUPLICATE_ATTRIBUTE_IN_SET; другой shop's section → CATEGORY_NOT_FOUND, его атрибут → UNKNOWN_ATTRIBUTE.

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

2026-10-31 на изолированном стенде, построенном из production: tools/mcpcheck/scenarios/record-sets.json — 55 REST steps через key (Также три pages то next_offset: null, more 10 ресурсов с и без code, а draft key Читать его own draft; GET/PATCH …/records/{code}: add, update, несвежий revision, ан unknown id, только для чтения, иностранный-shop и draft ключи, обычные value и public ответ after а PATCH) (schema ошибки, public/internal fields, Один ответ на item_ids, pages, all=true и его role Ворота, только для чтения и иностранные-shop ключи, а draft key Не меняя при этом live ответ, sets когда опущено, [] Исключить. buyer С клиентом role видел role-ограниченный set; анонимный buyer и а buyer без role Нет, не надо. level-3 компонента (обзоры со средними значениями) rating, Q&A ответы на загрузку на клик, галерея с лайтбокс) были построены и установлены key только, проверено на Chromium на 390 px и настольных компьютерах.