Pular para o conteúdo principal

Feature: Configuração de Colunas Visíveis

Introdução ao documento​

Este documento descreve a funcionalidade de configuração de colunas visíveis para controle de acesso a dados sensíveis.

Versionamento​

  • Versão do documento: 1.0.0
  • Última atualização: 2026-03-09
  • Responsável: Marivaldo Vinicius

Referencial teórico​

Visão geral​

A feature de colunas visíveis permite controlar quais colunas de dados podem ser visualizadas por usuários com role Facilitador_Limitado. Sistema armazena configuração única (singleton) que define lista de colunas permitidas. Por padrão, email é oculto para facilitadores limitados.

Atores envolvidos​

  • Administrador Geral: Configura quais colunas são visíveis
  • Facilitador Limitado: Visualiza apenas colunas permitidas
  • Sistema: Aplica filtro de colunas baseado na configuração

Pré-condições​

  • Permissão Administração_Geral para configurar colunas
  • Tabela visible_columns_config criada
  • Role Facilitador_Limitado configurada no sistema
  • Frontend implementa lógica de filtro de colunas

Fluxo principal​

Configuração de Colunas​

  1. Administrador acessa interface

    • Acessa página de configuração de colunas (via admin panel)
    • Visualiza configuração atual ou null se não configurado

  2. Definição de colunas permitidas

    • Administrador seleciona colunas que devem ser visíveis
    • Sistema valida que columns é array de strings
    • Salva configuração na tabela visible_columns_config

  3. Aplicação da configuração

    • Frontend consulta /api/v1/colunas para obter lista permitida
    • Filtra colunas exibidas baseado na configuração
    • Colunas não permitidas são ocultadas da visualização

Visualização com Restrição​

  1. Usuário com role limitada acessa dados

    • Frontend identifica role do usuário
    • Se Facilitador_Limitado, consulta configuração de colunas

  2. Filtro de colunas

    • Frontend aplica filtro removendo colunas não permitidas
    • Email é sempre oculto por padrão (mesmo se não configurado)
    • Apenas colunas na lista são exibidas

Fluxos alternativos​

Configuração não existe​

  • Se nenhuma configuração foi salva, API retorna columns: null
  • Frontend aplica configuração padrão (todas exceto email)
  • Sistema funciona normalmente mesmo sem configuração explícita

Atualização de configuração​

  • PUT e POST têm mesmo comportamento (upsert)
  • Se configuração existe, é atualizada
  • Se não existe, é criada
  • Apenas um registro é mantido (singleton)

Validação de dados​

  • Se columns não é array, sistema retorna erro 422
  • Se array contém valores não-string, validação falha
  • Mensagem de erro detalhada é retornada

Regras de negócio​

  1. Configuração única: Apenas uma configuração é mantida (singleton)
  2. Email sempre oculto: Email nunca é exibido para facilitadores limitados, mesmo se na lista
  3. Validação de array: Colunas devem ser array de strings
  4. Aplicação no frontend: Filtro é aplicado no frontend, não no backend
  5. Colunas padrão: Se não configurado, todas exceto email são permitidas (conforme migration)

Estados possíveis​

  • Configurado: Lista de colunas definida e ativa
  • Não configurado: Nenhuma configuração salva (usa padrão)
  • Erro de validação: Dados inválidos, configuração não salva

Endpoints envolvidos​

  • GET /api/v1/colunas - Retorna configuração atual

    • Response: { success: boolean, columns: array|null }

  • POST /api/v1/colunas - Salva ou atualiza configuração

    • Request body: { columns: string[] }
    • Response: { success: boolean, message: string, columns: array }

  • PUT /api/v1/colunas - Atualiza configuração (mesmo comportamento do POST)

    • Request body: { columns: string[] }
    • Response: { success: boolean, message: string, columns: array }

Admin Panel​

  • GET /admin/colunas - Interface de configuração (requer permissão)

Dados afetados​

  • Tabela visible_columns_config: Armazena configuração única
    • Campo columns: Array JSON com lista de colunas permitidas
    • Apenas um registro é mantido (singleton)

Colunas padrão​

Conforme migration inicial, colunas permitidas por padrão (exceto email):

  • name, phone, city, uf, progress, pcd, cnpj, companyName, classSchedule, cycleName, is_enroll_canceled, cancel_description, ch_percentual, segment, companySize, aliName