> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devmob.app.br/llms.txt
> Use this file to discover all available pages before exploring further.

# ERD

> ERDs atuais da modelagem de dados do DEVMOB

## Overview

Esta página centraliza a representação atual dos relacionamentos entre as entities documentadas em Data Modelling. Os diagramas mostram ownership, cardinalidade e dependências principais por domain.

## Domains

| Domain        | Entities e views documentadas                                                                                                                                                                     |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Identity      | `User`, `UserSession`, `Customer`, `CustomerAddress`, `OTP`, `Profile`                                                                                                                            |
| Tenant        | `Organization`, `OrganizationAddress`, `Cooperative`, `Company`, `Employee`, `Invite`, `Membership`                                                                                               |
| Authorization | `Role`, `RolePermission`                                                                                                                                                                          |
| Fleet         | `Driver`, `DriverCompany`, `Vehicle`, `Seat`, `SeatType`                                                                                                                                          |
| Operations    | `Point`, `Route`, `RouteApproval`, `TripSchedule`, `TripScheduleStop`, `TripScheduleItinerary`, `Trip`, `TripReview`, `TripTracking`, `TripStop`, `TripItinerary`, `TripEvent`, `TripSeatSegment` |
| Sales         | `Checkout`, `Order`, `Ticket`, `TicketActivity`, `Passenger`                                                                                                                                      |
| Benefits      | `FareBenefitCategory`, `FareBenefitProgram`, `PassengerBenefitRequest`, `BenefitDocumentValidation`, `BenefitUsageHistory`                                                                        |
| Credit Grant  | `CreditGrant`, `CreditLedgerEntry`                                                                                                                                                                |
| Promotion     | `Promotional`, `PromotionalRouteRule`, `PromotionalRoundTripRule`, `PromotionalMultiTicketRule`, `PromotionalLowDemandTimeRule`, `PromotionalUsageHistory`                                        |
| Support       | `SupportCase`, `SupportCaseMessage`, `SupportCaseAttachment`, `SupportCaseAssignment`, `SupportCaseCategory`, `SupportCaseSatisfactionRating`                                                     |
| Communication | `Notification`, `NotificationRecipient`                                                                                                                                                           |
| Export        | `ExportResource`, `ExportScheduled`, `ExportJob`                                                                                                                                                  |
| Billing       | `CompanyPaymentSettings`, `Payment`, `PaymentMethod`, `Receivable`, `BankAccount`, `Transfer`                                                                                                     |
| Webhooks      | `Webhook`                                                                                                                                                                                         |
| Observability | `AuditLog`                                                                                                                                                                                        |

## ERD global

```mermaid theme={null}
erDiagram
    User ||--o| Customer : has
    User ||--o{ UserSession : authenticates
    User ||--o{ Membership : receives
    User ||--o{ Invite : issues_or_accepts
    Organization ||--o| Cooperative : extends
    Organization ||--o| Company : extends
    Cooperative ||--o{ Company : administers
    Role ||--o{ Membership : grants
    Company ||--o{ Vehicle : owns
    Company ||--o{ DriverCompany : links
    Driver ||--o{ DriverCompany : links
    Company ||--o{ Route : owns
    Route ||--o{ RouteApproval : reviewed_by
    Route ||--o{ Trip : schedules
    Vehicle ||--o{ Trip : operates
    Driver ||--o{ Trip : drives
    Trip ||--o| TripTracking : has_current_tracking
    Driver ||--o{ TripTracking : sends
    Trip ||--o{ TripItinerary : exposes
    Trip ||--o{ TripReview : reviewed_by
    Checkout ||--o{ Order : groups
    Company ||--o{ Order : owns
    Customer ||--o{ Order : buys
    Customer ||--o{ TripReview : writes
    Order ||--o{ Ticket : contains
    Order ||--o{ TripReview : enables
    Ticket ||--o{ TicketActivity : records
    Trip ||--o{ Ticket : sells
    TripItinerary ||--o{ Ticket : prices
    Order ||--o| Payment : charges
    Payment ||--o{ Receivable : creates
    Company ||--o{ CreditGrant : grants
    CreditGrant ||--o{ CreditLedgerEntry : records
    Company ||--o{ Promotional : owns
    Promotional ||--o{ PromotionalUsageHistory : applies
    FareBenefitCategory ||--o{ FareBenefitProgram : defines
    FareBenefitProgram ||--o{ PassengerBenefitRequest : receives
    Order ||--o{ BenefitUsageHistory : uses
    SupportCase ||--o{ SupportCaseMessage : contains
    TripReview ||--o{ SupportCase : starts_contact
    Organization ||--o{ Notification : scopes
    User ||--o{ Notification : creates
    Notification ||--o{ NotificationRecipient : delivers
    User ||--o{ NotificationRecipient : receives
    ExportResource ||--o{ ExportJob : catalogs
    Organization ||--o{ AuditLog : scopes
```

