Начните с одного вопроса: лимит покупает организация или каждый сотрудник? Если тариф обещает компании 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
- Создать invitation со случайным одноразовым token и сроком действия.
- После принятия связать пользователя с tenant и назначить роль.
- По политике seats перевести membership в оплачиваемое состояние.
- Создавать usage event лишь при выполнении измеряемой операции.
- При удалении отозвать доступ, но не удалять исторический 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 не нужны.