Comercial - Ativacao de Pipeline, Grupo Empresarial e Usuarios

Objetivo

Este documento consolida a regra de negocio planejada para a etapa de ativacao da pipeline comercial quando a Pessoa/CNPJ aprovada precisa ser vinculada a um grupo empresarial e, opcionalmente, receber um usuario administrador inicial.

O texto foi escrito para orientar produto, frontend, backend e suporte. Ele descreve decisoes tomadas, motivacao, riscos, gaps conhecidos e exemplos de uso. Nem tudo aqui representa comportamento ja implementado no codigo atual.

Problema Que Estamos Resolvendo

Antes, a ativacao operacional depois da criacao da Pessoa no CRM dependia de um fluxo manual em telas de autorizacao:

O novo fluxo quer levar parte desse trabalho para o funil comercial, principalmente no funil 6 - Ativacao, para reduzir retrabalho e criar o primeiro acesso do cliente/parceiro com menos passos manuais.

O ponto critico e que a pipeline pertence ao dominio Comercial, mas criar usuarios, permissoes e grupos impacta o dominio de Autorizacao. Por isso, a ativacao precisa ser simples para o operador, mas explicita e segura para o sistema.

Glossario

Termo Significado neste documento
Pessoa/CNPJ Registro da Pessoa juridica no CRM que representa posto, transportadora ou empresa.
Pipeline Card comercial vinculado a uma Pessoa, com funil comercial e tipo proprio.
Funil 6 - Ativacao Etapa em que o parceiro aprovado passa a ser preparado para acesso operacional.
Grupo comercial Agrupamento existente no CRM/Pessoa, usado como informacao comercial de pertencimento.
Grupo empresarial Agrupamento usado pelo dominio de Autorizacao para organizar Pessoas/CNPJs e apoiar gestao de usuarios.
Admin inicial Primeiro usuario criado a partir da ativacao comercial para a Pessoa/CNPJ atual.
Admin operacional Usuario que possui permissoes de gestao de usuarios no contexto de uma Pessoa. Nao e um perfil fixo separado.
Responsavel inicial protegido Admin inicial criado pela ativacao e protegido contra remocao por usuarios operacionais.
Contexto ativo Pessoa operacional selecionada na sessao do usuario, por exemplo um posto ou uma transportadora.
APROMS Time interno com acesso administrativo para corrigir, liberar ou revisar acessos.

Principios Decididos

Decisao Central

O funil de ativacao deve funcionar como um facilitador controlado:

Pipeline no funil 6
        |
        v
Resolver grupo empresarial da Pessoa/CNPJ atual
        |
        v
Opcionalmente criar admin inicial para a Pessoa/CNPJ atual
        |
        v
Aplicar permissoes padrao somente nessa Pessoa/CNPJ
        |
        v
Enviar link de definicao de senha
        |
        v
Permitir avanco para treinamento sem esperar primeiro login

Grupo Comercial vs Grupo Empresarial

Grupo Comercial

O grupo comercial pertence ao contexto de CRM/Pessoa. Ele representa uma informacao comercial: uma Pessoa pode estar associada a um agrupamento conhecido pelo Comercial.

Exemplo:

Grupo comercial: GRUPO ZAFALON
Pessoas no CRM:
- Posto Zafalon A
- Posto Zafalon B
- Posto Zafalon C

Grupo Empresarial

O grupo empresarial pertence ao contexto de Autorizacao. Ele organiza Pessoas/CNPJs para apoiar escopo, selecao e gestao de usuarios.

Exemplo:

Grupo empresarial: GRUPO ZAFALON
Pessoas vinculadas:
- Posto Zafalon A
- Posto Zafalon B

Regra De Integracao

O grupo comercial pode sugerir o grupo empresarial na ativacao, mas nao deve obrigar a escolha.

Fluxo recomendado:

Pessoa da pipeline possui grupo comercial?
        |
        +-- Sim: sugerir grupo empresarial correspondente, se existir.
        |
        +-- Nao: permitir buscar grupo empresarial existente ou criar novo.

Por Que Nao Unificar Automaticamente

Regra Do Grupo Empresarial

Pertencer a um grupo empresarial nao concede acesso automaticamente.