## ERD por domain

| Domain        | Representação atual                                                                                                                                                                                                                                                   |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Identity      | `User` centraliza autenticação. `UserSession` registra sessões revogáveis. `Customer`, `CustomerAddress`, `OTP` e a view `Profile` derivam identidade, contato, endereço e escopo autenticado.                                                                        |
| Tenant        | `Organization` é a raiz multi-tenant. `Cooperative` e `Company` especializam a organização, com `Cooperative` administrando múltiplas companies. `Membership`, `Invite` e `Employee` modelam acesso, convite e vínculo operacional.                                   |
| Authorization | `Role` pertence à organização e agrega `RolePermission`. `Membership` e `Invite` apontam para a role que concede acesso.                                                                                                                                              |
| Fleet         | `Company` mantém veículos, motoristas por empresa e mapa de assentos. `Driver` nasce do `User`; `DriverCompany` guarda o vínculo operacional por company.                                                                                                             |
| Operations    | `Route`, `RouteApproval`, `TripSchedule`, `Trip`, `TripReview` e `TripTracking` organizam rota, aprovação, programação, execução, avaliação da viagem, último tracking GPS, paradas, itinerários vendáveis, eventos e ocupação de assentos por trecho.                |
| Sales         | `Checkout` agrupa `Order`. `Order` contém `Ticket`, referencia comprador, company e pagamento. `TicketActivity` registra tentativas de uso, validações e reimpressões.                                                                                                |
| Benefits      | `FareBenefitCategory` define tipos gerais. `FareBenefitProgram` configura aplicação por contexto. `PassengerBenefitRequest`, `BenefitDocumentValidation` e `BenefitUsageHistory` registram solicitação, validação e uso aplicado ao pedido.                           |
| Credit Grant  | `CreditGrant` registra crédito concedido por company a Customer. `CreditLedgerEntry` registra concessão, reserva, consumo, estorno e expiração do crédito. Regras de funcionário validam elegibilidade antes da concessão, mas não criam FK para Employee no crédito. |
| Promotion     | `Promotional` é a promoção configurada pela company. As regras fixas vivem em tabelas próprias por tipo, e `PromotionalUsageHistory` registra a aplicação no checkout, order ou ticket.                                                                               |
| Support       | `SupportCase` organiza chamado, categoria, mensagens, anexos, atribuições e avaliação de satisfação. Pode apontar para order, trip review, ticket ou trip conforme o contexto.                                                                                        |
| Communication | `Notification` guarda conteúdo e contexto da notificação. `NotificationRecipient` guarda leitura, entrega, arquivamento e remoção por usuário.                                                                                                                        |
| Export        | `ExportResource` cataloga recursos exportáveis. `ExportScheduled` define recorrência. `ExportJob` registra a execução e o arquivo gerado.                                                                                                                             |
| Billing       | `Payment` registra cobrança da order. `Receivable` detalha valores a receber por company. `BankAccount`, `Transfer`, `PaymentMethod` e `CompanyPaymentSettings` sustentam pagamento, repasse e configuração financeira.                                               |
| Webhooks      | `Webhook` guarda eventos externos por provider, identificadores externos, payload e status de processamento, sem FK local documentada.                                                                                                                                |
| Observability | `AuditLog` registra ações por organização e usuário para rastreabilidade operacional.                                                                                                                                                                                 |

