Fase 05 — Administração hierárquica · Sistema de Gestão de Estágios

Base: papéis por vínculo, Matriz de autorização e Perfis e responsabilidades por vínculo.

A estrutura de perfis e o contexto de vínculo existem. O provisionamento inicial ou a inclusão de Administrador do Sistema também pode ser feito por admin:create. A gestão global de campi tem backend, Policies, Form Requests, testes e páginas Livewire com Flux. O Administrador do Sistema também dispõe de telas para administrar contas e vínculos administrativos, consultar a auditoria administrativa e ver o histórico de e-mails associados a essas contas e vínculos. A interface local do Administrador do Campus, cursos, tipos de estágio e operações das jornadas de estágio continuam pendentes.

Policies e escopo

Disponibilizar o contexto único do vínculo ativo para Policies e Actions por ActiveAffiliationContext; completar os resolvedores de escopo por recurso junto de cada fluxo.
Criar CampusPolicy para consulta e gestão de campi, usando somente o vínculo ativo selecionado.
Criar UserPolicy e ampliar AffiliationPolicy para contas e vínculos administrativos, exigindo o Administrador do Sistema ativo selecionado.
Criar Policies para cursos, tipos, concedentes, estágios e documentos.
Revalidar vínculo selecionado, perfil e proteções administrativas dentro das transações de gestão de usuários e vínculos.
Manter as permissões de notificações em AffiliationPolicy; não há bypass global por Gate::before.
Criar testes positivos e negativos para operações de campus e administração de usuários/vínculos.
Criar testes positivos e negativos dos demais recursos por função.
Cobrir para cada AffiliationType as ações, limites, destinatários de notificação e consultas descritos em Perfis e responsabilidades por vínculo.
Restringir a gestão de usuários ao Administrador do Sistema, impedindo que o Administrador do Campus cadastre Administradores do Sistema.
Permitir ao Setor de Estágio cadastrar usuários permitidos, exceto administradores.
Aplicar as mesmas regras para edição e criação.

Administrador do Sistema

Definir e testar as operações globais permitidas antes de criar suas telas.
Implementar o backend de cadastro, edição, desativação e reativação de campi por CampusController, usando Campus::create(), $campus->update() e métodos de ciclo de vida do Model.
Exigir a senha atual em cada desativação; bloquear alterações no campus inativo e manter os vínculos existentes.
Criar as telas Livewire de listagem, cadastro, detalhes e edição de campi para o Administrador do Sistema.
Disponibilizar busca textual tolerante a erros por nome, filtro de situação, paginação e seleção de cidade por UF. CNPJ não faz parte dos atributos pesquisáveis do índice atual.
Confirmar desativação em modal com senha atual; confirmar reativação sem senha adicional.
Restringir rotas, navegação e requisições Livewire ao vínculo ativo de Administrador do Sistema.
Disponibilizar índice e detalhes de auditoria para alterações de campi, contas e vínculos administrativos, autorizados por Policy e pelo vínculo ativo selecionado.
Disponibilizar histórico de e-mails ligados a contas e vínculos administrativos, com conteúdo armazenado e tentativas de envio.
Administrar contas e vínculos de Administrador do Sistema e Administrador do Campus pela interface, com políticas e validação de escopo.
Reutilizar a criação transacional de conta/vínculo compartilhada com admin:create.
Enviar convites e avisos de novo vínculo pela interface, informando a função adicionada e deduplicando os endereços da conta e do vínculo.
Permitir editar nome, CPF e e-mail de login da conta; a mudança de e-mail envia os avisos aos endereços anterior e novo, como na alteração própria em Segurança.
Separar edição da conta da edição do vínculo; no vínculo, permitir somente e-mail e registro institucional, mantendo pessoa, tipo e campus fixos.
Desativar, reativar ou excluir vínculo e excluir conta quando não houver registros associados; as operações de encerramento enviam aviso e preservam as proteções de último Administrador do Sistema.

Telas de contas e vínculos administrativos

As rotas users.* são exclusivas do Administrador do Sistema com vínculo ativo selecionado. A listagem tem uma linha por conta com pelo menos um vínculo administrativo, inclusive desativado; busca nomes pelo Scout/Meilisearch e consulta CPF ou e-mail de login completos por igualdade, com 15 resultados por página. O painel administrativo, em contraste, conta todas as linhas de users.

