Описание таблицы в БД
Пример того, как я описываю таблицы PostgreSQL в спецификациях: нейминг-конвеншн, типы, ключи, дефолты, not null и ссылки на глоссарий. Таблица связана со спецификацией «Спецификация + REST API» — коды ошибок и типы операций совпадают с контрактом API.
Loyalty.GPB.pgsql.sch.bonus.t.charge_off_operation
| Описание | Таблица операций списания / отмены списания бонусных баллов через партнерский API |
|---|
| имя | тип | ключ | not null | default | описание |
|---|---|---|---|---|---|
| id | bigint | PK | + | generated always as identity | Идентификатор операции (суррогатный ключ) |
| operation_uid | uuid | UQ | + | gen_random_uuid() | Внешний идентификатор операции — параметр id партнерского API |
| phone_number | varchar(11) | IDX | + | Идентификатор клиента, номер телефона в формате 7XXXXXXXXXX | |
| partner_id | int | FK | + | Идентификатор партнера в системе Банка, см. глоссарий Partner | |
| operation_type | smallint | + | Тип операции: 1 — списание, 2 — отмена | ||
| amount | numeric(12,2) | + | Сумма баллов (1 балл = 1 рубль) | ||
| status | varchar(20) | IDX | + | 'created' | Статус операции: created / sent / success / rejected, см. глоссарий OperationStatus |
| error_code | int | Код отказа ГПБ: 1–4, см. «Спецификация + REST API», маппинг ответов с ошибками | |||
| external_response | jsonb | Сырой ответ ГПБ API для аудита и разбора спорных операций | |||
| is_retry | boolean | + | false | Признак повторного запроса (механизм retry) | |
| retry_count | smallint | + | 0 | Количество выполненных повторов | |
| sent_at | timestamptz | Момент отправки запроса в ГПБ API | |||
| created_at | timestamptz | + | now() | Момент создания записи | |
| updated_at | timestamptz | + | now() | Момент последнего изменения статуса (обновляется триггером) | |
| created_by | varchar(64) | + | 'system' | Инициатор: system или логин сотрудника при ручной обработке | |
| comment | text | Комментарий оператора поддержки при ручной обработке | |||
| loyalty_program_code | varchar(10) | 'GPB_MVP' | Код программы лояльности — поле в планах, при переходе на несколько программ |
Индексы и ограничения
pk_charge_off_operation— первичный ключ поid.uq_charge_off_operation_uid— уникальностьoperation_uid: защита от двойного списания при повторных запросах.idx_charge_off_operation_phone— поиск операций клиента по номеру телефона.idx_charge_off_operation_status_sent— частичный индексwhere status in ('created','sent')для воркера повторов.fk_charge_off_operation_partner— внешний ключ кt.partner (partner_id).
ERD фрагмента схемы
Примечание: описание таблицы синхронизировано с контрактом API — значения error_code и operation_type один в один из спецификации, чтобы разработка и тестирование не гадали, где истина.