Clarify 1C file exchange concept

docs/tz-fregat.typ

@@ -1724,8 +1724,8 @@ Wireframe-прототип:
 
 Интеграционный контур должен обеспечивать:
 
-- получение документов обмена из 1С
+- получение файлов обмена из 1С
-- передачу в 1С документов обмена, сформированных личным кабинетом
+- передачу в 1С файлов обмена, сформированных личным кабинетом
 - передачу во внешние системы данных, необходимых для сопровождения заказов и клиентов, если такой обмен согласован сторонами
 - сопоставление внутренних идентификаторов и идентификаторов внешних систем
 - регистрацию входящих и исходящих операций обмена
@@ -1753,58 +1753,100 @@ Wireframe-прототип:
 == Основной способ обмена с 1С
 
 
-Основным способом интеграции является документный обмен по согласованным структурам. 1С формирует документы обмена по расписанию либо по событию при наличии технической возможности, а личный кабинет принимает, валидирует и обрабатывает такие документы.
+Основным способом интеграции является файловый обмен по согласованным структурам. Личный кабинет формирует список контрагентов, по которым требуется синхронизация, а 1С на основании этого списка формирует ответные выгрузки только по таким контрагентам и только в согласованном объеме.
 
 В качестве базового формата обмена используется JSON. Если на стороне 1С по техническим причинам удобнее использовать XML или CSV, стороны могут согласовать эквивалентную структуру без изменения состава передаваемых данных.
 
-Документы обмена могут передаваться одним из согласованных способов:
+Файлы обмена могут передаваться одним из согласованных способов:
 
 - загрузка файла в согласованное файловое хранилище
 - передача файла через HTTP endpoint личного кабинета
 - передача через иной согласованный защищенный канал, доступный заказчику и 1С
 
-Периодичность формирования документов обмена определяется возможностями 1С и требованиями к актуальности данных. Базовый режим: не реже одного раза в час для данных, влияющих на отображение каталога, остатков, заказов и задолженности.
+Базовая логика обмена:
 
-== Состав документов обмена
++ Личный кабинет передает в 1С список контрагентов, у которых есть личный кабинет либо которые заведены в системе для клиентской работы.
++ 1С формирует выгрузки только по указанным контрагентам.
++ Каталог и остатки передаются как актуальный общий snapshot.
++ Балансы и задолженность передаются как состояние по контрагентам на дату формирования выгрузки.
++ Заказы и статусы передаются по указанным контрагентам за согласованный период, по умолчанию за последние 60 календарных дней.
+
+== Состав файлов обмена
 
 
-Минимальный состав документов обмена:
+Минимальный состав файлов обмена:
 
-- `catalog_snapshot` — каталог, характеристики товаров, складские остатки и дата актуальности данных
+- `cabinet_counterparties` — список контрагентов из личного кабинета, по которым требуется синхронизация
-- `counterparty_snapshot` — сведения о контрагентах, доступных клиенту, и задолженность при наличии таких данных
+- `balance_snapshot` — баланс, задолженность и дата актуальности по контрагентам из списка
-- `order_status_snapshot` — заказы, статусы, состав, стоимость, доставка и существенные изменения по заказам
+- `catalog_snapshot` — актуальная продукция, характеристики и складские остатки
-- `order_export` — заявки и заказы, сформированные в личном кабинете и передаваемые в 1С
+- `orders_snapshot` — заказы, статусы, состав, стоимость, доставка и существенные изменения по заказам за согласованный период
 
-Документы `catalog_snapshot`, `counterparty_snapshot` и `order_status_snapshot` передаются от 1С в личный кабинет. Документ `order_export` передается из личного кабинета в 1С.
+Файл `cabinet_counterparties` передается из личного кабинета в 1С. Файлы `balance_snapshot`, `catalog_snapshot` и `orders_snapshot` передаются из 1С в личный кабинет.
 
-Состав документов может быть расширен по согласованию сторон, если в ходе интеграции появится отдельный тип данных, который нецелесообразно включать в существующие документы обмена.
+Состав файлов может быть расширен по согласованию сторон, если в ходе интеграции появится отдельный тип данных, который нецелесообразно включать в существующие файлы обмена.
 
 == Определение обновлений и идемпотентность
 
 
-Каждый документ обмена должен содержать служебный блок с метаданными:
+Каждый файл обмена должен содержать служебный блок с метаданными:
 
-- `document_type` — тип документа обмена
+- `document_type` — тип файла обмена
-- `schema_version` — версия структуры документа
+- `schema_version` — версия структуры файла
 - `snapshot_id` — уникальный идентификатор выгрузки
-- `generated_at` — дата и время формирования документа на стороне источника
+- `generated_at` — дата и время формирования файла
-- `period_from` и `period_to` — период данных, если документ является выгрузкой за период
+- `period_from` и `period_to` — период данных, если файл является выгрузкой за период
-- `source` — источник документа
+- `source` — источник файла
 - `checksum` — контрольная сумма содержимого, если она формируется источником
 
-Личный кабинет должен хранить журнал обработанных документов обмена и не обрабатывать повторно документ с тем же `document_type`, `snapshot_id` и `checksum`.
+Личный кабинет должен хранить журнал обработанных файлов обмена и не обрабатывать повторно файл с тем же `document_type`, `snapshot_id` и `checksum`.
 
 Если 1С может формировать только полную выгрузку, личный кабинет должен принимать полный snapshot и обновлять данные идемпотентно по внешним идентификаторам 1С и дате изменения объекта.
 
-Если 1С может формировать выгрузку изменений за период, документ должен содержать данные за период с момента последней успешной синхронизации либо за иной согласованный период. Для заказов рекомендуется передавать:
+Для заказов регулярная синхронизация ограничивается согласованным периодом. По умолчанию передаются заказы за последние 60 календарных дней, а также активные заказы, если они не попадают в этот период, но должны отображаться клиенту.
 