O cadastro começa por consulta explícita do CPF. Para conta nova, um único e-mail é salvo na conta e no primeiro vínculo; é gerada uma senha aleatória desconhecida e enviado convite para definir senha. Para conta existente, nome, CPF e login são preservados e o campo único de e-mail vale para o novo vínculo. O aviso de novo vínculo identifica tipo, campus e registro institucional; se a conta já tiver outro registro, o formulário permite copiá-lo e ajustá-lo. Administrador do Campus exige campus ativo; Administrador do Sistema não recebe campus nem curso. Não se escolhe automaticamente o tipo de vínculo.

A edição da conta permite corrigir nome, CPF e endereço de login. A troca do login invalida tokens de redefinição pendentes e envia avisos aos endereços anterior e novo, seguindo o fluxo de Segurança. A edição do vínculo fica separada e limita-se ao e-mail e ao registro institucional; usuário, tipo e campus não mudam. Para mudar função ou campus, cadastra-se outro vínculo e encerra-se o anterior.

Uma pessoa não pode ter dois vínculos administrativos ativos com o mesmo tipo e campus. A duplicidade é verificada também ao reativar; vínculos históricos e duplicidades antigas não são apagados automaticamente. Vínculos de campus inativo ficam somente para leitura. Desativação de vínculo exige confirmação e senha atual, envia aviso aos e-mails da conta e do vínculo e não pode atingir o vínculo selecionado nem o último Administrador do Sistema ativo. Reativação exige confirmação, sem senha adicional, e obedece à regra de duplicidade. A exclusão de vínculo ou conta exige senha e só é permitida quando não há registros associados; também envia aviso. As alterações são transacionais, auditadas pelo vínculo administrador e não registram senhas.

As rotas audit. e email-logs. exigem o vínculo ativo e selecionado de Administrador do Sistema. Auditoria inclui campi, contas com vínculos administrativos e vínculos de Administrador do Sistema ou do Campus. O histórico de e-mails filtra pelas finalidades administrativas e pelo scope_context do registro afetado; não infere escopo a partir do destinatário ou do solicitante. Contatos externos podem aparecer quando o envio está ligado a conta ou vínculo dentro do escopo. A tela de e-mails mostra conteúdo persistido e tentativas, mas não oferece reenvio. Notificações operacionais, estágios, documentos, concedentes e outros vínculos ficam fora dessas consultas.

Painel administrativo

O dashboard detalhado é exibido somente quando o vínculo ativo selecionado é Administrador do Sistema e considera dados de todo o sistema: total de contas da tabela users, vínculos e campi (com totais ativos), vínculos por tipo, estágios por situação, documentos por situação e solicitações enviadas ou em análise. Os status de estágio e documento aparecem mesmo com valor zero. Outros perfis recebem o painel padrão.

Administrador do Campus

Limitar e testar a gestão local ao campus do vínculo ativo selecionado.
Permitir ao Administrador do Campus editar telefone, representante legal e dados do seguro do próprio campus; não permitir alterar nome, CNPJ, endereço, e-mail ou ciclo de ativação.
Criar a tela Livewire de edição permitida do campus.
Impedir acesso a campus alheio, criação de campus e alteração do ciclo de ativação pelo Administrador do Campus.
Administrar usuários e vínculos dentro do escopo.
Criar/editar cursos, dois coordenadores e tipos de estágio.
Impedir acesso a outro campus.

Interface de campi