## Identity, Tenant e Authorization

```mermaid theme={null}
erDiagram
    User ||--o| Customer : has
    User ||--o{ UserSession : authenticates
    User ||--o| Profile : derives
    Customer ||--o| Profile : enriches
    User ||--o{ OTP : receives
    Customer ||--o{ CustomerAddress : has

    Organization ||--o| OrganizationAddress : has
    Organization ||--o| Cooperative : extends
    Organization ||--o| Company : extends
    Cooperative ||--o{ Company : administers

    Organization ||--o{ Role : scopes
    Role ||--o{ RolePermission : contains
    User ||--o{ Membership : receives
    Organization ||--o{ Membership : scopes
    Role ||--o{ Membership : grants

    User ||--o{ Invite : invited_by
    User ||--o{ Invite : invited_user
    Organization ||--o{ Invite : scopes
    Role ||--o{ Invite : grants

    Company ||--o{ Employee : owns
    Organization ||--o{ Employee : scopes
    Membership ||--o| Employee : originates
    User ||--o{ Employee : represents
    Customer ||--o{ Employee : links
```

<Info>
  `Profile` é uma view consolidada do usuário autenticado. Ele deriva dados de `User`, `Customer`, roles, memberships e vínculos operacionais.
</Info>

## Fleet e Operations

```mermaid theme={null}
erDiagram
    Company ||--o{ Vehicle : owns
    Company ||--o{ DriverCompany : links
    Driver ||--o{ DriverCompany : links
    User ||--o| Driver : has

    Vehicle ||--o{ SeatType : defines
    Vehicle ||--o{ Seat : contains
    SeatType ||--o{ Seat : classifies

    Company ||--o{ Route : owns
    Point ||--o{ Route : origin
    Point ||--o{ Route : destination
    Route ||--o{ RouteApproval : reviewed_by
    User ||--o{ RouteApproval : requests_or_reviews

    Company ||--o{ TripSchedule : owns
    Route ||--o{ TripSchedule : templates
    Vehicle ||--o{ TripSchedule : templates
    Driver ||--o{ TripSchedule : templates
    TripSchedule ||--o{ TripScheduleStop : contains
    Point ||--o{ TripScheduleStop : stops_at
    TripSchedule ||--o{ TripScheduleItinerary : exposes

    Company ||--o{ Trip : owns
    Route ||--o{ Trip : runs
    Vehicle ||--o{ Trip : operates
    Driver ||--o{ Trip : drives
    Trip ||--o| TripTracking : has_current_tracking
    Driver ||--o{ TripTracking : sends
    Trip ||--o{ TripStop : contains
    Point ||--o{ TripStop : stops_at
    Trip ||--o{ TripItinerary : exposes
    TripStop ||--o{ TripItinerary : from_stop
    TripStop ||--o{ TripItinerary : to_stop
    Trip ||--o{ TripEvent : records
    TripStop ||--o{ TripEvent : at_stop
    Trip ||--o{ TripSeatSegment : controls
    Seat ||--o{ TripSeatSegment : occupies
```

<Note>
  `TripScheduleItinerary` referencia paradas por `stopOrder` dentro da mesma programação. O vínculo direto com `TripScheduleStop` não é FK documentada hoje.
</Note>

## Sales e Billing

