Ошибка почти никогда не живёт в одной команде «обнулить счётчик». Обычно один процесс уже считает новый год, второй ещё использует старый часовой пояс, а третий держит закешированное значение sequence. Начните с двух конфликтующих документов: выпишите их тип, филиал, дату выдачи, часовой пояс и момент записи в UTC.
Если номер имеет юридическое или бухгалтерское значение, сначала согласуйте правила серии с владельцем процесса. Техническая схема обеспечивает уникальность и воспроизводимость, но не определяет, обязан ли ряд быть непрерывным: это требование зависит от документа и применимых правил.
Серия — это данные, а не ночная задача
| Часть ключа | Пример | Зачем хранить |
|---|---|---|
| Тип документа | invoice | акты и счета могут иметь разные ряды |
| Бизнес-год | 2027 | отдельная последовательность каждого года |
| Филиал/организация | msk | если нумерация разделена организационно |
| Следующий номер | 42 | единственная изменяемая величина |
| Часовой пояс | Europe/Moscow | одинаковая граница года у всех узлов |
Новая строка `(invoice, 2027, msk)` сама начинает ряд нового года. Ничего глобально перезапускать в полночь не нужно. Если филиалы делят общую серию, филиал убирают из ключа; если у каждой организации свой ряд, добавляют стабильный идентификатор организации.
Год берётся из даты документа
Не используйте локальное `now()` приложения без явного правила. Пользователь может оформить документ задним числом, очередь — завершить его после полуночи, а сервер — работать в UTC. Выберите поле `issued_at`, преобразуйте его в утверждённый бизнес-часовой пояс и один раз получите `series_year`. Это значение сохраняется в документе и больше не пересчитывается из текущего времени.
series_year = year(issued_at AT TIME ZONE 'Europe/Moscow')
series_key = (document_type, series_year, legal_entity_id)
UNIQUE (document_type, series_year, legal_entity_id, number)Номер и документ фиксируются одной транзакцией
- Начать транзакцию и получить или создать строку нужной серии.
- Заблокировать строку счётчика `FOR UPDATE` либо выполнить атомарный `UPDATE ... RETURNING`.
- Получить номер и сразу вставить документ с тем же series key.
- Зафиксировать транзакцию; при ошибке откатить и счётчик, и документ.
- Вернуть клиенту уже сохранённый номер, а не предварительный прогноз.
На стороне базы оставьте уникальное ограничение. Оно не заменяет правильную транзакцию, но превращает скрытый дубль в видимую ошибку. Повтор API должен иметь idempotency key: иначе два одинаковых запроса смогут законно занять два разных номера.
Почему простой RESTART опасен
PostgreSQL sequence удобна для глобальных уникальных идентификаторов, но её значения не откатываются вместе с неуспешной транзакцией, поэтому возможны пропуски. `ALTER SEQUENCE ... RESTART` меняет текущее состояние и синхронизируется с конкурентными обращениями, однако сброс общей sequence не создаёт отдельные ряды по году и не исправляет неверный выбор года приложением.
- Не вызывайте `setval(1)` из нескольких экземпляров приложения.
- Не считайте `MAX(number)+1` без блокировки: два запроса увидят один максимум.
- Не удаляйте старую строку счётчика — она объясняет историческую серию.
- Не обещайте отсутствие пропусков, если используете обычную sequence.
- Не меняйте уже выданный номер автоматически после смены часового пояса.
Пограничный тест проводится в четырёх сценариях
| Сценарий | Ожидание | Что ловим |
|---|---|---|
| 31 декабря 23:59:59 | номер старой серии | ранний сброс |
| 1 января 00:00:00 | первый номер новой серии | неверный timezone |
| два параллельных запроса | разные номера | гонка |
| ошибка после выдачи | согласованный rollback/retry | потерянный документ |
| документ задним числом | серия даты документа | зависимость от now |
Уже возникшие дубли исправляют отдельно
Сначала остановите выдачу в повреждённой серии и сохраните снимок строк. Определите, какой документ был подтверждён первым и какие номера уже ушли наружу. Не перенумеровывайте историю массово без решения владельца процесса: корректнее создать протокол исправления, восстановить счётчик после максимального подтверждённого номера и включить ограничение уникальности после очистки.
Исправление готово, когда год вычисляется одинаково на всех узлах, параллельный тест не даёт дублей, а повтор одного запроса возвращает тот же документ. Для разбора достаточно схемы серии, двух обезличенных строк, часового пояса и trace транзакции; содержимое документов и персональные данные не нужны.