O grupo empresarial define o universo organizado de Pessoas/CNPJs relacionadas. O acesso real depende de permissoes atribuidas por Pessoa.

Exemplo seguro:

Grupo empresarial: GRUPO ZAFALON
Pessoas:
- Posto A
- Posto B

Usuario Joao:
- permissao no Posto A: sim
- permissao no Posto B: nao

Resultado:
- Joao acessa Posto A.
- Joao nao acessa Posto B.

Fluxo Da Ativacao

Entrada

A ativacao parte de uma pipeline ativa no funil 6 - Ativacao.

A pipeline deve estar vinculada a uma Pessoa/CNPJ atual. Essa Pessoa pode ser posto ou transportadora conforme o tipo da pipeline.

Passos

  1. Operador abre a tela de ativacao da pipeline.
  2. Sistema exibe a Pessoa/CNPJ da pipeline.
  3. Sistema sugere grupo empresarial a partir do grupo comercial, quando possivel.
  4. Operador escolhe grupo empresarial existente ou cria novo grupo.
  5. Sistema vincula a Pessoa/CNPJ atual ao grupo empresarial escolhido.
  6. Sistema mostra se ja existem admins em outras Pessoas do mesmo grupo, apenas como alerta/informacao.
  7. Operador decide se cria admin inicial para a Pessoa/CNPJ atual.
  8. Se criar admin, informa dados do usuario e confirma permissao padrao.
  9. Se nao criar admin, informa motivo obrigatorio.
  10. Sistema registra a ativacao e permite seguir o funil.

Diagrama

[Diagram]

Criacao Do Admin Inicial

Quem E O Admin Inicial

O admin inicial e o primeiro usuario criado pela ativacao comercial para a Pessoa/CNPJ da pipeline.

Ele representa o contato responsavel inicial do parceiro para acesso ao sistema. Pode ser dono, gestor ou administrador indicado pelo cliente.

Dados Minimos

Campos esperados:

O username deve ser unico. Pode ter formato livre aceito pelo sistema, por exemplo vinicius.willian ou um documento sem mascara, desde que seja unico.

Regra De Username

O username e o identificador unico operacional do usuario.

Na ativacao:

Regra De E-mail Na Ativacao

Na criacao do admin inicial pela ativacao comercial, o e-mail deve ser unico.

Motivo:

Diferenca Para Gestao Normal De Usuarios

Na gestao normal de usuarios, o e-mail pode repetir.

Exemplo aceito fora da ativacao:

Usuario 1:
- username: frentista.01
- e-mail: dono@posto.com.br

Usuario 2:
- username: caixa.01
- e-mail: dono@posto.com.br

Motivo:

Gap Da Diferenca De E-mail

A diferenca entre ativacao e gestao normal precisa ser explicada na tela.

Risco:

Mitigacao:

Permissoes Do Admin Inicial

O admin inicial recebe um grupo de permissao padrao conforme o tipo operacional da Pessoa.

Regra:

Exemplo:

Grupo empresarial: GRUPO ZAFALON
Pessoas no grupo:
- Posto A
- Posto B

Pipeline atual:
- Posto B

Admin inicial criado:
- Carlos

Acesso de Carlos:
- Posto A: nao
- Posto B: sim, com Admin Posto

Admin Operacional

Admin operacional nao deve ser um novo nivel fixo neste momento.

A regra recomendada e derivar o comportamento de admin a partir das permissoes efetivas no contexto.

Definicao:

Usuario e admin operacional de uma Pessoa quando possui permissoes de gestao de usuarios naquela Pessoa.

Exemplo:

Maria no Posto A:
- usuarios.criar: sim
- usuarios.editar: sim
- usuarios.permissoes: sim

Resultado:
- Maria e admin operacional no Posto A.

Por Que Nao Criar Flag admin_operacional Agora

Criar uma flag separada parece simples, mas gera duplicidade de regra.

Riscos:

Decisao:

Responsavel Inicial Protegido

O admin inicial criado pela ativacao deve ser registrado como responsavel inicial protegido da Pessoa/CNPJ da pipeline.

Essa protecao nao e uma permissao adicional. Ela e uma regra de governanca para evitar que usuarios operacionais removam o primeiro responsavel criado no onboarding.

