Define document exchange for 1C integration

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С
 - проверка получения каталога, остатков, заказов, статусов и задолженности
 - проверка обработки дублей и ошибок обмена
 - проверка отображения даты актуальности данных