diff --git a/docs/tz-fregat.typ b/docs/tz-fregat.typ index c42efed..80e4a21 100644 --- a/docs/tz-fregat.typ +++ b/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` — каталог, характеристики товаров, складские остатки и дата актуальности данных -- `counterparty_snapshot` — сведения о контрагентах, доступных клиенту, и задолженность при наличии таких данных -- `order_status_snapshot` — заказы, статусы, состав, стоимость, доставка и существенные изменения по заказам -- `order_export` — заявки и заказы, сформированные в личном кабинете и передаваемые в 1С +- `cabinet_counterparties` — список контрагентов из личного кабинета, по которым требуется синхронизация +- `balance_snapshot` — баланс, задолженность и дата актуальности по контрагентам из списка +- `catalog_snapshot` — актуальная продукция, характеристики и складские остатки +- `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` — тип документа обмена -- `schema_version` — версия структуры документа +- `document_type` — тип файла обмена +- `schema_version` — версия структуры файла - `snapshot_id` — уникальный идентификатор выгрузки -- `generated_at` — дата и время формирования документа на стороне источника -- `period_from` и `period_to` — период данных, если документ является выгрузкой за период -- `source` — источник документа +- `generated_at` — дата и время формирования файла +- `period_from` и `period_to` — период данных, если файл является выгрузкой за период +- `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_to": "2026-05-04T10:00:00+03:00", + "period_from": "2026-03-05", + "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", - "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 - } - } - ] + "updated_at": "2026-05-04T09:45:00+03:00" } ] } @@ -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С - проверка получения каталога, остатков, заказов, статусов и задолженности - проверка обработки дублей и ошибок обмена - проверка отображения даты актуальности данных