-- все открытые и активные заказы
+== Пример cabinet_counterparties
-- заказы, измененные за согласованный период
-- заказы конкретных контрагентов, доступных пользователям личного кабинета
 
-Для каждого объекта внутри документа обмена рекомендуется передавать `external_id`, `updated_at` и при наличии `deleted` или `is_active`, чтобы личный кабинет мог корректно обновить, скрыть или пометить объект как неактуальный.
 
-== Пример структуры catalog_snapshot
+```json
+{
+  "document_type": "cabinet_counterparties",
+  "schema_version": "1.0",
+  "snapshot_id": "cabinet-counterparties-2026-05-04T10:00:00",
+  "generated_at": "2026-05-04T10:00:00+03:00",
+  "source": "cabinet",
+  "counterparties": [
+    {
+      "counterparty_external_id": "1c-counterparty-77",
+      "inn": "7700000000",
+      "name": "ООО Клиент",
+      "cabinet_enabled": true
+    }
+  ]
+}
+```
+
+== Пример balance_snapshot
+
+
+```json
+{
+  "document_type": "balance_snapshot",
+  "schema_version": "1.0",
+  "snapshot_id": "1c-balances-2026-05-04T10:00:00",
+  "generated_at": "2026-05-04T10:00:00+03:00",
+  "balance_date": "2026-05-04",
+  "source": "1c",
+  "balances": [
+    {
+      "counterparty_external_id": "1c-counterparty-77",
+      "debt_amount": 125000,
+      "currency": "RUB"
+    }
+  ]
+}
+```
+
+== Пример catalog_snapshot
 
 
 ```json
@@ -1813,24 +1855,13 @@ Wireframe-прототип:
   "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",
+      "product_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",
@@ -1843,21 +1874,21 @@ Wireframe-прототип:
 }
 ```
 
-== Пример структуры order_status_snapshot
+== Пример orders_snapshot
 
 
 ```json
 {
-  "document_type": "order_status_snapshot",
+  "document_type": "orders_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_from": "2026-03-05",
-  "period_to": "2026-05-04T10:00:00+03:00",
+  "period_to": "2026-05-04",
   "source": "1c",
   "orders": [
     {
-      "external_id": "1c-order-10025",
+      "order_external_id": "1c-order-10025",
       "cabinet_order_id": "FRG-2030",
       "counterparty_external_id": "1c-counterparty-77",
       "status": "in_production",
@@ -1865,49 +1896,7 @@ Wireframe-прототип:
       "total_amount": 145000,
       "currency": "RUB",
       "delivery_date": "2026-05-12",
-      "debt_amount": 0,
+      "updated_at": "2026-05-04T09:45:00+03:00"
-      "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
-          }
-        }
-      ]
     }
   ]
 }
@@ -1923,7 +1912,7 @@ Wireframe-прототип:
 - источник последнего обновления
 - признак успешной или неуспешной обработки
 - журнал интеграционных ошибок при наличии
-- идентификатор последнего обработанного документа обмена
+- идентификатор последнего обработанного файла обмена
 
 == Журналирование интеграционных операций
 
@@ -1938,7 +1927,7 @@ Wireframe-прототип:
 - пользователя либо внешний источник, выполнивший изменение
 - статус обработки сообщения
 - текст ошибки при наличии
-- идентификатор документа обмена и контрольную сумму при наличии
+- идентификатор файла обмена и контрольную сумму при наличии
 
 == Требования к защите интеграционного обмена
 
@@ -1949,8 +1938,8 @@ Wireframe-прототип:
 
 - отсутствуют обязательные параметры авторизации
 - подпись или токен не прошли проверку
-- документ обмена не соответствует согласованной структуре
+- файл обмена не соответствует согласованной структуре
-- невозможно определить тип документа или объект обработки
+- невозможно определить тип файла или объект обработки
 
 Секреты, используемые для интеграции с 1С, должны храниться только в Vault и передаваться сервисам через runtime-конфигурацию.
 
@@ -1964,7 +1953,7 @@ Wireframe-прототип:
 - заказы клиента получаются и отображаются с актуальными статусами
 - изменения заказа из 1С отображаются в карточке заказа
 - текущая задолженность клиента и дата актуальности данных отображаются в предусмотренных интерфейсах
-- повторная передача одного и того же документа обмена не приводит к дублированию данных
+- повторная передача одного и того же файла обмена не приводит к дублированию данных
 - ошибки интеграционного обмена фиксируются в журнале
 - неуспешные сообщения могут быть проанализированы и повторно обработаны в согласованном порядке
 
@@ -2579,8 +2568,8 @@ Wireframe-прототип:
 
 Интеграционная документация должна описывать:
 
-- состав документов обмена, передаваемых между 1С и личным кабинетом
+- состав файлов обмена, передаваемых между 1С и личным кабинетом
-- структуру каждого документа обмена
+- структуру каждого файла обмена
 - формат обмена: JSON, XML или CSV
 - обязательные и необязательные поля
 - правила сопоставления идентификаторов
@@ -2656,8 +2645,8 @@ Wireframe-прототип:
 В состав этапа входят:
 
 - сопоставление внутренних идентификаторов и идентификаторов 1С
-- настройка приема документов обмена от 1С
+- настройка приема файлов обмена от 1С
-- настройка передачи документов обмена из личного кабинета в 1С
+- настройка передачи файлов обмена из личного кабинета в 1С
 - проверка получения каталога, остатков, заказов, статусов и задолженности
 - проверка обработки дублей и ошибок обмена
 - проверка отображения даты актуальности данных