Regra

Por Que A Protecao E Necessaria

Sem protecao, existe um buraco operacional:

1. Joao e criado pelo Comercial como primeiro admin do Posto A.
2. Joao cria Maria com permissoes de gestao de usuarios.
3. Maria cria Pedro com permissoes de gestao de usuarios.
4. Joao deixa de ser o ultimo admin.
5. Maria remove Joao.

A regra nao remover o ultimo admin so garante continuidade. Ela nao protege o responsavel inicial contra substituicao indevida.

Decisao

Usar duas protecoes:

Regra De Ultimo Admin

Mesmo com responsavel inicial protegido, o sistema tambem deve impedir que uma Pessoa/CNPJ fique sem admin operacional.

Regra:

Nao pode remover ou desativar o ultimo usuario com permissoes de gestao de usuarios naquela Pessoa.

Exemplo:

Posto A tem apenas Joao como admin operacional.
Maria tenta remover Joao.
Sistema bloqueia.

Exemplo com dois admins:

Posto A tem Joao e Maria como admins operacionais.
Maria tenta remover Joao.

Se Joao e responsavel inicial protegido:
- bloqueia para Maria.

Se Joao nao e protegido:
- pode permitir, desde que Maria tenha permissao e o Posto A continue com admin.

Fluxo Sem Admin Inicial

Criar admin inicial e opcional.

Quando o operador escolhe nao criar admin, o sistema deve exigir motivo.

Motivos possiveis:

Regra:

Ativacao pode concluir sem admin, mas motivo e obrigatorio.

Gap:

Mitigacao:

Segunda Empresa No Mesmo Grupo

Cenario

Dia 1:
Pipeline ativa Posto A.
Grupo empresarial: GRUPO ZAFALON.
Admin inicial: Joao.
Joao tem acesso somente ao Posto A.

Dia 30:
Pipeline ativa Posto B.
Posto B entra no GRUPO ZAFALON.

Regra

Joao nao ganha acesso automatico ao Posto B.

A ativacao do Posto B deve:

Diagrama

[Diagram]

Gestao De Usuarios Depois Da Ativacao

Regra De Contexto Para Posto E Transportadora

Na visao operacional de posto e transportadora, a listagem de usuarios deve ser filtrada pelo contexto ativo.

Exemplo:

Contexto ativo: Posto A
Listagem mostra usuarios com permissao no Posto A.

Contexto ativo: Posto B
Listagem mostra usuarios com permissao no Posto B.

Motivo:

Visao APROMS

Usuarios internos da APROMS podem ter visao administrativa mais ampla.

Regra recomendada:

Criacao De Usuarios Por Admin Operacional

Um admin operacional pode criar usuarios dentro do escopo onde ele proprio possui permissoes de gestao de usuarios.

Regra recomendada:

Admin pode criar/liberar usuarios nas Pessoas em que ele ja possui gestao de usuarios.
Estar no mesmo grupo empresarial nao basta.

Exemplos:

Joao e admin no Posto A somente.
Joao pode criar usuarios para Posto A.
Joao nao pode criar usuarios para Posto B.
Maria e admin no Posto A e no Posto B.
Maria pode criar usuarios para Posto A e Posto B.

Concessao De Grupos De Permissao

O admin operacional pode conceder grupos de permissao compativeis com o tipo da Pessoa e dentro do escopo permitido.

Isso pode incluir grupos como Admin Posto ou Admin Transportadora, desde que:

Status De Convite E Primeiro Acesso

A pipeline nao deve depender do primeiro login para avancar.

Regra:

Status sugeridos:

Campo Valores sugeridos
convite_status nao_aplicavel, pendente, enviado, expirado, reenviado, falhou
primeiro_acesso_status nao_realizado, realizado
ativacao_status pendente, concluida_com_admin, concluida_sem_admin

Gap:

Recomendacao:

Registro De Ativacao

Para rastreabilidade, a ativacao deve gerar ou atualizar um registro proprio.

Campos conceituais sugeridos:

pipeline_uuid
pessoa_uuid
grupo_empresarial_uuid
admin_inicial_usuario_uuid
admin_inicial_protegido
motivo_sem_admin
convite_status
primeiro_acesso_status
ativado_por_usuario_uuid
ativado_em
observacoes