Rotas GET: campuses.index, campuses.create, campuses.show e campuses.edit, com autenticação, contexto de vínculo e a permissão viewAdministration.
Páginas SFC em resources/views/pages/campuses, com layout administrativo e navegação pela sidebar. A dashboard conserva seu layout anterior.
Os campos compartilhados ficam no componente Livewire campuses.form-fields, reutilizado no cadastro e na edição. A digitação dos campos comuns usa wire:model sem .live; a consulta explícita do CNPJ sincroniza os valores, sem enviar uma requisição por tecla. Nome, CNPJ, telefone, e-mail, representante legal, seguradora, apólice e endereço são obrigatórios; o CEP é opcional. Os mesmos requisitos são aplicados no backend.
components/select é um select próprio com lista customizada, busca interna, teclado, seleção única, temas claro/escuro e validação do formulário. Usa Blade, Alpine e componentes Flux Free; não depende do Flux Pro. A pesquisa não permite cadastrar um valor livre. O componente aceita icon no controle e optionIcons por opção, com versões pesquisável e sem busca. O campo de pesquisa é integrado ao painel, sem contorno preto interno; o controle externo mantém foco discreto para teclado. A lista usa rolagem de 4 px no Chromium e thin no Firefox. A mensagem vazia e a opção ativa acompanham inclusões, remoções e alterações de opções feitas pelo Livewire; o observador é desconectado ao destruir o componente.
cities.select usa o enum BrazilianState para UF e registros da tabela cities para cidade. Não carrega opções inicialmente: pesquisa somente após 2 caracteres, com debounce de 500 ms e até 20 resultados pelo Scout/Meilisearch, filtrados por estado. Alterações do texto alimentam a busca; teclas sem mudança do valor não disparam pesquisa. Na edição, a cidade selecionada continua identificada no botão, mesmo fora dos resultados. Trocar UF limpa cidade e busca. A UF serve à interface e não é enviada como campo cadastral ao controller.
Busca e situação ficam na URL; os resultados são paginados em grupos de 15. Consultas carregam endereço e cidade antecipadamente e não alteram dados ou geram atividades.
Busca textual de campi usa Scout/Meilisearch pelo nome, com tolerância a erros. CNPJ não faz parte do índice pesquisável atual; a consulta por CNPJ formatado retorna vazio. Listagem sem texto e filtros estruturados podem usar Eloquent. Buscas textuais futuras sobre registros devem seguir Scout/Meilisearch e aplicar o escopo autorizado no índice; query() não substitui filtros do mecanismo. A filtragem local do select de UF opera apenas sobre as 27 opções fixas do enum.
Cadastro e edição usam formulários HTTP com CSRF, erros por campo, preservação dos dados preenchidos e indicação de envio. As gravações continuam nas transações do CampusController, com a validação e a auditoria existentes.
Operações do Administrador do Sistema retornam aos detalhes do campus com mensagem de resultado. A atualização local pelo backend do Administrador do Campus continua retornando ao painel, pois sua interface está pendente.
Campus desativado mostra a data e o aviso de somente leitura, sem edição. O modal de desativação reabre após erro de senha e não preserva a senha informada. As identidades dos campi nos componentes são bloqueadas contra alteração pelo cliente; a permissão é revalidada a cada requisição Livewire.
CampusInterfaceTest cobre renderização, acesso por perfil e vínculo, filtros, paginação, cidade por UF, erros de formulário, modal, congelamento e revalidação de permissão.

Índices e integrações

Os índices de Campus e City são configurados em config/scout.php. A sincronização Eloquent ocorre por fila após commit. Execute ./vendor/bin/sail artisan scout:sync-index-settings e importe registros existentes com scout:import 'App\Models\Campus' e scout:import 'App\Models\City'. Mantenha um worker de fila ativo; o Meilisearch também processa suas tarefas de indexação de modo assíncrono. Configure SCOUT_PREFIX ao compartilhar o serviço entre ambientes.

A suíte geral usa o driver collection para não alterar índices do desenvolvimento. CampusSearchTest usa o Meilisearch real, índices temporários com prefixo aleatório e limpeza após cada teste; verifica busca, filtros, criação, edição, transições, exclusão, fila e rollback. O serviço Meilisearch do Sail é necessário para esses testes.

O botão Consultar CNPJ, nos formulários de cadastro e edição, usa BrasilApiCompanyLookup para consultar cnpj/v1/{cnpj} na BrasilAPI. Valida e normaliza o CNPJ antes da chamada, com conexão limitada a 3 segundos e resposta a 10 segundos. Preenche razão social como nome, telefone, e-mail e endereço quando disponíveis; resolve a cidade por ibge_code e UF na tabela local, sem busca textual nem criação de cidades. Uma consulta bem-sucedida reinicializa o seletor com essa cidade; quando não houver correspondência, limpa a seleção anterior e solicita UF/cidade manualmente. Campos ausentes na resposta não apagam valores digitados. Os dados permanecem editáveis e só são gravados pelo envio normal ao controller, com Form Requests e auditoria. A consulta em si não grava dados nem atividades. Falhas, CNPJ não encontrado e respostas inválidas exibem erro e preservam o formulário. A permissão e o estado do campus são revalidados em cada requisição. Representante legal e seguro continuam sob responsabilidade de quem cadastra; não são inferidos do quadro de sócios. Consulta independente por CEP permanece pendente.

Setor de Estágio

Implementar autorização e Actions de gestão dos cadastros e análises antes de criar as telas operacionais.
Administrar templates DOCX e versões.
Administrar concedentes e solicitações pendentes no escopo do campus; cadastros e aprovações devem preservar essa associação mesmo quando CPF/CNPJ se repetirem.
Administrar a importação do calendário nacional/estadual e o cadastro manual de feriados municipais.
Analisar estágios enviados.
Analisar solicitações de supervisor/concedente.
Validar documentos, avaliações, pendências e liberação.
Consultar o calendário aplicável e registrar exceções por estágio, sem alterar o calendário global.

Próxima fase

Fase 06 — Documentos