```mermaid theme={null}
erDiagram
    Customer ||--o{ Checkout : starts
    Checkout ||--o{ Order : groups
    Customer ||--o{ Order : buys
    Organization ||--o{ Order : scopes
    Company ||--o{ Order : owns
    User ||--o{ Order : sells

    Order ||--o{ Ticket : contains
    Passenger ||--o{ Ticket : travels
    Trip ||--o{ Ticket : sells
    TripItinerary ||--o{ Ticket : prices
    Seat ||--o{ Ticket : assigns
    SeatType ||--o{ Ticket : prices
    Ticket ||--o{ TicketActivity : records
    Trip ||--o{ TicketActivity : scopes
    Driver ||--o{ TicketActivity : performs
    User ||--o{ TicketActivity : performs
    Ticket ||--o{ TripSeatSegment : occupies

    Order ||--o{ TripReview : enables
    Trip ||--o{ TripReview : reviewed_by
    Checkout ||--o{ TripReview : via_order
    Customer ||--o{ TripReview : writes
    Driver ||--o{ TripReview : receives
    Company ||--o{ TripReview : receives

    Order ||--o| Payment : charges
    Organization ||--o{ Payment : scopes
    Company ||--o{ Payment : receives
    Payment ||--o{ Receivable : creates
    Organization ||--o{ Receivable : scopes
    Company ||--o{ Receivable : receives

    Customer ||--o{ PaymentMethod : stores
    Organization ||--o{ BankAccount : scopes
    Company ||--o| BankAccount : owns
    BankAccount ||--o{ Transfer : receives
    Organization ||--o{ Transfer : scopes
    Company ||--o{ Transfer : requests
    Company ||--o| CompanyPaymentSettings : configures
    Organization ||--o{ CompanyPaymentSettings : scopes
```

## Benefits

```mermaid theme={null}
erDiagram
    FareBenefitCategory ||--o{ FareBenefitProgram : configures
    FareBenefitCategory ||--o{ BenefitUsageHistory : classifies

    Company ||--o{ FareBenefitProgram : owns
    Route ||--o{ FareBenefitProgram : restricts
    FareBenefitProgram ||--o{ PassengerBenefitRequest : receives
    FareBenefitProgram ||--o{ BenefitUsageHistory : applies

    Customer ||--o{ PassengerBenefitRequest : requests
    User ||--o{ PassengerBenefitRequest : requests_or_reviews
    PassengerBenefitRequest ||--o{ BenefitDocumentValidation : validates
    PassengerBenefitRequest ||--o{ BenefitUsageHistory : authorizes

    Customer ||--o{ BenefitDocumentValidation : submits
    User ||--o{ BenefitDocumentValidation : validates

    Order ||--o{ BenefitUsageHistory : applies_to
    Customer ||--o{ BenefitUsageHistory : benefits
    Company ||--o{ BenefitUsageHistory : scopes
    Route ||--o{ BenefitUsageHistory : scopes
    Trip ||--o{ BenefitUsageHistory : scopes
```

## Credit Grant e Promotion

```mermaid theme={null}
erDiagram
    Organization ||--o{ CreditGrant : scopes
    Company ||--o{ CreditGrant : grants
    Customer ||--o{ CreditGrant : receives
    User ||--o{ CreditGrant : granted_by
    CreditGrant ||--o{ CreditLedgerEntry : records
    Company ||--o{ CreditLedgerEntry : scopes
    Customer ||--o{ CreditLedgerEntry : benefits
    Checkout ||--o{ CreditLedgerEntry : uses
    Order ||--o{ CreditLedgerEntry : uses
    Ticket ||--o{ CreditLedgerEntry : uses

    Organization ||--o{ Promotional : scopes
    Company ||--o{ Promotional : owns
    Promotional ||--o| PromotionalRouteRule : route_rule
    Promotional ||--o| PromotionalRoundTripRule : round_trip_rule
    Promotional ||--o| PromotionalMultiTicketRule : multi_ticket_rule
    Promotional ||--o| PromotionalLowDemandTimeRule : low_demand_rule
    Company ||--o{ PromotionalRouteRule : scopes
    Company ||--o{ PromotionalRoundTripRule : scopes
    Company ||--o{ PromotionalMultiTicketRule : scopes
    Company ||--o{ PromotionalLowDemandTimeRule : scopes
    Route ||--o{ PromotionalRouteRule : validates
    Route ||--o{ PromotionalRoundTripRule : outbound_or_return
    Route ||--o{ PromotionalLowDemandTimeRule : restricts
    Promotional ||--o{ PromotionalUsageHistory : applies
    Company ||--o{ PromotionalUsageHistory : scopes
    Customer ||--o{ PromotionalUsageHistory : receives
    Checkout ||--o{ PromotionalUsageHistory : validates
    Order ||--o{ PromotionalUsageHistory : applies_to
    Ticket ||--o{ PromotionalUsageHistory : applies_to
```

