Permission
Cada Permission é um par action:resource que representa uma capacidade específica no sistema.
| 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 |
read:trip está disponível para todas as organizações, mas criar, atualizar e cancelar viagens é exclusivo de Company.
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 |
Permissions com escopo BackOffice não pertencem a nenhum tipo de organização. Elas só fazem sentido para roles INTERNAL.
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 |
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. |
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.
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:
- O access token identifica o usuário.
- O Profile precisa estar ativo; caso contrário a requisição é rejeitada (
403).
- Se a rota exige uma API surface, o claim
access:{api} correspondente é conferido.
- 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.
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.
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.
