# Modelo de Permissões: Grupos, Kits, Roles e Overrides

## Objetivo
Organizar o modelo de acesso do sistema separando identidade organizacional, pacote técnico de permissões, função/cargo e exceções operacionais.

## Regra principal
A hierarquia oficial passa a ser:
- `usuário -> grupo -> kit -> namespaces/slugs`
- `role` complementa contexto organizacional, senioridade e assentos.
- `override` cobre exceções por usuário, equipe ou contrato.

## Conceitos
### Grupos
Tabela base: `grupos_permissoes`

Grupo representa identidade operacional.
Exemplos:
- Financeiro
- RH
- Suporte
- Consultor Líder
- Profissionais
- Clientes

Grupo responde: "quem essa pessoa é na operação?"

### Kits
Tabela base: `perm_kits`

Kit representa um pacote técnico reaproveitável de capacidades.
Exemplos:
- `kit.cliente`
- `kit.profissional`
- `kit.assistente`

Kit responde: "que blocos de acesso essa identidade ganha?"

### Group Kits
Tabela nova de vínculo: `perm_group_kit`

Ela conecta a identidade operacional ao pacote técnico.
Esse vínculo é o caminho recomendado para o ACL administrativo.

### Roles
Tabelas relacionadas: `role_catalog`, `role_bindings`, `role_group_map`, `role_level_map`

Role representa cargo, assento, cadeira organizacional ou senioridade.
Exemplos:
- Presidente
- Tech Lead
- Delivery Manager
- Product Owner Dev

Role não deve ser a base principal do ACL.
Role responde: "qual função essa pessoa ocupa?"

### Overrides
Tabelas de override continuam sendo a camada de exceção.
Elas respondem: "o que precisa ser aberto ou fechado fora da regra padrão?"

## Diretriz de modelagem
### O que deve ficar em grupos
- identidade operacional
- estrutura da empresa/contrato
- áreas, times, liderança, atendimento, operação

### O que deve ficar em kits
- capabilities reaproveitáveis
- pacotes técnicos de acesso
- blocos de namespace/slugs por tipo de atuação

### O que deve ficar em roles
- cargo
- cadeira organizacional
- liderança e responsabilidade formal
- senioridade, quando relevante para workflows, não para ACL base

## Diretriz para admin
A área `pages/admin` deve ser a fonte de governança do modelo.
O fluxo recomendado é:
1. criar/editar grupo
2. vincular kits ao grupo
3. vincular usuários ao grupo
4. aplicar overrides só quando necessário

## Estado atual da implementação
Já existe backend PSR para grupos, kits, namespaces, contratos, diagnósticos e overrides.
A partir de 2026-04-13 também existe o vínculo explícito `grupo -> kit` via módulo `GroupKits`.

## Próximos passos recomendados
- evoluir `pages/admin/perms-grupos.php` para editar metadados completos do grupo (`slug`, `cor`, `icone`, `nivel`, `parent`, `descricao`)
- revisar grupos duplicados ou ambíguos (`empresa` vs `empresas`, `cliente` vs `clientes`, `corretor` vs `corretora`)
- reduzir o peso de `user_tipo -> kit` no ACL administrativo
- migrar resoluções administrativas para `grupo -> kit`
- manter `user_tipo -> kit` apenas como compatibilidade em áreas públicas, se ainda necessário