From fb22a6b11d9bc5ccdbc7b2b5ec2b7a00751a766a Mon Sep 17 00:00:00 2001 From: Ruslan Bakiev <572431+veikab@users.noreply.github.com> Date: Mon, 4 May 2026 14:14:54 +0700 Subject: [PATCH] Define document exchange for 1C integration --- docs/tz-fregat.typ | 208 ++++++++++++++++++++++++++++++++++----------- 1 file changed, 157 insertions(+), 51 deletions(-) diff --git a/docs/tz-fregat.typ b/docs/tz-fregat.typ index 3c5b743..c42efed 100644 --- a/docs/tz-fregat.typ +++ b/docs/tz-fregat.typ @@ -1724,8 +1724,8 @@ Wireframe-прототип: Интеграционный контур должен обеспечивать: -- получение данных из 1С -- прием событий от 1С +- получение документов обмена из 1С +- передачу в 1С документов обмена, сформированных личным кабинетом - передачу во внешние системы данных, необходимых для сопровождения заказов и клиентов, если такой обмен согласован сторонами - сопоставление внутренних идентификаторов и идентификаторов внешних систем - регистрацию входящих и исходящих операций обмена @@ -1750,63 +1750,168 @@ Wireframe-прототип: 1С рассматривается как первичный источник учетных данных по заказам, складам, статусам, стоимости, доставке и задолженности. Личный кабинет отображает эти сведения и фиксирует дату их актуальности. -== События от 1С +== Основной способ обмена с 1С -Система должна поддерживать прием webhook-событий от 1С в согласованном формате. +Основным способом интеграции является документный обмен по согласованным структурам. 1С формирует документы обмена по расписанию либо по событию при наличии технической возможности, а личный кабинет принимает, валидирует и обрабатывает такие документы. -Минимальный состав событий: +В качестве базового формата обмена используется JSON. Если на стороне 1С по техническим причинам удобнее использовать XML или CSV, стороны могут согласовать эквивалентную структуру без изменения состава передаваемых данных. -- создание нового заказа -- изменение информации по заказу -- изменение статуса заказа -- изменение сроков, условий или параметров доставки -- изменение состава заказа -- изменение сведений о задолженности клиента, если такие данные передаются событийно +Документы обмена могут передаваться одним из согласованных способов: -Для каждого события должны фиксироваться: +- загрузка файла в согласованное файловое хранилище +- передача файла через HTTP endpoint личного кабинета +- передача через иной согласованный защищенный канал, доступный заказчику и 1С -- тип события -- внешний идентификатор объекта 1С -- внутренний идентификатор объекта, если сопоставление выполнено -- дата и время события -- источник события -- статус обработки -- текст ошибки при неуспешной обработке +Периодичность формирования документов обмена определяется возможностями 1С и требованиями к актуальности данных. Базовый режим: не реже одного раза в час для данных, влияющих на отображение каталога, остатков, заказов и задолженности. -Система должна защищаться от повторной обработки дублей webhook-событий. - -== Методы получения данных из 1С +== Состав документов обмена -Система должна поддерживать получение данных из 1С через согласованные методы. +Минимальный состав документов обмена: -Минимальный состав методов: +- `catalog_snapshot` — каталог, характеристики товаров, складские остатки и дата актуальности данных +- `counterparty_snapshot` — сведения о контрагентах, доступных клиенту, и задолженность при наличии таких данных +- `order_status_snapshot` — заказы, статусы, состав, стоимость, доставка и существенные изменения по заказам +- `order_export` — заявки и заказы, сформированные в личном кабинете и передаваемые в 1С -- получение заказов клиента -- получение товарного каталога -- получение характеристик товаров -- получение доступных остатков по складам -- получение статусов и изменений по заказам -- получение текущей задолженности клиента и даты актуальности этих сведений +Документы `catalog_snapshot`, `counterparty_snapshot` и `order_status_snapshot` передаются от 1С в личный кабинет. Документ `order_export` передается из личного кабинета в 1С. -Точный набор методов, параметры запросов, формат ответов и ограничения по частоте вызовов фиксируются в интеграционной спецификации. +Состав документов может быть расширен по согласованию сторон, если в ходе интеграции появится отдельный тип данных, который нецелесообразно включать в существующие документы обмена. -== Требования к структурам обмена +== Определение обновлений и идемпотентность -Входные и выходные данные интеграционного слоя должны описываться в структурированном виде и позволять однозначно восстанавливать: +Каждый документ обмена должен содержать служебный блок с метаданными: -- тип объекта обмена -- идентификатор объекта -- дату и время события -- полезную нагрузку объекта -- статус обработки -- источник изменения +- `document_type` — тип документа обмена +- `schema_version` — версия структуры документа +- `snapshot_id` — уникальный идентификатор выгрузки +- `generated_at` — дата и время формирования документа на стороне источника +- `period_from` и `period_to` — период данных, если документ является выгрузкой за период +- `source` — источник документа +- `checksum` — контрольная сумма содержимого, если она формируется источником -Для обмена должны использоваться структурированные payload-форматы, пригодные для сериализации в JSON. +Личный кабинет должен хранить журнал обработанных документов обмена и не обрабатывать повторно документ с тем же `document_type`, `snapshot_id` и `checksum`. -Точная структура payload, схема подписи запросов и набор обязательных полей согласуются сторонами до начала этапа интеграции с 1С. +Если 1С может формировать только полную выгрузку, личный кабинет должен принимать полный snapshot и обновлять данные идемпотентно по внешним идентификаторам 1С и дате изменения объекта. + +Если 1С может формировать выгрузку изменений за период, документ должен содержать данные за период с момента последней успешной синхронизации либо за иной согласованный период. Для заказов рекомендуется передавать: + +- все открытые и активные заказы +- заказы, измененные за согласованный период +- заказы конкретных контрагентов, доступных пользователям личного кабинета + +Для каждого объекта внутри документа обмена рекомендуется передавать `external_id`, `updated_at` и при наличии `deleted` или `is_active`, чтобы личный кабинет мог корректно обновить, скрыть или пометить объект как неактуальный. + +== Пример структуры catalog_snapshot + + +```json +{ + "document_type": "catalog_snapshot", + "schema_version": "1.0", + "snapshot_id": "1c-catalog-2026-05-04T10:00:00", + "generated_at": "2026-05-04T10:00:00+03:00", + "period_from": null, + "period_to": "2026-05-04T10:00:00+03:00", + "source": "1c", + "checksum": "sha256:...", + "products": [ + { + "external_id": "1c-product-0001", + "article": "FRG-101", + "name": "Упаковочный скотч", + "product_type": "packing_tape", + "is_active": true, + "updated_at": "2026-05-04T09:58:00+03:00", + "attributes": { + "width_mm": 48, + "length_m": 50, + "thickness_mkm": 43, + "color": "прозрачный" + }, + "stocks": [ + { + "warehouse_external_id": "1c-warehouse-main", + "warehouse_name": "Основной склад", + "quantity": 120 + } + ] + } + ] +} +``` + +== Пример структуры order_status_snapshot + + +```json +{ + "document_type": "order_status_snapshot", + "schema_version": "1.0", + "snapshot_id": "1c-orders-2026-05-04T10:00:00", + "generated_at": "2026-05-04T10:00:00+03:00", + "period_from": "2026-05-04T09:00:00+03:00", + "period_to": "2026-05-04T10:00:00+03:00", + "source": "1c", + "orders": [ + { + "external_id": "1c-order-10025", + "cabinet_order_id": "FRG-2030", + "counterparty_external_id": "1c-counterparty-77", + "status": "in_production", + "status_name": "В производстве", + "total_amount": 145000, + "currency": "RUB", + "delivery_date": "2026-05-12", + "debt_amount": 0, + "updated_at": "2026-05-04T09:45:00+03:00", + "items": [ + { + "product_external_id": "1c-product-0001", + "name": "Упаковочный скотч", + "quantity": 100, + "price": 1450 + } + ] + } + ] +} +``` + +== Пример структуры order_export + + +```json +{ + "document_type": "order_export", + "schema_version": "1.0", + "snapshot_id": "cabinet-orders-2026-05-04T10:05:00", + "generated_at": "2026-05-04T10:05:00+03:00", + "source": "cabinet", + "orders": [ + { + "cabinet_order_id": "FRG-2031", + "counterparty_external_id": "1c-counterparty-77", + "contact_name": "Иван Иванов", + "comment": "Нужен расчет по доставке", + "delivery_address": "Москва, склад клиента", + "created_at": "2026-05-04T10:02:00+03:00", + "items": [ + { + "product_external_id": "1c-product-0001", + "quantity": 100, + "attributes": { + "width_mm": 48, + "length_m": 50 + } + } + ] + } + ] +} +``` == Интеграционные поля и служебные атрибуты @@ -1818,7 +1923,7 @@ Wireframe-прототип: - источник последнего обновления - признак успешной или неуспешной обработки - журнал интеграционных ошибок при наличии -- технический идентификатор последнего обработанного события, если он передается 1С +- идентификатор последнего обработанного документа обмена == Журналирование интеграционных операций @@ -1833,6 +1938,7 @@ Wireframe-прототип: - пользователя либо внешний источник, выполнивший изменение - статус обработки сообщения - текст ошибки при наличии +- идентификатор документа обмена и контрольную сумму при наличии == Требования к защите интеграционного обмена @@ -1843,8 +1949,8 @@ Wireframe-прототип: - отсутствуют обязательные параметры авторизации - подпись или токен не прошли проверку -- payload не соответствует согласованной структуре -- невозможно определить тип события или объект обработки +- документ обмена не соответствует согласованной структуре +- невозможно определить тип документа или объект обработки Секреты, используемые для интеграции с 1С, должны храниться только в Vault и передаваться сервисам через runtime-конфигурацию. @@ -1858,7 +1964,7 @@ Wireframe-прототип: - заказы клиента получаются и отображаются с актуальными статусами - изменения заказа из 1С отображаются в карточке заказа - текущая задолженность клиента и дата актуальности данных отображаются в предусмотренных интерфейсах -- webhook-события не обрабатываются повторно при дублях +- повторная передача одного и того же документа обмена не приводит к дублированию данных - ошибки интеграционного обмена фиксируются в журнале - неуспешные сообщения могут быть проанализированы и повторно обработаны в согласованном порядке @@ -2473,12 +2579,12 @@ Wireframe-прототип: Интеграционная документация должна описывать: -- состав событий, передаваемых из 1С -- состав методов получения данных из 1С -- структуру payload для каждого события и метода +- состав документов обмена, передаваемых между 1С и личным кабинетом +- структуру каждого документа обмена +- формат обмена: JSON, XML или CSV - обязательные и необязательные поля - правила сопоставления идентификаторов -- требования к авторизации, подписи или иному механизму защиты запросов +- требования к авторизации, подписи или иному механизму защиты обмена - порядок обработки дублей - порядок фиксации ошибок и повторной обработки сообщений - критерии приемки интеграционного обмена @@ -2550,8 +2656,8 @@ Wireframe-прототип: В состав этапа входят: - сопоставление внутренних идентификаторов и идентификаторов 1С -- настройка приема webhook-событий от 1С -- настройка получения данных из 1С через согласованные методы +- настройка приема документов обмена от 1С +- настройка передачи документов обмена из личного кабинета в 1С - проверка получения каталога, остатков, заказов, статусов и задолженности - проверка обработки дублей и ошибок обмена - проверка отображения даты актуальности данных