> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yume.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Сквозная автонумерация
> Счётчик компании: пара «компания + ключ нумерации», выдача номера с блокировкой строки и потребители — номера договоров клиентов, артикулы единиц инвентаря и номера документов.
Полный перечень полей — в [глоссарии сквозной автонумерации](/ru/logic/settings/counters-glossary).
Внутренние идентификаторы записей в базе не годятся для договоров, бирок на инвентаре и бланков: они не идут подряд, разрежены и ничего не говорят человеку. Поэтому в модуле настроек живёт отдельный простой механизм — **сквозной счётчик**: маленькая запись, которая помнит, какой номер компания выдаст следующим. Один и тот же механизм обслуживает несколько независимых нумераций: номера договоров клиентов, артикулы единиц инвентаря, номера документов. Других потребителей у него нет.
## Модель данных
Сквозной счётчик — это три значения плюс внутренний идентификатор записи.
| Поле | Тип | Назначение |
| ---------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Компания | связь | Владелец счётчика. У каждой компании свой набор счётчиков, и нумерации разных компаний друг на друга не влияют |
| Ключ счётчика | текст (до 40 символов) | Что именно нумеруется: клиенты компании, единицы конкретного продукта, документы конкретного шаблона, документы без шаблона |
| Текущее значение | целое неотрицательное число | Номер, который будет выдан следующим. Начальное значение — 1, после каждой выдачи увеличивается |
Пара «компания + ключ счётчика» уникальна: одна и та же нумерация не может существовать в двух экземплярах, а обращение к счётчику всегда однозначно попадает в нужную строку. Счётчики хранятся централизованно, в общей части базы, отдельно от данных самой компании, и принадлежность задаёт именно поле «Компания»; при удалении компании её счётчики удаляются вместе с ней.
Строки счётчиков не заводятся заранее. У новой компании их просто нет — нужная строка создаётся в момент первой выдачи номера и сразу со значением 1. Поэтому первый клиент получает номер 1, первая единица продукта — номер 1, первый документ по шаблону — номер 1.
## Как выдаётся номер
Выдача одинакова для всех потребителей и состоит из пяти шагов:
1. Определяется компания текущего запроса.
2. По паре «компания + ключ счётчика» ищется строка счётчика; если её ещё нет — она создаётся со значением 1.
3. Строка берётся **с блокировкой**: пока текущая операция не завершится, другие запросы к этому же счётчику ждут.
4. Текущее значение забирается как выданный номер.
5. Значение увеличивается — на единицу при выдаче одного номера или сразу на всё количество при пакетной выдаче — и сохраняется.
Блокировка снимается вместе с завершением операции. Именно она даёт главную гарантию: два одновременных запроса не получат один и тот же номер, второй дождётся первого и продолжит с увеличенного значения.
Блокировка строки применяется при выдаче номера договора клиента и при массовом создании единиц инвентаря. Нумерация документов работает без неё: номер читается и увеличивается без ожидания, а уникальность номера документа не проверяется на уровне базы. При одновременном создании двух документов по одному шаблону возможен повтор номера.
## Серии нумерации
Каждый ключ счётчика — отдельная, полностью независимая серия номеров.
| Серия | Сколько счётчиков | Шаг выдачи | Где виден результат |
| --------------------------------- | --------------------------- | ---------------------------------------- | ------------------------- |
| Номера клиентов | один на компанию | +1 за клиента | Номер договора клиента |
| Порядковые номера единиц продукта | по одному на каждый продукт | + количество единиц, запрошенное в форме | Артикул единицы инвентаря |
| Номера документов по шаблону | по одному на каждый шаблон | +1 за документ | Сквозной номер документа |
| Номера документов без шаблона | один на компанию | +1 за документ | Сквозной номер документа |
Серии не согласованы между собой: номер 17 может одновременно существовать у клиента, у единицы одного из продуктов и у нескольких документов, созданных по разным шаблонам. Номер имеет смысл только вместе со своей серией.
### Номер договора клиента
Клиент получает номер вида «№ГГ‑0001»: знак номера, две последние цифры текущего года, дефис и порядковый номер из счётчика клиентов, дополненный нулями до четырёх знаков.
Номер выдаётся при сохранении карточки и только при двух условиях: карточка уже существует в базе и поле номера ещё пустое. У только что заведённого клиента поле остаётся незаполненным — номер появится при следующем сохранении этой карточки. Присвоенный номер дальше не меняется, изменить его через обычные формы нельзя: поле доступно только для чтения. Клиенты, загруженные пакетным импортом, номер не получают вовсе — импорт пишет карточки в обход обычного сохранения.
Номер договора подставляется в текст документов как отдельная подстановка и используется в поиске по клиентам.
Подробнее о том, в какой момент номер появляется в карточке: [«Карточка клиента»](/ru/logic/clients-loyalty/client).
### Артикулы единиц инвентаря
При массовом создании единиц из продукта счётчик этого продукта сдвигается сразу на всё запрошенное количество, а артикул каждой единицы собирается из артикула продукта, дефиса и порядкового номера, дополненного нулями до трёх знаков. Если у продукта артикул не заполнен, вместо него подставляется внутренний идентификатор продукта. Так пачка получает подряд идущие артикулы, а повторный вызов формы продолжает нумерацию с того места, где остановился предыдущий.
За один раз форма позволяет создать не более тысячи единиц.
Количество в форме не проверяется на положительность. При отрицательном значении не создаётся ни одной единицы, но счётчик всё равно сдвигается на то же число позиций — номера сгорают.
Подробнее о форме создания и составе артикула: [«Продукт»](/ru/logic/inventory/inventory-groups).
### Номера документов
Документ, сформированный по шаблону, получает номер из счётчика своего шаблона; документ без шаблона — из общего счётчика документов компании. Номер записывается в карточку документа. В текст документа он попадает отдельной подстановкой — только когда содержимое собирается по шаблону для связанной аренды. В протоколе подписания номер показывается как видимый номер бланка, а если номера нет — вместо него выводится внутренний идентификатор документа.
Есть три сценария, которые различаются по расходу номеров:
* **Создание** документа — номер выдаётся, счётчик сдвигается.
* **Перегенерация** (пересборка содержимого по шаблону) — номер сохраняется, счётчик не трогается.
* **Перевыпуск** подписанного документа — создаётся новый документ, и он забирает следующий номер серии; у исходного документа номер остаётся прежним.
Загруженные файлом документы номер не получают вовсе — счётчик для них не вызывается, поле номера остаётся пустым.
Подробнее о жизненном цикле документа: [«Документы: карточки, файлы и статусы»](/ru/logic/documents/crud).
## Транзакции и откаты
Выдача номера и создание самой записи не всегда происходят в одной транзакции, и это заметно по последствиям сбоя.
* **Массовое создание единиц.** Сдвиг счётчика и создание единиц выполняются в одной операции: если создание сорвётся, счётчик откатится вместе с ним и номера не потеряются.
* **Номер договора клиента.** Счётчик увеличивается в собственной небольшой транзакции ещё до сохранения карточки. Если сохранение сорвётся и вызов не был обёрнут в общую транзакцию сверху, увеличенное значение уже зафиксировано — номер сгорит, в нумерации останется пропуск.
* **Документы.** Выдача номера, создание и перевыпуск документа идут внутри одной операции, поэтому неудачное создание номер не расходует.
Пропуски в нумерации — нормальное состояние. Значение счётчика только растёт: удаление клиента, единицы или документа номер не возвращает, и следующая запись всё равно получит следующее значение.
## Эксплуатация
Счётчик — служебная запись, у неё нет ни отдельной страницы в интерфейсе компании, ни собственных методов API: значение меняется только как побочный эффект выдачи номера. Раздел счётчиков в административной панели фактически не подключён, поэтому «отмотать» нумерацию назад или начать её с нужного числа можно лишь правкой значения в базе данных — эту операцию выполняет техническая поддержка.
Практические следствия для бизнес-сценариев:
* Нумерация не привязана к календарю: у номера договора клиента меняется только двузначный префикс года, сама последовательность через новый год продолжается, а не начинается заново.
* Год в номере договора берётся по всемирному времени, а не по часовому поясу компании. В первые часы после местной полуночи 1 января номер ещё получит префикс уходящего года.
* Дополнение нулями задаёт минимальную ширину номера, а не предел. После 9999‑го клиента номер станет пятизначным, после 999‑й единицы продукта — четырёхзначным; формат при этом не ломается, просто становится длиннее.
* Счётчик единиц привязан к конкретному продукту: новый продукт всегда начинает нумерацию с единицы, а у удалённого продукта строка счётчика остаётся невостребованной. Смена артикула продукта счётчик не сбрасывает — меняется только текстовая часть будущих артикулов.
* Счётчик знает только о номерах, которые выдал сам. Артикул, введённый сотрудником вручную, в нумерации не учитывается, и совпадения такого артикула с будущим автоматическим механизм не предотвращает.
## Подводные камни
* **Номера документов могут повториться.** В отличие от номеров клиентов и артикулов единиц, номер документа выдаётся без блокировки строки счётчика, и уникальность не гарантируется даже на уровне базы. Два документа, созданных по одному шаблону одновременно, могут получить одинаковый номер.
* Счётчик клиентов не сбрасывается в начале года: меняется только двузначный префикс года в номере договора, а порядковая часть продолжает расти, поэтому первый договор нового года не будет иметь номер 0001.
* Номер договора не появляется в момент создания клиента — он присваивается только при следующем сохранении уже существующей карточки, поэтому у только что заведённого клиента поле остаётся пустым.
* Клиенты, созданные пакетным импортом, номер договора не получают: импорт пишет карточки в обход обычного сохранения, поэтому вместе с номером не создаются также приветственный бонус и подписант.
* Значение счётчика клиентов увеличивается в собственной вложенной транзакции до сохранения карточки: если сохранение сорвётся и вызов не обёрнут во внешнюю транзакцию, номер уже израсходован и в нумерации останется пропуск. При массовом создании единиц откат, наоборот, возвращает счётчик назад.
* Количество единиц в форме массового создания не проверяется на положительность: при отрицательном значении не создаётся ни одной единицы, но счётчик продукта всё равно сдвигается на то же число позиций, и эти номера теряются безвозвратно.
* Сохранение карточки клиента вне контекста компании (фоновые сценарии и служебные команды без выбранной компании) завершается ошибкой на выдаче номера: защиты от «пустой компании» в этой ветке нет, хотя в соседней логике создания подписанта такая проверка есть.
* Изменить текущее значение счётчика через интерфейс нельзя: раздел счётчиков в административной панели не зарегистрирован из-за ошибки в строке подключения, поэтому правка возможна только напрямую в базе данных.
* Артикулы единиц инвентаря не проверяются на уникальность в базе, поэтому счётчик защищает от повторов только внутри автогенерации по одному продукту: артикул, введённый вручную, может совпасть с автоматически выданным.
* Год в номере договора берётся по всемирному времени, а не по часовому поясу компании: в первые часы после местной полуночи 1 января договор получит префикс уходящего года.
- Серии нумерации независимы: документ без шаблона и документ по шаблону ведут свои последовательности, поэтому одинаковый номер у двух документов одной компании — штатная ситуация, а не ошибка.
- Номер документа попадает в текст отдельной подстановкой только при сборке содержимого по шаблону для связанной аренды; в протоколе подписания при отсутствии номера показывается внутренний идентификатор документа.
- Дополнение нулями задаёт минимальную ширину, а не предел: после 9999‑го клиента номер договора становится пятизначным, а после 999‑й единицы продукта порядковая часть артикула — четырёхзначной.
- Если у продукта не заполнен артикул, в артикулах его единиц вместо артикула подставляется внутренний идентификатор продукта; смена артикула продукта меняет только текстовую часть будущих артикулов и счётчик не сбрасывает.
- Уникальность артикула самого продукта проверяется только в форме продукта, только при включённой соответствующей возможности и только среди неархивных продуктов; на единицы инвентаря эта проверка не распространяется.
- Значение счётчика только растёт: удаление клиента, единицы инвентаря или документа не освобождает номер, поэтому пропуски в нумерации неизбежны.
- Номер аренды выдаётся не этим механизмом: у аренды есть собственное поле сквозного номера с уникальностью в рамках компании, но текущий код его нигде не заполняет (поле помечено как устаревшее), и потребители подставляют вместо него внутренний идентификатор аренды.
- Строка счётчика создаётся при первой выдаче номера, поэтому отсутствие счётчика у компании не является признаком неполной настройки.
## Связанные страницы
Полный перечень полей счётчика и серий нумерации.
Обзорная страница модуля и переход ко всем его разделам.
Полный перечень параметров компании: что можно включить или выключить, какие значения стоят по умолчанию и как настройки читаются и сохраняются.
Как значение настройки попадает в базу, как оно кэшируется по компаниям и почему изменение настройки сбрасывает кэш целиком.
Собственные поля компании для клиентов, инвентаря, аренд и других справочников: типы, обязательность, отображение в таблице и фильтрах.
Как компания меняет названия разделов и статусов под свою нишу, включая формы слова по падежам и числам.
Сохранённый состав, порядок и ширина колонок для таблиц интерфейса — отдельно по каждой таблице компании.
Показ рекламных и информационных баннеров платформы внутри системы: частота показа, отметка о просмотре и исключение компаний.
Служебный экран платформы для просмотра и правки настроек конкретной компании со сбросом значений к умолчанию.