Add CommerceBridge 1C documentation

cspell.json

@@ -8,6 +8,17 @@
   "words": [
     "mxlogger",
     "mxloggerlogs",
+    "commercebridge",
+    "commerceml",
+    "Mishiko",
+    "checkauth",
+    "Imagick",
+    "pagetitle",
+    "longtitle",
+    "introtext",
+    "menutitle",
+    "hidemenu",
+    "редиректов",
     "modxapp",
     "createdon",
     "emailsender",

docs/authors.json

@@ -153,6 +153,7 @@
       "ru": "Антон Мамрашев"
     }
   },
+  "Mishiko23": "Mishiko23",
   "modx-pro": "MODX RSC",
   "mvoevodskiy": {
     "modstore": "https://modstore.pro/authors/mvoevodskiy",

docs/components/commercebridge1c/exchange-setup.md

@@ -0,0 +1,77 @@
+# Настройка обмена с 1С
+
+Названия разделов в интерфейсе 1С зависят от конфигурации. Используйте штатный узел обмена с сайтом по протоколу CommerceML 2.
+
+## Параметры подключения
+
+Укажите в 1С:
+
+| Параметр | Значение |
+| --- | --- |
+| Адрес сайта | `https://example.ru/assets/components/CommerceBridge1C/connector.php` |
+| Пользователь | Логин из настроек CommerceBridge 1C |
+| Пароль | Пароль из настроек CommerceBridge 1C |
+| Протокол | CommerceML 2 |
+
+Сначала выполните штатную команду проверки соединения. После успешной авторизации настройте состав выгрузки.
+
+## Первый обмен
+
+Рекомендуемый порядок:
+
+1. включите режим отладки в CommerceBridge 1C;
+2. ограничьте выгрузку одной категорией и несколькими товарами;
+3. выполните полную выгрузку каталога и предложений;
+4. проверьте категории, шаблоны, артикулы, цены, остатки и изображения;
+5. настройте сопоставление нестандартных свойств;
+6. повторите тестовый обмен;
+7. отключите подробную отладку;
+8. снимите временное ограничение номенклатуры.
+
+## Каталог и торговые предложения
+
+Обычно 1С отправляет данные несколькими файлами:
+
+- `import.xml` — группы, товары, описания и свойства;
+- `offers.xml` — цены, остатки и характеристики предложений;
+- ZIP — XML и изображения в одном архиве.
+
+После первоначального `import.xml` можно отправлять только `offers.xml`. Это обновит цены и остатки без повторного импорта полного каталога.
+
+## Изображения
+
+Компонент принимает расширения `jpg`, `jpeg`, `png`, `gif` и `webp`. PDF, XLS, DOC и другие присоединённые документы игнорируются.
+
+Изображения добавляются в галерею miniShop3. После импорта запускается стандартное создание миниатюр, а поля изображения и превью товара обновляются сразу.
+
+## Склады
+
+Если список складов не задан, остатки всех складов суммируются. Для отбора укажите GUID нужных складов через запятую в `commerceml_warehouse_ids`.
+
+Пример:
+
+```text
+7f2a...,b91c...
+```
+
+## Отбор номенклатуры
+
+Ограничить импорт можно на обеих сторонах:
+
+- средствами узла обмена 1С;
+- GUID категорий в `commerceml_category_ids`;
+- GUID товаров в `commerceml_product_ids`.
+
+Пустой список означает, что ограничение компонента не применяется.
+
+## Автономная работа
+
+После настройки создайте регламентное задание на стороне 1С. Endpoint CommerceBridge 1C не требует открытой панели MODX или вкладки браузера.
+
+Для безопасности используйте HTTPS и, если возможно, разрешите доступ к endpoint только с IP сервера 1С.
+
+## Ручной импорт
+
+На вкладке ручного импорта можно загрузить отдельный XML или ZIP. Этот режим подходит для тестирования и диагностики.
+
+Для больших файлов предпочтителен автоматический HTTP-обмен из 1С: при ручной загрузке вкладка браузера должна оставаться открытой до завершения запроса.

docs/components/commercebridge1c/field-mapping.md

@@ -0,0 +1,100 @@
+# Свойства и типы цен
+
+CommerceBridge 1C умеет направлять свойства номенклатуры и характеристики предложений в выбранные поля товара.
+
+Правила настраиваются в панели компонента. Сопоставление выполняется по GUID свойства или по его наименованию без учёта регистра.
+
+## Поля правила
+
+| Поле | Назначение |
+| --- | --- |
+| Свойство 1С | GUID или точное наименование свойства |
+| Название | Пояснение правила в панели |
+| Назначение | Поле ресурса, поле miniShop3, TV или опция |
+| Поле | Ключ или ID поля назначения |
+| Преобразование | Строка, число, логическое значение или список |
+| Коэффициент | Множитель для числового значения |
+| Режим обновления | Всегда, только если поле пусто, либо никогда |
+| Значение по умолчанию | Используется, когда 1С передала пустое значение |
+| Активно | Включает или отключает правило |
+
+## Поля ресурса MODX
+
+Допустимые назначения:
+
+```text
+pagetitle, longtitle, description, introtext, content, menutitle,
+alias, published, hidemenu, searchable
+```
+
+Пример: свойство 1С `Заголовок H1` можно направить в `longtitle`.
+
+## Поля товара miniShop3
+
+Допустимые назначения:
+
+```text
+article, price, old_price, stock, weight, made_in,
+new, popular, favorite, tags, color, size
+```
+
+Поля `tags`, `color` и `size` обрабатываются как списки. Остальные поля получают одно значение.
+
+## TV-параметры
+
+В качестве назначения укажите имя или числовой ID существующего TV. TV должен быть доступен шаблону товара.
+
+Для значения типа «Список» элементы записываются в TV через разделитель `||`.
+
+## Опции miniShop3
+
+Укажите ключ опции латиницей. Если опции ещё нет, компонент создаст её автоматически:
+
+- `textfield` для одного значения;
+- `combo-multiple` для списка.
+
+Недопустимые символы в ключе заменяются символом подчёркивания, а сам ключ приводится к нижнему регистру.
+
+## Преобразование значений
+
+### Строка
+
+Несколько значений объединяются через запятую и пробел.
+
+### Число
+
+Пробелы удаляются, десятичная запятая заменяется точкой, затем применяется коэффициент.
+
+Например, для перевода миллиметров в метры установите коэффициент `0.001`.
+
+### Логическое значение
+
+Значения `1`, `true`, `yes`, `да`, `истина` и `on` записываются как `1`; остальные — как `0`.
+
+### Список
+
+Все непустые значения свойства сохраняются как список. Формат хранения зависит от назначения.
+
+## Режим обновления
+
+| Режим | Поведение |
+| --- | --- |
+| Всегда | Перезаписывать поле при каждом обмене |
+| Если пусто | Не изменять уже заполненное поле сайта |
+| Никогда | Считать правило, но не записывать значение |
+
+::: warning
+Для числовых полей значение `0` считается пустым в режиме «Если пусто».
+:::
+
+## Несколько типов цен
+
+Поле `price` получает тип цены, заданный в `commerceml_primary_price_id`. Если GUID не указан, используется первая цена предложения.
+
+При включённой настройке `commerceml_create_price_tvs` остальные типы цен записываются в TV:
+
+- имя TV формируется из названия типа цены;
+- TV автоматически привязывается к шаблону товара;
+- ранее созданные GUID-имена TV заменяются короткими читаемыми именами.
+
+Выбор TV по группе покупателей выполняется на стороне шаблонов или логики сайта. Сам компонент не меняет цену корзины miniShop3 в зависимости от группы пользователя.

docs/components/commercebridge1c/index.md

@@ -0,0 +1,90 @@
+---
+title: CommerceBridge 1C
+description: Обмен каталогом, ценами, остатками и заказами между 1С и miniShop3 по CommerceML 2
+logo: /components/commercebridge1c/cover.png
+author: Mishiko23
+repository: https://github.com/Mishiko23/CommerceBridge-1C
+dependencies: miniShop3
+outline: deep
+
+items:
+  - text: Установка
+    link: installation
+  - text: Настройка обмена с 1С
+    link: exchange-setup
+  - text: Системные настройки
+    link: settings
+  - text: Свойства и типы цен
+    link: field-mapping
+  - text: Заказы и статусы
+    link: orders
+  - text: Диагностика
+    link: troubleshooting
+---
+
+# CommerceBridge 1C
+
+CommerceBridge 1C организует двусторонний обмен между **1С** и интернет-магазином на **MODX 3 + miniShop3** по протоколу **CommerceML 2**.
+
+Компонент принимает каталог и торговые предложения по HTTP, обновляет товары по GUID и выгружает заказы miniShop3 обратно в 1С. Для обмена не требуется FTP.
+
+## Возможности
+
+- импорт категорий с сохранением вложенности;
+- импорт товаров, наименований, кратких и полных описаний;
+- импорт артикула, кода 1С, производителя и SEO description;
+- импорт свойств, веса, длины, ширины и высоты;
+- загрузка изображений и создание миниатюр средствами miniShop3;
+- фильтрация вложений по расширению: документы не загружаются как изображения;
+- обновление цен и остатков через `offers.xml` без повторного импорта каталога;
+- суммирование остатков всех складов или отбор выбранных складов;
+- импорт нескольких типов цен в автоматически создаваемые TV;
+- сопоставление свойств 1С с полями MODX, miniShop3, TV и опциями;
+- отбор категорий и товаров по GUID;
+- управление публикацией и видимостью товаров по остатку;
+- скрытие пустых категорий;
+- выгрузка заказов и данных покупателя в 1С;
+- сопоставление статусов 1С и miniShop3;
+- ручная загрузка XML/ZIP из панели компонента;
+- история сеансов, краткий отчёт, журнал и режим отладки.
+
+## Схема обмена
+
+Компонент поддерживает стандартные команды CommerceML:
+
+1. `checkauth` — проверка логина и пароля;
+2. `init` — согласование параметров сеанса;
+3. `file` — загрузка XML, ZIP и изображений;
+4. `import` — обработка загруженного файла;
+5. `query` — передача заказов из miniShop3 в 1С;
+6. `success` — завершение сеанса.
+
+Категории и товары связываются с объектами MODX по GUID 1С. Повторная выгрузка обновляет существующие объекты и не должна создавать дубликаты.
+
+## Требования
+
+- MODX Revolution 3.2 или новее;
+- miniShop3;
+- PHP 8.2 или новее;
+- расширения PHP: XMLReader, SimpleXML, XMLWriter, ZIP и Fileinfo;
+- OpenSSL для установки защищённого пакета;
+- GD или Imagick для обработки изображений;
+- HTTPS для endpoint обмена.
+
+## Ограничения версии 1.6.0
+
+::: warning
+Перед первым полным обменом создайте резервную копию файлов и базы данных. Первую проверку выполняйте на небольшой группе товаров.
+:::
+
+- характеристики предложений сохраняются как свойства базового товара, отдельные дочерние SKU miniShop3 не создаются;
+- TV с дополнительными ценами хранят значения, но выбор цены по группе покупателя настраивается отдельно в шаблонах сайта;
+- валюта выгружаемых заказов — `RUB`;
+- панель показывает результат завершённых HTTP-запросов, а не непрерывный прогресс внутри одного запроса;
+- для большого ручного импорта вкладка браузера должна оставаться открытой, автоматический обмен из 1С работает автономно.
+
+## Безопасность
+
+Для 1С создаётся отдельная учётная запись обмена. Пароль сохраняется только в виде результата `password_hash()` и не отображается в панели после сохранения.
+
+Рекомендуется ограничить endpoint по IP сервера 1С на уровне nginx или Apache. Каталог `core/cache/commerceml/` не должен быть доступен из веба.