Начните с одного вопроса: лимит покупает организация или каждый сотрудник? Если тариф обещает компании 10 000 операций, добавление коллеги не должно создавать ещё 10 000 и не должно само по себе расходовать ни одной операции. Приглашение меняет состав команды; расход появляется только после измеряемого действия.

Персональные места и metered usage могут одновременно влиять на счёт, но считать их одной колонкой нельзя. В модели per-seat количество пользователей обычно становится quantity подписки, тогда как потребление регистрируется отдельными событиями. Эта граница должна совпадать в продукте, базе и биллинге.

Сначала запишите два словаря

СущностьЧто считаетЧто не делает
membershipроль и состояние сотрудникане хранит остаток компании
seat quantityоплачиваемые активные местане измеряет операции
quota accountлимит и период tenantне выдаёт права
usage eventодно списание/возвратне меняет membership
invitationодноразовое приглашениене является потреблением

Согласуйте, какие membership входят в seats: pending, active, suspended, removed. Не угадывайте это по числу строк users. Например, pending может резервировать место или не резервировать — оба варианта допустимы, если правило явно показано пользователю и одинаково применяется в биллинге.

Общая квота принадлежит tenant

quota_accounts: tenant_id, period_start, limit_units, used_units, version
usage_events: tenant_id, actor_user_id, request_id, units, kind, occurred_at
memberships: tenant_id, user_id, role, state, activated_at

UNIQUE (tenant_id, request_id)

`actor_user_id` нужен для аудита, но не становится владельцем остатка. Если сотрудника удалить, прошлые события остаются в ledger и по-прежнему объясняют использованный объём. Перенос пользователя между организациями не должен переносить за ним расход.

Списание выполняется одной атомарной операцией

Проверка «остаток больше нуля», а затем отдельный UPDATE создаёт гонку: два сотрудника одновременно увидят последнюю единицу и оба получат успех. Используйте транзакцию и блокировку строки quota account либо условный UPDATE, который меняет `used_units` только когда хватает остатка. PostgreSQL описывает row-level locks и транзакции как средства согласовать такие изменения.

BEGIN;
INSERT INTO usage_events (..., request_id, units)
  VALUES (..., :key, :units)
  ON CONFLICT (tenant_id, request_id) DO NOTHING;

UPDATE quota_accounts
SET used_units = used_units + :units
WHERE tenant_id = :tenant
  AND used_units + :units <= limit_units;
COMMIT;

Это иллюстрация, не готовый порядок запросов: в реализации результат INSERT и UPDATE связывают так, чтобы существующий idempotency key не списывал повторно, а неуспешный reserve не оставлял usage event. Проще держать всю ветку в одной функции/транзакции и тестировать rollback.

Повтор запроса возвращает прежний ответ

  • Клиент создаёт request ID на логическое действие, а не на каждую сетевую попытку.
  • Сервер проверяет уникальность в границах tenant.
  • После timeout повтор с тем же ID не создаёт второе списание.
  • Компенсация оформляется новым событием с ссылкой на исходное.
  • Сумма ledger регулярно сверяется с материализованным used_units.

Жизненный цикл приглашения не трогает usage

  1. Создать invitation со случайным одноразовым token и сроком действия.
  2. После принятия связать пользователя с tenant и назначить роль.
  3. По политике seats перевести membership в оплачиваемое состояние.
  4. Создавать usage event лишь при выполнении измеряемой операции.
  5. При удалении отозвать доступ, но не удалять исторический ledger.

Особенно проверьте повторное принятие одного приглашения, два приглашения на один email и вход уже существующего пользователя. Эти ветки часто создают дубликат membership, после чего один человек дважды попадает в seat count или имеет два источника прав.

Тест последних единиц обнаруживает гонку

СценарийОжидаемый итогИнвариант
два запроса при остатке 1успех только у одногоused <= limit
retry после timeoutтот же ответодно usage event
pending приглашениепо политике seat, usage 0лимит не меняется
удаление сотрудникадоступ закрытистория сохранена
смена периодановый quota accountстарый период неизменяем

Сверка ищет расхождение трёх чисел

Показывайте отдельно активные места, лимит периода и использованные единицы. Фоновая сверка сравнивает seat quantity с membership policy, сумму ledger с used_units и значения, отправленные биллингу. Автоматически исправлять прошлый счёт без аудита не стоит: сначала сохраните расхождение и первичные события.

Для диагностики подготовьте tenant ID, правила состояний membership, три обезличенных request ID, значения quota до и после и transaction trace. Email приглашённого, платёжные данные и полный invitation token не нужны.

Проверенные источники