h1. ADR: нумерация внутренних и внешних заказов через ACCOUNT_NUMBER

h2. Статус
Принято 2026-03-07.

h2. Контекст
На тестовом стенде Bitrix заказы хранятся в @b_sale_order@, где:
* @ID@ — внутренний PK Bitrix;
* @ACCOUNT_NUMBER@ — отдельное поле видимого номера заказа;
* @XML_ID@ — GUID интеграции.

По умолчанию на стенде Bitrix генерирует @ACCOUNT_NUMBER = ID@, потому что шаблон собственной нумерации не настроен. При этом публичные ссылки и часть кастомного кода уже умеют работать по @ACCOUNT_NUMBER@, но часть интерфейсов исторически продолжает показывать @ID@.

Для внешних заказов этого недостаточно: пользовательский номер должен отличаться от внутренних заказов сайта и оставаться стабильным между Bitrix, 1С и внешними системами.

h2. Решение
* Канонический видимый номер заказа во всех интерфейсах должен быть @ACCOUNT_NUMBER@.
* @ID@ остаётся только внутренним техническим идентификатором Bitrix.
* @XML_ID@ остаётся GUID интеграции и не используется как пользовательский номер.
* Для внешних заказов Rest1C-API формирует @ACCOUNT_NUMBER@ в формате @<PREFIX>-<1C_NUMBER>@.
* Префикс берётся либо из явного поля payload, либо из маппинга @EXTERNAL_ORDER_NUMBER_PREFIXES@ по источнику заказа, либо из @EXTERNAL_ORDER_DEFAULT_NUMBER_PREFIX@, если источник не передан.
* Если источник внешнего заказа известен, но префикс для него не настроен, импорт заказа должен завершаться ошибкой. Молчаливый fallback на @ID@ или @ORDER_PREFIX@ запрещён.

h2. Последствия
* Поиск и upsert внешних заказов должны учитывать сначала @XML_ID@, затем сформированный внешний @ACCOUNT_NUMBER@, а уже потом legacy-варианты числового номера.
* Обновление статуса и @ID_1C@ по данным @Orders/InfoFull@ должно искать заказ с учётом внешнего @ACCOUNT_NUMBER@, иначе внешние заказы не будут находиться по номеру 1С.
* Сайт и API должны отдавать пользователю @ACCOUNT_NUMBER@ как @orderNumber@. Если нужен внутренний идентификатор, его нужно отдавать отдельным полем @id@.
* @ORDER_PREFIX@ остаётся частью протокола запросов в 1С по номеру заказа и не должен использоваться как префикс пользовательской нумерации внешних заказов.

h2. Границы реализации в этом репозитории
В @Rest1C-API@ реализуется:
* формирование и проверка внешнего @ACCOUNT_NUMBER@ при импорте;
* поиск существующих заказов по внешнему @ACCOUNT_NUMBER@;
* документация по конфигурации и модели идентификаторов.

Пользовательские API и шаблоны сайта, которые ещё показывают @ID@ вместо @ACCOUNT_NUMBER@, должны выравниваться в соответствующем репозитории фронтенда/Bitrix-модуля.