Mapeamento de Banco de Dados — `notifications`

Pilar: 04 — Banco de Dados / Tabelas
Status: 🟢 Implementado
Última Revisão Técnica: 2026-08-03
Módulos Conectados: gatein-server (app/models.py, app/api/mobile/notifications.py)

1. Visão Geral da Modelagem

A tabela notifications armazena o histórico persistente de todas as notificações enviadas para os motoristas de frete. Essa tabela alimenta a tela de Notificações do aplicativo mobile e fornece suporte para o controle de badge de "mensagens não lidas".

2. Atributos Físicos da Tabela `notifications`

Coluna	Tipo SQL	Constraints	Descrição / Regra
`id`	`UUID`	`PRIMARY KEY`, Default `gen_random_uuid()`	Identificador único interno da notificação
`driver_id`	`UUID`	`FOREIGN KEY (drivers.id)`, `NOT NULL`, `INDEX`	Motorista destinatário da notificação
`company_id`	`UUID`	`FOREIGN KEY (companies.id)`, `NOT NULL`, `INDEX`	Terminal ou Transportador emissor (Tenant Guard)
`type`	`VARCHAR(64)`	`NOT NULL`, `INDEX`	Tipo do evento (ex: `CHECKIN_APPROVED`, `REMINDER_1DAY`)
`title`	`VARCHAR(255)`	`NOT NULL`	Título legível da notificação
`body`	`TEXT`	`NOT NULL`	Corpo completo da mensagem enviada
`data`	`JSONB`	`NULLABLE`	Payload serializado utilizado para deep links e navegação interna no app
`is_read`	`BOOLEAN`	`NOT NULL`, Default `false`, `INDEX`	Flag indicando se o motorista abriu a notificação no app
`read_at`	`TIMESTAMPTZ`	`NULLABLE`	Timestamp exato de leitura pelo motorista
`sent_at`	`TIMESTAMPTZ`	`NOT NULL`, Default `now()`	Timestamp em que o servidor despachou a notificação para o FCM
`fcm_message_id`	`VARCHAR(255)`	`NULLABLE`	ID de rastreamento retornado pelo Google FCM
`fcm_error`	`TEXT`	`NULLABLE`	Descrição do erro caso a notificação tenha falhado
`created_at`	`TIMESTAMPTZ`	`NOT NULL`, Default `now()`	Data de inserção no banco de dados

3. Índices e Performance

idx_notifications_driver_created: Índice composto (driver_id, created_at DESC) para acelerar a busca da lista de notificações na tela mobile com ordenação cronológica.
idx_notifications_driver_unread: Índice composto parcial (driver_id, is_read) otimizado para a contagem rápida de notificações não lidas (alimentação do contador de badge da home).

4. Diagrama de Relacionamento (ER)

erDiagram
    DRIVERS ||--o{ NOTIFICATIONS : "recebe"
    COMPANIES ||--o{ NOTIFICATIONS : "dispara"
    NOTIFICATIONS {
        uuid id PK
        uuid driver_id FK
        uuid company_id FK
        string type
        string title
        text body
        jsonb data
        boolean is_read
        timestamp read_at
        timestamp sent_at
    }

5. Endpoints Relacionados no Mobile

5.1 Listagem de Notificações (`GET /mobile/notifications`)

Retorna o histórico de notificações paginado para o motorista autenticado.

5.2 Leitura de Notificação (`PATCH /mobile/notifications/{id}/read`)

Marca a notificação como lida, atualizando is_read = true e read_at = now().

1. Visão Geral da Modelagem​

2. Atributos Físicos da Tabela notifications​

3. Índices e Performance​

4. Diagrama de Relacionamento (ER)​

5. Endpoints Relacionados no Mobile​

5.1 Listagem de Notificações (GET /mobile/notifications)​

5.2 Leitura de Notificação (PATCH /mobile/notifications/{id}/read)​