mufassall

Шпаргалка · Бизнес-процессы

Сквозная нумерация документов

14 мин · Средний · mufassall.dtwin.uz/ru/l/document-numbering/

← Открыть урок

Проблема

Во многих странах выставленные счета-фактуры обязаны иметь непрерывные номера: в каждой серии и каждом году ни один номер не пропущен и ни один не использован дважды, а аудитор проверяет реестр. Последовательность в базе оставляет дыры, 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_api

Mermaid: последовательность запросов

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)
@enduml

PlantUML: компоненты

@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/yr0/yr
Номера, выданные дважды0/yr0/yr
Выставлений на серию900/с780/с
p99 ожидания выставления4 мс18 мс

Шаги

  1. Кейс Каждый счёт получает следующий номер

    Бухгалтер создаёт счёт, и сервис даёт ему номер вида INV-2026-000481: серия, год и порядковый номер.

  2. Проблема В реестре дыры

    В конце года реестр выгружается для налогового аудитора.

  3. Проблема MAX()+1 выдаёт один номер дважды

    Разработчик заменяет последовательность: следующий номер — максимальный плюс один.

  4. Решение Строка-счётчик на серию и год

    Одна строка на серию и год хранит последний использованный номер.

  5. Решение Номер — только когда документ выставлен

    Черновики больше не получают номер: у них только внутренний id.

  6. Проблема Все ждут одну строку

    В конце месяца нагрузочный тест запускает 64 параллельных выставления в одной серии.

  7. Решение Брать номер последним, тяжёлую работу — снаружи

    Проверки и итоги уходят до BEGIN.

  8. Проблема Выставленный счёт удаляют

    Счёт 000517 ушёл не тому покупателю.

  9. Решение Аннулировать, а не удалять

    Выставленный документ аннулируется: статус cancelled, время, причина и ссылка на документ, который его заменяет.

  10. Решение Своя серия на филиал

    Компания открывает филиал.

  11. Решение 1 января нумерация начинается заново

    В новом году каждая серия начинается с 000001.

  12. Итоги Итоги

    Шесть правил для номеров, которые по закону должны быть непрерывными.

Термины

Сквозная нумерация
Номера документов в каждой серии и году идут подряд, без пропусков и повторов. Часто это требование закона, аудитор проверяет его по реестру.
Серия номеров
Отдельная последовательность номеров со своим префиксом и годом, например на филиал. У каждой серии свой счётчик, поэтому серии не ждут друг друга.
Строка-счётчик
Строка с последним номером серии, которую увеличивают через UPDATE ... RETURNING в одной транзакции с документом. Откат возвращает номер, а блокировка строки выстраивает писателей в очередь.
Дыра в последовательности
Значение, пропущенное последовательностью в базе: после отката, кэша или падения. Последовательности ради скорости никогда не идут назад и поэтому не годятся для сквозных номеров.