> ## 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.

# Roles & Permissions

> Catálogo de permissions action:resource, role types e atribuição via Membership.

## Permission

Cada Permission é um par `action:resource` que representa uma capacidade específica no sistema.

### Formato

```
action:resource
```

| Componente | Descrição            | Exemplos                                      |
| ---------- | -------------------- | --------------------------------------------- |
| `action`   | A operação permitida | `create`, `read`, `update`, `delete`          |
| `resource` | O recurso alvo       | `trip`, `order`, `vehicle`, `driver`, `route` |

### Catálogo de Permissions

O catálogo é controlado pelo DEVMOB e usado pelas superfícies Ops e BackOffice.

Cada entrada declara em quais **API surfaces** (`ops`, `bko`) ela é aceita e a quais **tipos de organização** ela se aplica (`Company`, `Cooperative` ou `Todas`). O tipo de organização define a composição da role admin padrão criada com cada organização.

#### Organização & acesso

| Permission                | Descrição                               | APIs         | Escopo     |
| ------------------------- | --------------------------------------- | ------------ | ---------- |
| `read:organization`       | Visualizar perfil da organização        | `bko`, `ops` | Todas      |
| `update:organization`     | Atualizar perfil da organização         | `bko`, `ops` | Todas      |
| `read:role`               | Listar roles                            | `bko`, `ops` | Todas      |
| `create:role`             | Criar roles                             | `bko`, `ops` | Todas      |
| `update:role`             | Atualizar roles                         | `bko`, `ops` | Todas      |
| `delete:role`             | Remover roles                           | `bko`, `ops` | Todas      |
| `read:member`             | Listar membros                          | `bko`, `ops` | Todas      |
| `create:member`           | Convidar novo membro                    | `bko`, `ops` | Todas      |
| `update:member`           | Atualizar um membro                     | `bko`, `ops` | Todas      |
| `delete:member`           | Revogar um membro                       | `bko`, `ops` | Todas      |
| `read:user`               | Listar usuários                         | `bko`        | BackOffice |
| `update:user`             | Bloquear ou desbloquear usuários        | `bko`        | BackOffice |
| `read:benefit_category`   | Listar categorias globais de benefício  | `bko`, `ops` | Todas      |
| `create:benefit_category` | Criar categoria global de benefício     | `bko`        | BackOffice |
| `update:benefit_category` | Atualizar categoria global de benefício | `bko`        | BackOffice |
| `delete:benefit_category` | Remover categoria global de benefício   | `bko`        | BackOffice |
| `read:benefit_program`    | Listar programas de benefício           | `bko`, `ops` | Todas      |
| `create:benefit_program`  | Criar programa de benefício             | `bko`, `ops` | Todas      |
| `update:benefit_program`  | Atualizar programa de benefício         | `bko`, `ops` | Todas      |
| `delete:benefit_program`  | Remover programa de benefício           | `bko`        | BackOffice |
| `read:invite`             | Listar convites pendentes               | `bko`, `ops` | Todas      |
| `create:invite`           | Criar convites de membros               | `bko`, `ops` | Todas      |
| `delete:invite`           | Revogar convites de membros             | `bko`, `ops` | Todas      |
| `read:audit`              | Listar entradas do log de auditoria     | `ops`        | Todas      |

#### Frota

| Permission       | Descrição                            | APIs  | Escopo  |
| ---------------- | ------------------------------------ | ----- | ------- |
| `read:vehicle`   | Listar veículos da frota             | `ops` | Company |
| `create:vehicle` | Registrar novos veículos             | `ops` | Company |
| `update:vehicle` | Atualizar informações de veículos    | `ops` | Company |
| `delete:vehicle` | Remover veículos da frota            | `ops` | Company |
| `read:seat-type` | Listar sugestões de tipos de assento | `ops` | Company |
| `read:driver`    | Listar motoristas                    | `ops` | Company |
| `create:driver`  | Registrar novo motorista             | `ops` | Company |
| `update:driver`  | Atualizar informações do motorista   | `ops` | Company |
| `delete:driver`  | Remover motorista                    | `ops` | Company |

#### Operações

