Шпаргалка · Бизнес-процессы
Жизненный цикл документа
Проблема
Электронный счёт-фактура между двумя компаниями проходит путь от черновика до принятого, отклонённого или отменённого, и каждый юридически значимый шаг должен подтвердить внешний реестр. Как сохранить эту машину состояний корректной, когда двое нажимают одновременно, а реестр отвечает поздно, дважды или никогда.
Чему вы научитесь
- Состояния документа и таблица переходов вместо разбросанных if
- Оптимистичная блокировка: колонка
version, 0 строк и 409 - Промежуточные состояния, пока реестр не подтвердит через callback
- Идемпотентные callback, сверка статусов, история и outbox
Диаграмма как код
Итоговая схема урока в виде текста: вставьте её в Jira, GitLab, GitHub, Notion или документацию, там Mermaid рисуется сам. Есть варианты для D2 и PlantUML (Confluence, IntelliJ).
Mermaid: схема
flowchart LR
n_seller(["Приложение продавца"])
n_buyer(["Приложение покупателя"])
n_api["API документов"]
n_db[("База документов")]
n_registry>"Реестр"]
n_worker("Сверка статусов")
n_events[["События"]]
n_seller --> n_api
n_buyer --> n_api
n_api --> n_db
n_api --> n_registry
n_registry --x|"потеряно"| n_api
n_worker --> n_db
n_worker --> n_registry
n_db --> n_events
n_events --> n_buyerMermaid: последовательность запросов
sequenceDiagram
participant n_buyer as Приложение покупателя
participant n_api as API документов
participant n_db as База документов
participant n_seller as Приложение продавца
participant n_registry as Реестр
participant n_worker as Сверка статусов
Note over n_buyer,n_api: Счёт-фактура — это машина состояний
n_buyer->>n_api: GET /documents/inv_5120 HTTP/1.1
n_api-->>n_buyer: HTTP/1.1 200 OK
Note over n_api,n_db: Два пользователя действуют одновременно
n_api->>n_db: two clicks on inv_5120, 5 ms apart
Note over n_api,n_db: Обновлять только прочитанную версию
n_api->>n_db: UPDATE documents
n_db-->>n_api: UPDATE 0
Note over n_seller,n_api: Проигравший получает 409, а не тихую перезапись
n_seller->>n_api: POST /documents/inv_5120/cancel HTTP/1.1
n_api-->>n_seller: HTTP/1.1 409 Conflict
Note over n_buyer,n_api: Разрешённые переходы — из одной таблицы
n_buyer->>n_api: POST /documents/inv_5120/reject HTTP/1.1
n_api-->>n_buyer: HTTP/1.1 422 Unprocessable Content
Note over n_api,n_registry: Последнее слово за реестром, и он отвечает позже
n_api->>n_registry: POST /v1/documents/inv_5120/accept HTTP/1.1
n_registry-->>n_api: HTTP/1.1 202 Accepted
Note over n_registry,n_api: Ждать в промежуточном состоянии, пока реестр не подтвердит
n_registry->>n_api: POST /registry/callbacks HTTP/1.1
n_api-->>n_registry: HTTP/1.1 200 OK
Note over n_registry,n_api: Callback приходит дважды или не приходит вовсе
n_registry-xn_api: callback log, registry -#62; api
Note over n_api,n_db: Каждый event id обрабатывать один раз
n_api->>n_db: INSERT INTO registry_events (event_id, received_at)
n_db-->>n_api: INSERT 0 0
Note over n_worker,n_registry: Задача сверки спрашивает о зависших документах
n_worker->>n_registry: GET /v1/documents/inv_5133/status HTTP/1.1
n_registry-->>n_worker: HTTP/1.1 200 OK
Note over n_api,n_db: Каждый переход пишет историю и строку outbox
n_api->>n_db: BEGIN#59;D2
direction: right
n_seller: "Приложение продавца" {
shape: rectangle
}
n_buyer: "Приложение покупателя" {
shape: rectangle
}
n_api: "API документов" {
shape: rectangle
}
n_db: "База документов" {
shape: cylinder
}
n_registry: "Реестр" {
shape: cloud
}
n_worker: "Сверка статусов" {
shape: rectangle
style.multiple: true
}
n_events: "События" {
shape: queue
}
n_seller -> n_api
n_buyer -> n_api
n_api -> n_db
n_api -> n_registry
n_registry -> n_api: "потеряно" {
style.stroke-dash: 3
target-arrowhead.shape: cross
}
n_worker -> n_db
n_worker -> n_registry
n_db -> n_events
n_events -> n_buyerPlantUML: последовательность запросов
@startuml
participant "Приложение покупателя" as n_buyer
participant "API документов" as n_api
database "База документов" as n_db
participant "Приложение продавца" as n_seller
boundary "Реестр" as n_registry
participant "Сверка статусов" as n_worker
note over n_buyer, n_api : Счёт-фактура — это машина состояний
n_buyer -> n_api : GET /documents/inv_5120 HTTP/1.1
n_api --> n_buyer : HTTP/1.1 200 OK
note over n_api, n_db : Два пользователя действуют одновременно
n_api -> n_db : [дубль] two clicks on inv_5120, 5 ms apart
note over n_api, n_db : Обновлять только прочитанную версию
n_api -> n_db : UPDATE documents
n_db --> n_api : UPDATE 0
note over n_seller, n_api : Проигравший получает 409, а не тихую перезапись
n_seller -> n_api : POST /documents/inv_5120/cancel HTTP/1.1
n_api --> n_seller : HTTP/1.1 409 Conflict
note over n_buyer, n_api : Разрешённые переходы — из одной таблицы
n_buyer -> n_api : POST /documents/inv_5120/reject HTTP/1.1
n_api --> n_buyer : HTTP/1.1 422 Unprocessable Content
note over n_api, n_registry : Последнее слово за реестром, и он отвечает позже
n_api -> n_registry : POST /v1/documents/inv_5120/accept HTTP/1.1
n_registry --> n_api : HTTP/1.1 202 Accepted
note over n_registry, n_api : Ждать в промежуточном состоянии, пока реестр не подтвердит
n_registry -> n_api : POST /registry/callbacks HTTP/1.1
n_api --> n_registry : HTTP/1.1 200 OK
note over n_registry, n_api : Callback приходит дважды или не приходит вовсе
n_registry ->x n_api : [потеряно] callback log, registry -> api
note over n_api, n_db : Каждый event id обрабатывать один раз
n_api -> n_db : INSERT INTO registry_events (event_id, received_at)
n_db --> n_api : INSERT 0 0
note over n_worker, n_registry : Задача сверки спрашивает о зависших документах
n_worker -> n_registry : GET /v1/documents/inv_5133/status HTTP/1.1
n_registry --> n_worker : HTTP/1.1 200 OK
note over n_api, n_db : Каждый переход пишет историю и строку outbox
n_api -> n_db : BEGIN;
@endumlPlantUML: компоненты
@startuml
left to right direction
agent "Приложение продавца" as n_seller
agent "Приложение покупателя" as n_buyer
component "API документов" as n_api
database "База документов" as n_db
cloud "Реестр" as n_registry
collections "Сверка статусов" as n_worker
queue "События" as n_events
n_seller --> n_api
n_buyer --> n_api
n_api --> n_db
n_api --> n_registry
n_registry -[#c62828,dashed]-> n_api : потеряно
n_worker --> n_db
n_worker --> n_registry
n_db --> n_events
n_events --> n_buyer
@endumlИтог
Пять правил для документов, синхронизированных с реестром.
1) Состояния и переходы живут в одной таблице переходов. 2) Каждое обновление проверяет version; 0 строк — это 409. 3) Пока реестр не подтвердил, документ в промежуточном состоянии, а не окончательном. 4) Callback дедуплицируются по event_id, потерянные подбирает задача сверки. 5) Каждый переход пишет историю и строку outbox в той же транзакции.
Показатели: в начале и в конце
| Показатель | В начале | В конце |
|---|---|---|
| Потерянные обновления | 0/день | 0/день |
| Расходится с реестром | 0 | 0 |
| Зависли в ожидании | 0 | 0 |
| Повторные эффекты | 0/день | 0/день |
Шаги
- Кейс Счёт-фактура — это машина состояний
Продавец создаёт счёт-фактуру
inv_5120какdraft(черновик), подписывает (signed) и отправляет (sent). - Проблема Два пользователя действуют одновременно
Покупатель нажимает принять, через 5 мс продавец нажимает отменить.
- Решение Обновлять только прочитанную версию
Теперь обновление указывает, на какой версии оно основано.
- Кейс Проигравший получает 409, а не тихую перезапись
Клиент отправляет в
If-Matchверсию, которую показал пользователю. - Решение Разрешённые переходы — из одной таблицы
У второго сотрудника покупателя открыта старая вкладка, и он жмёт отклонить на уже принятой счёт-фактуре, со свежей версией.
- Проблема Последнее слово за реестром, и он отвечает позже
Принятая счёт-фактура вступает в силу, только когда её зарегистрирует реестр.
- Решение Ждать в промежуточном состоянии, пока реестр не подтвердит
В таблице появляются новые строки:
delivered + accept -> accept_pending, затемaccept_pending + registered -> acceptedиaccept_pending + rejected -> delivered. - Проблема Callback приходит дважды или не приходит вовсе
API обрабатывал первый callback 12 секунд, реестр перестал ждать через 10 и отправил его повторно.
- Решение Каждый event id обрабатывать один раз
Обработчик сначала записывает
event_idв таблицу с уникальным ключом. - Решение Задача сверки спрашивает о зависших документах
Каждые 5 минут задача выбирает документы, которые больше 15 минут стоят в промежуточном состоянии, и запрашивает их статус у реестра.
- Решение Каждый переход пишет историю и строку outbox
В одной транзакции API обновляет документ, добавляет строку истории (откуда, куда, кто, почему, когда) и строку outbox.
- Итоги Итог
Пять правил для документов, синхронизированных с реестром.
Термины
- Машина состояний
- Объект меняется только по парам (состояние, действие), разрешённым в таблице переходов. Любой другой переход отклоняется.
- Промежуточное состояние (pending)
- Промежуточное состояние, в котором документ ждёт подтверждения внешней системы. До подтверждения итог пользователю не показывают.