Esse registro responde perguntas importantes:

Casos De Uso

Caso 1 - Primeira Empresa Do Grupo Com Admin

Cenario:
- Posto A chega no funil 6.
- Nao existe grupo empresarial ZAFALON.
- Operador cria grupo empresarial ZAFALON.
- Operador cria Joao como admin inicial.

Resultado:
- Posto A vinculado ao grupo ZAFALON.
- Joao criado com Admin Posto somente no Posto A.
- Joao recebe link de definicao de senha.
- Joao fica como responsavel inicial protegido do Posto A.
- Pipeline pode seguir para treinamento.

Caso 2 - Segunda Empresa Do Grupo Sem Liberar Admin Antigo

Cenario:
- Posto B chega no funil 6.
- Grupo ZAFALON ja existe.
- Joao e admin do Posto A.

Resultado:
- Posto B e vinculado ao grupo ZAFALON.
- Joao nao ganha acesso ao Posto B.
- Tela alerta que ja existem admins no grupo, mas sem acesso automatico.
- Operador pode criar novo admin para Posto B ou concluir sem admin com motivo.

Caso 3 - Ativacao Sem Admin

Cenario:
- Transportadora C chega no funil 6.
- Operador seleciona grupo empresarial existente.
- Cliente ainda nao informou responsavel.

Resultado:
- Transportadora C e vinculada ao grupo.
- Nenhum usuario e criado.
- Motivo sem admin e obrigatorio.
- Pipeline pode seguir, mas fica rastreavel que a ativacao nao gerou admin.

Caso 4 - Username Duplicado Na Ativacao

Cenario:
- Operador tenta criar admin inicial com username joao.silva.
- ja existe usuario com username joao.silva.

Resultado:
- Sistema bloqueia criacao pela ativacao.
- Sistema orienta resolver pela gestao de usuarios APROMS.
- Nao reutiliza usuario automaticamente neste fluxo.

Caso 5 - E-mail Repetido Na Gestao Normal

Cenario:
- Admin do Posto A cria frentista.01 e caixa.01.
- Ambos usam o e-mail dono@posto.com.br.

Resultado:
- Permitido na gestao normal.
- Username continua unico para cada usuario.
- Recuperacao de senha pode ir para o mesmo e-mail.

Caso 6 - Tentativa De Remover Responsavel Inicial

Cenario:
- Joao foi criado pela ativacao como responsavel inicial protegido do Posto A.
- Joao cria Maria com permissoes de gestao de usuarios no Posto A.
- Maria tenta remover Joao.

Resultado:
- Sistema bloqueia.
- Motivo: Joao e responsavel inicial protegido.
- APROMS pode substituir ou remover a protecao, se necessario.

Gaps E Decisoes Futuras

Admin De Grupo

Nao sera criado agora um conceito forte de admin do grupo.

Motivo:

Possivel evolucao:

Admin Operacional Explicito

Nao criar agora uma flag admin_operacional como fonte de verdade.

Possivel evolucao:

Filtros Administrativos APROMS

Filtros avancados podem ser evoluidos depois.

Ideias:

Persistencia Do Registro De Ativacao

Ainda precisa ser desenhada tecnicamente.

Decisao pendente:

Recomendacao:

Reenvio De Convite

Ainda precisa definir:

Usuario Existente

Neste primeiro desenho, usuario existente bloqueia a criacao do admin inicial pela ativacao.

Possivel evolucao:

Riscos Do Botao Unico De Ativacao

Um botao unico pode ser bom para produtividade, mas ruim se esconder decisoes importantes.

Riscos:

Mitigacao recomendada:

Resumo visual recomendado antes de confirmar:

Pessoa/CNPJ: Posto Zafalon A
Grupo empresarial: GRUPO ZAFALON
Admin inicial: Joao Silva
Username: joao.silva
E-mail: joao@zafalon.com.br
Permissao inicial: Admin Posto
Acesso liberado: somente Posto Zafalon A
Convite: enviar link de definicao de senha
Aviso: outros admins do grupo nao receberao acesso automatico

Regras Finais Consolidadas