| Permission             | Descrição                          | APIs         | Escopo     |
| ---------------------- | ---------------------------------- | ------------ | ---------- |
| `read:point`           | Listar catálogo global de pontos   | `bko`, `ops` | Todas      |
| `create:point`         | Criar ponto no catálogo global     | `bko`        | BackOffice |
| `update:point`         | Atualizar ponto no catálogo global | `bko`        | BackOffice |
| `delete:point`         | Remover ponto no catálogo global   | `bko`        | BackOffice |
| `read:route`           | Listar rotas                       | `ops`        | Company    |
| `create:route`         | Criar rota                         | `ops`        | Company    |
| `update:route`         | Atualizar rota                     | `ops`        | Company    |
| `delete:route`         | Remover rota                       | `ops`        | Company    |
| `read:trip`            | Listar viagens                     | `ops`        | Todas      |
| `create:trip`          | Criar viagem                       | `ops`        | Company    |
| `update:trip`          | Atualizar viagem                   | `ops`        | Company    |
| `delete:trip`          | Cancelar viagem                    | `ops`        | Company    |
| `read:trip_schedule`   | Listar agendamentos de viagem      | `ops`        | Company    |
| `create:trip_schedule` | Criar agendamentos de viagem       | `ops`        | Company    |
| `update:trip_schedule` | Atualizar agendamentos de viagem   | `ops`        | Company    |
| `delete:trip_schedule` | Remover agendamentos de viagem     | `ops`        | Company    |
| `create:trip_event`    | Registrar evento de viagem         | `ops`        | Company    |

<Info>
  `read:trip` está disponível para **todas** as organizações, mas criar, atualizar e cancelar viagens é exclusivo de **Company**.
</Info>

#### Vendas

| Permission      | Descrição                | APIs         | Escopo  |
| --------------- | ------------------------ | ------------ | ------- |
| `read:checkout` | Listar checkouts         | `bko`, `ops` | Company |
| `read:order`    | Listar pedidos de venda  | `bko`, `ops` | Company |
| `create:order`  | Criar pedido de venda    | `ops`        | Company |
| `update:order`  | Cancelar pedido de venda | `ops`        | Company |
| `read:ticket`   | Listar tickets           | `ops`        | Company |
| `create:ticket` | Emitir ticket            | `ops`        | Company |
| `update:ticket` | Atualizar ticket         | `ops`        | Company |
| `delete:ticket` | Cancelar ticket          | `ops`        | Company |

#### Billing

| Permission            | Descrição                   | APIs         | Escopo |
| --------------------- | --------------------------- | ------------ | ------ |
| `read:bank_account`   | Visualizar conta bancária   | `bko`, `ops` | Todas  |
| `update:bank_account` | Definir conta bancária      | `ops`        | Todas  |
| `read:payment`        | Listar pagamentos           | `bko`, `ops` | Todas  |
| `read:balance`        | Visualizar saldo financeiro | `ops`        | Todas  |
| `read:receivable`     | Listar recebíveis           | `bko`, `ops` | Todas  |
| `read:transfer`       | Listar transferências       | `bko`, `ops` | Todas  |
| `create:transfer`     | Solicitar transferência     | `ops`        | Todas  |

<Note>
  Permissions com escopo **BackOffice** não pertencem a nenhum tipo de organização. Elas só fazem sentido para roles `INTERNAL`.
</Note>

### Claims de acesso à API

Além das permissions do catálogo, existem três claims derivados — `access:ops`, `access:bko` e `access:driver` — que liberam o ingresso em cada API surface. Eles não são atribuídos como entidade própria: aparecem no Profile a partir dos vínculos ativos do usuário.

| Claim           | Derivado quando                                                                                  |
| --------------- | ------------------------------------------------------------------------------------------------ |
| `access:ops`    | O usuário possui Membership `ACTIVE` em uma organização com Role `ENVIRONMENT` ou `ORGANIZATION` |
| `access:bko`    | O usuário possui Membership `ACTIVE` com Role `INTERNAL`                                         |
| `access:driver` | O usuário possui vínculo ativo como motorista em uma empresa                                     |

## Role

Uma Role agrupa um conjunto de permissions sob um nome descritivo.