<Note>
  `PromotionalUsageHistory.validatedRuleId` aponta para a tabela de regra compatível com `validatedRuleType`: `PromotionalRouteRule`, `PromotionalRoundTripRule`, `PromotionalMultiTicketRule` ou `PromotionalLowDemandTimeRule`.
</Note>

## Support

```mermaid theme={null}
erDiagram
    SupportCaseCategory ||--o{ SupportCase : classifies
    Customer ||--o{ SupportCase : opens
    Organization ||--o{ SupportCase : scopes
    Company ||--o{ SupportCase : scopes
    Cooperative ||--o{ SupportCase : scopes
    User ||--o{ SupportCase : opens_or_handles
    Order ||--o{ SupportCase : relates
    TripReview ||--o{ SupportCase : starts_contact
    Ticket ||--o{ SupportCase : relates
    Trip ||--o{ SupportCase : relates

    SupportCase ||--o{ SupportCaseMessage : contains
    User ||--o{ SupportCaseMessage : sends
    SupportCase ||--o{ SupportCaseAttachment : contains
    SupportCaseMessage ||--o{ SupportCaseAttachment : contains
    User ||--o{ SupportCaseAttachment : uploads

    SupportCase ||--o{ SupportCaseAssignment : assigns
    User ||--o{ SupportCaseAssignment : from_to_by
    SupportCase ||--o| SupportCaseSatisfactionRating : rated_by
    Customer ||--o{ SupportCaseSatisfactionRating : rates
    User ||--o{ SupportCaseSatisfactionRating : rates
```

## Communication

```mermaid theme={null}
erDiagram
    Organization ||--o{ Notification : scopes
    User ||--o{ Notification : creates
    Notification ||--o{ NotificationRecipient : delivers
    User ||--o{ NotificationRecipient : receives
```

<Info>
  `Notification.resourceDomain`, `Notification.resource` e `Notification.resourceId` apontam para o recurso relacionado sem FK direta. O front resolve a rota de abertura pelo `type` da notificação e pelo recurso relacionado.
</Info>

## Export

```mermaid theme={null}
erDiagram
    ExportResource ||--o{ ExportScheduled : catalogs
    ExportResource ||--o{ ExportJob : catalogs
    ExportScheduled ||--o{ ExportJob : creates

    Organization ||--o{ ExportScheduled : scopes
    Company ||--o{ ExportScheduled : scopes
    Cooperative ||--o{ ExportScheduled : scopes
    User ||--o{ ExportScheduled : requests

    Organization ||--o{ ExportJob : scopes
    Company ||--o{ ExportJob : scopes
    Cooperative ||--o{ ExportJob : scopes
    User ||--o{ ExportJob : requests
```

## Webhooks e Observability

```mermaid theme={null}
erDiagram
    Webhook {
      UUID webhookId
      String externalProvider
      String externalEventId
      String externalEventType
      String status
    }

    Organization ||--o{ AuditLog : scopes
    User ||--o{ AuditLog : acts
```

<Info>
  `Webhook` referencia recursos externos pelo payload e pelos identificadores do provider. Ele não possui FK local documentada hoje.
</Info>