Шпаргалка · Бизнес-процессы
Сквозная нумерация документов
Проблема
Во многих странах выставленные счета-фактуры обязаны иметь непрерывные номера: в каждой серии и каждом году ни один номер не пропущен и ни один не использован дважды, а аудитор проверяет реестр. Последовательность в базе оставляет дыры, MAX()+1 даёт дубли. Строка-счётчик, которую берут в транзакции выставления, даёт обе гарантии ценой очереди писателей, поэтому урок ещё и измеряет эту цену и держит её маленькой.
Чему вы научитесь
- Почему последовательности в базе оставляют дыры by design и почему MAX()+1 выдаёт один номер двум документам
- Строка-счётчик на серию и год, взятая через UPDATE ... RETURNING в той же транзакции, что и документ, и сколько её блокировка стоит в пропускной способности
- Номер берётся при выставлении, а не в черновике; заблокированная часть транзакции держится короткой
- Аннулирование вместо удаления, своя серия на филиал и смена года в юридическом часовом поясе компании
Диаграмма как код
Итоговая схема урока в виде текста: вставьте её в Jira, GitLab, GitHub, Notion или документацию, там Mermaid рисуется сам. Есть варианты для D2 и PlantUML (Confluence, IntelliJ).
Mermaid: схема
flowchart LR
n_clerk(["Бухгалтер"])
n_api["Сервис счетов"]
n_db[("БД счетов")]
n_export("Выгрузка реестра")
n_auditor>"Налоговый аудитор"]
n_branch(["Филиал"])
n_clerk -->|"вызов"| n_api
n_api --> n_db
n_export --> n_db
n_export -->|"асинхронно"| n_auditor
n_branch -->|"вызов"| n_apiMermaid: последовательность запросов
sequenceDiagram
participant n_api as Сервис счетов
participant n_db as БД счетов
participant n_export as Выгрузка реестра
participant n_auditor as Налоговый аудитор
Note over n_api,n_db: Каждый счёт получает следующий номер
n_api->>n_db: INSERT INTO invoices (id, number, status, buyer_id)
n_db-->>n_api: INSERT 0 1 number = INV-2026-000481
Note over n_export,n_auditor: В реестре дыры
n_export->>n_auditor: register 2026, series INV: 000481 000482 000484 000485 000490 ...
Note over n_api,n_db: MAX()+1 выдаёт один номер дважды
n_api->>n_db: number = SELECT max(no) + 1 FROM invoices WHERE series = 'INV'
Note over n_api,n_db: Строка-счётчик на серию и год
n_api->>n_db: UPDATE number_counters
n_db-->>n_api: UPDATE 1 last_no = 482
Note over n_api,n_db: Номер — только когда документ выставлен
n_api->>n_db: BEGIN#59; -- POST /invoices/9f2c/finalize
Note over n_api,n_db: Все ждут одну строку
n_api->>n_db: load test: 64 parallel finalizes, one series
Note over n_api,n_db: Брать номер последним, тяжёлую работу — снаружи
n_api->>n_db: finalize, reordered
Note over n_export,n_auditor: Выставленный счёт удаляют
n_export->>n_auditor: DELETE FROM invoices WHERE number = 'INV-2026-000517'#59; -- wrong buyer
Note over n_api,n_db: Аннулировать, а не удалять
n_api->>n_db: UPDATE invoices
Note over n_api,n_db: Своя серия на филиал
n_api->>n_db: SELECT series, year, last_no FROM number_counters#59;
n_db-->>n_api: HQ #124; 2026 #124; 517
Note over n_api,n_db: 1 января нумерация начинается заново
n_api->>n_db: INSERT INTO number_counters (series, year, last_no)D2
direction: right
n_clerk: "Бухгалтер" {
shape: rectangle
}
n_api: "Сервис счетов" {
shape: rectangle
}
n_db: "БД счетов" {
shape: cylinder
}
n_export: "Выгрузка реестра" {
shape: rectangle
style.multiple: true
}
n_auditor: "Налоговый аудитор" {
shape: cloud
}
n_branch: "Филиал" {
shape: rectangle
}
n_clerk -> n_api: "вызов"
n_api -> n_db
n_export -> n_db
n_export -> n_auditor: "асинхронно"
n_branch -> n_api: "вызов"PlantUML: последовательность запросов
@startuml
participant "Сервис счетов" as n_api
database "БД счетов" as n_db
participant "Выгрузка реестра" as n_export
boundary "Налоговый аудитор" as n_auditor
note over n_api, n_db : Каждый счёт получает следующий номер
n_api -> n_db : INSERT INTO invoices (id, number, status, buyer_id)
n_db --> n_api : INSERT 0 1 number = INV-2026-000481
note over n_export, n_auditor : В реестре дыры
n_export ->> n_auditor : register 2026, series INV: 000481 000482 000484 000485 000490 ...
note over n_api, n_db : MAX()+1 выдаёт один номер дважды
n_api -> n_db : number = SELECT max(no) + 1 FROM invoices WHERE series = 'INV'
note over n_api, n_db : Строка-счётчик на серию и год
n_api -> n_db : UPDATE number_counters
n_db --> n_api : UPDATE 1 last_no = 482
note over n_api, n_db : Номер — только когда документ выставлен
n_api -> n_db : BEGIN; -- POST /invoices/9f2c/finalize
note over n_api, n_db : Все ждут одну строку
n_api -> n_db : load test: 64 parallel finalizes, one series
note over n_api, n_db : Брать номер последним, тяжёлую работу — снаружи
n_api -> n_db : finalize, reordered
note over n_export, n_auditor : Выставленный счёт удаляют
n_export ->> n_auditor : DELETE FROM invoices WHERE number = 'INV-2026-000517'; -- wrong buyer
note over n_api, n_db : Аннулировать, а не удалять
n_api -> n_db : UPDATE invoices
note over n_api, n_db : Своя серия на филиал
n_api -> n_db : SELECT series, year, last_no FROM number_counters;
n_db --> n_api : HQ | 2026 | 517
note over n_api, n_db : 1 января нумерация начинается заново
n_api -> n_db : INSERT INTO number_counters (series, year, last_no)
@endumlPlantUML: компоненты
@startuml
left to right direction
agent "Бухгалтер" as n_clerk
component "Сервис счетов" as n_api
database "БД счетов" as n_db
collections "Выгрузка реестра" as n_export
cloud "Налоговый аудитор" as n_auditor
agent "Филиал" as n_branch
n_clerk --> n_api : вызов
n_api --> n_db
n_export --> n_db
n_export --> n_auditor : асинхронно
n_branch --> n_api : вызов
@endumlИтог
Шесть правил для номеров, которые по закону должны быть непрерывными.
1) Не используйте для них последовательность в базе: она пропускает номера by design. 2) Не используйте MAX()+1: два писателя читают один и тот же максимум. 3) Держите строку-счётчик на серию и год и берите номер через UPDATE ... RETURNING в той же транзакции, что и документ: откат его переиспользует. 4) Берите номер при выставлении, никогда в черновике. 5) Блокировка строки выстраивает писателей в очередь: берите номер последним, тяжёлую работу выносите наружу, делите по сериям, где это разрешают правила. 6) Аннулируйте вместо удаления, а год меняйте в юридическом часовом поясе со строками, созданными заранее.
Показатели: в начале и в конце
| Показатель | В начале | В конце |
|---|---|---|
| Пропущенные номера | 0/yr | 0/yr |
| Номера, выданные дважды | 0/yr | 0/yr |
| Выставлений на серию | 900/с | 780/с |
| p99 ожидания выставления | 4 мс | 18 мс |
Шаги
- Кейс Каждый счёт получает следующий номер
Бухгалтер создаёт счёт, и сервис даёт ему номер вида
INV-2026-000481: серия, год и порядковый номер. - Проблема В реестре дыры
В конце года реестр выгружается для налогового аудитора.
- Проблема MAX()+1 выдаёт один номер дважды
Разработчик заменяет последовательность: следующий номер — максимальный плюс один.
- Решение Строка-счётчик на серию и год
Одна строка на серию и год хранит последний использованный номер.
- Решение Номер — только когда документ выставлен
Черновики больше не получают номер: у них только внутренний id.
- Проблема Все ждут одну строку
В конце месяца нагрузочный тест запускает 64 параллельных выставления в одной серии.
- Решение Брать номер последним, тяжёлую работу — снаружи
Проверки и итоги уходят до
BEGIN. - Проблема Выставленный счёт удаляют
Счёт 000517 ушёл не тому покупателю.
- Решение Аннулировать, а не удалять
Выставленный документ аннулируется: статус
cancelled, время, причина и ссылка на документ, который его заменяет. - Решение Своя серия на филиал
Компания открывает филиал.
- Решение 1 января нумерация начинается заново
В новом году каждая серия начинается с 000001.
- Итоги Итоги
Шесть правил для номеров, которые по закону должны быть непрерывными.
Термины
- Сквозная нумерация
- Номера документов в каждой серии и году идут подряд, без пропусков и повторов. Часто это требование закона, аудитор проверяет его по реестру.
- Серия номеров
- Отдельная последовательность номеров со своим префиксом и годом, например на филиал. У каждой серии свой счётчик, поэтому серии не ждут друг друга.
- Строка-счётчик
- Строка с последним номером серии, которую увеличивают через UPDATE ... RETURNING в одной транзакции с документом. Откат возвращает номер, а блокировка строки выстраивает писателей в очередь.
- Дыра в последовательности
- Значение, пропущенное последовательностью в базе: после отката, кэша или падения. Последовательности ради скорости никогда не идут назад и поэтому не годятся для сквозных номеров.