| Campo            | Descrição                                                       |
| ---------------- | --------------------------------------------------------------- |
| `roleId`         | Identificador único                                             |
| `organizationId` | Organização dona da role; preenchido apenas para `ORGANIZATION` |
| `type`           | Tipo da role: `INTERNAL`, `ENVIRONMENT` ou `ORGANIZATION`       |
| `name`           | Nome da role (ex.: "Admin", "Operador")                         |
| `description`    | Descrição da role (opcional)                                    |
| `createdBy`      | Usuário que criou a role, quando aplicável                      |
| `createdAt`      | Timestamp da criação                                            |
| `updatedBy`      | Usuário que fez a última atualização, quando aplicável          |
| `updatedAt`      | Timestamp da última atualização                                 |
| `deletedBy`      | Usuário que removeu a role, quando aplicável                    |
| `deletedAt`      | Timestamp de remoção lógica                                     |

As permissions atribuídas à Role vivem em `RolePermission`, não em um campo próprio da Role.

Uma Role pode ter três tipos:

| RoleType       | Regra                                                                           |
| -------------- | ------------------------------------------------------------------------------- |
| `INTERNAL`     | Fora de organização; usada apenas no BackOffice.                                |
| `ENVIRONMENT`  | Global e reutilizável por organizações; a organização é definida na Membership. |
| `ORGANIZATION` | Customizada por uma organização; exige `organizationId`.                        |

<Info>
  Roles `ORGANIZATION` são customizáveis por organização. A Company A pode ter uma role "Supervisor" com permissions diferentes da role "Supervisor" da Company B.
</Info>

### Role admin padrão

A role admin padrão é uma Role `ENVIRONMENT` compatível com o tipo da organização. No onboarding, o owner recebe uma Membership `ACTIVE` na nova organização apontando para essa role. Assim, organizações podem reutilizar roles padrão, enquanto roles `ORGANIZATION` continuam disponíveis para customização local.

## Atribuição via Membership

**Membership** é o ponto de encontro entre User, Organization e Role. Um usuário pode acumular mais de uma role na mesma organização.

| Campo            | Descrição                                                     |
| ---------------- | ------------------------------------------------------------- |
| `membershipId`   | Identificador único da Membership                             |
| `userId`         | Referência ao User                                            |
| `organizationId` | Referência à Organization; `null` apenas para role `INTERNAL` |
| `roleId`         | Referência à Role atribuída                                   |
| `status`         | Estado do vínculo (`ACTIVE` ou `REVOKED`)                     |
| `revokedAt`      | Timestamp da revogação, quando aplicável                      |
| `revokedBy`      | Usuário que revogou o vínculo, quando aplicável               |
| `createdBy`      | Usuário que criou o vínculo, quando aplicável                 |
| `createdAt`      | Timestamp da criação                                          |
| `updatedBy`      | Usuário que fez a última atualização, quando aplicável        |
| `updatedAt`      | Timestamp da última atualização                               |

### Exemplo Prático

```
User: joao@email.com
├── Membership (Company "TransBrasil")
│   └── Role: "Gerente de Operações"
│       ├── create:trip
│       ├── update:trip
│       ├── read:order
│       └── read:receivable
│
└── Membership (Cooperative "Metropolitana")
    └── Role: "Coordenador"
        ├── read:organization
        ├── read:trip
        └── read:order
```

## Verificação de Permissão

A cada requisição autenticada:

1. O access token identifica o usuário.
2. O Profile precisa estar **ativo**; caso contrário a requisição é rejeitada (`403`).
3. Se a rota exige uma API surface, o claim `access:{api}` correspondente é conferido.
4. As permissions efetivas são comparadas com a permission exigida pela ação.

O conjunto de permissions efetivas é a **união** dos claims derivados, das permissions das roles `INTERNAL` e das permissions das roles `ENVIRONMENT`/`ORGANIZATION` da organização ativa. Somente Memberships `ACTIVE` entram nessa composição. Um Profile resolve **no máximo uma** organização ativa.

<Info>
  Quando uma ação aceita múltiplas permissions, basta possuir uma delas, salvo quando a própria ação exige todas. A organização ativa restringe o escopo da operação.
</Info>

<Warning>
  Se o usuário não possui Membership `ACTIVE` na organização ativa, ou se o `scope.permissionIds` não contém a permission exigida, a requisição é rejeitada com `403 Forbidden`.
</Warning>