Guia de Operacao para Usuarios

AI Admin – Guia de Onboarding e Operacao de Usuarios

Este documento foi escrito para equipes de atendimento, operacao, comercial e administracao.

O objetivo e explicar, de forma simples, como um usuario entra no sistema, como ele e aprovado, quais papeis pode receber e como usar os principais fluxos de negocio.

Este guia evita detalhes tecnicos desnecessarios. Quando houver uma regra que depende mais de processo interno do que de automacao do plugin, isso e indicado explicitamente.

Para Quem Serve Este Guia

Use este documento para responder:

como um usuario e criado
como um usuario e aprovado
como um usuario recebe um ou mais papeis AI Admin
o que cada papel faz
como funciona newsletter
como o usuario acessa e edita seu perfil/empresa
como o usuario gerencia usuarios vinculados
como o usuario trabalha com produtos
como o usuario envia e acompanha cotacoes
como o usuario contrata ou gerencia anuncios
qual a diferenca entre papel do WordPress e papel AI Admin

Conceito Central: Papel do WordPress x Papel do AI Admin

O sistema trabalha com duas camadas diferentes de permissao.

1. Papel do WordPress

E o papel padrao do WordPress.

Exemplos:

administrator
editor
outros papeis registrados no WordPress

Esse papel controla o acesso geral a plataforma, por exemplo:

acesso ao /wp-admin
acesso a menus administrativos
possibilidade de editar usuarios
acesso a paginas internas do plugin

2. Papel do AI Admin

E o papel de negocio do sistema.

Exemplos:

ai_client
ai_advertiser
ai_contact
ai_fisica
ai_juridica

Esse papel controla o que o usuario faz dentro da operacao do portal, por exemplo:

cotacoes
anuncios
newsletter
perfil de empresa
usuarios vinculados
acesso a fornecedores

Regra pratica

Papel do WordPress = nivel de acesso a plataforma.

Papel do AI Admin = funcao de negocio do usuario.

Hoje o modelo recomendado e:

o usuario tem um papel WordPress
o usuario pode ter multiplos papeis AI Admin

Caminhos de Entrada de Usuario

Hoje existem dois caminhos principais.

Caminho 1: Administrador cria o usuario no WordPress

Esse e o caminho mais controlado e mais seguro.

Onde fazer

Usuarios > Adicionar novo
ou editar um usuario existente em Usuarios > Todos os usuarios
ou pela pagina do plugin AI Admin > Usuarios

Fluxo recomendado

Criar o usuario no WordPress.
Definir o papel WordPress.
Abrir a edicao do usuario.
Na secao de AI Admin, marcar um ou mais papeis AI Admin.
Preencher os campos de vinculacao da empresa, principalmente:

ai_client_id
ai_company_name
demais dados cadastrais necessarios

Salvar.
Enviar ou confirmar as credenciais de acesso.

Caminho 2: Usuario da empresa cria outro usuario dentro do perfil da empresa

Esse fluxo e usado para criar usuarios vinculados a mesma empresa/cliente.

Onde fazer

pagina de perfil da empresa
aba Users

Fluxo atual

O usuario entra no perfil da empresa.
Vai para a aba Users.
Clica em Add New User.
Preenche usuario, email e dados basicos.
Seleciona um ou mais papeis AI Admin.
O sistema cria o novo usuario e o vincula a mesma empresa/cliente.

Observacao importante

Esse fluxo agora aceita multiplos papeis AI Admin, mas continua limitado a papeis AI Admin permitidos pelo plugin. Ele nao deve ser usado para conceder papeis administrativos arbitrarios do WordPress.

Como Funciona a Aprovacao

O que esta claramente automatizado

O plugin ja suporta claramente:

criacao de usuario
atribuicao de papeis AI Admin
vinculacao a empresa/cliente
acesso condicionado por papeis e vinculacao

O que ainda deve ser tratado como processo operacional

Um fluxo completo de aprovacao automatica para cadastro publico nao esta claramente implementado como processo fim a fim no plugin.

Existe uma configuracao relacionada a cadastro:

AI Admin > Settings
opcao Allow Client Registration

Mas, pela leitura atual do codigo, a forma mais segura de documentar o processo e:

aprovacao ainda deve ser tratada como processo administrativo
um responsavel valida a empresa e o contato
depois define os papeis corretos
depois confirma o vinculo do usuario com a empresa

Processo recomendado de aprovacao

Confirmar identidade do contato e da empresa.
Confirmar se o usuario sera pessoa fisica ou juridica.
Confirmar se ele tambem atuara como contato, anunciante ou gestor.
Criar ou revisar a conta WordPress.
Vincular o usuario ao cliente/empresa correto.
Atribuir um ou mais papeis AI Admin.
Confirmar se o usuario deve acessar o WordPress admin ou apenas o fluxo operacional/perfil.
Enviar instrucoes de acesso.

Papeis AI Admin e o Que Cada Um Faz

Abaixo esta a leitura operacional dos papeis hoje definidos no plugin.

`ai_client`

Uso tipico:

cliente padrao

Permissoes principais:

visualizar cotacoes
criar cotacoes
editar as proprias cotacoes
visualizar o proprio perfil
editar o proprio perfil
visualizar fornecedores
receber/assinar newsletter
participar de votacoes e enquetes

`ai_advertiser`

Uso tipico:

anunciante
conta de marketing

Permissoes principais:

visualizar estatisticas de anuncios
gerenciar anuncios proprios
criar anuncios
editar anuncios proprios
visualizar relatorios de anuncios
visualizar fornecedores
visualizar revistas
receber/assinar newsletter

`ai_contact`

Uso tipico:

contato da empresa
pessoa responsavel por manter dados e usuarios vinculados

Permissoes principais:

visualizar dados do cliente
editar dados do cliente
gerenciar usuarios vinculados
visualizar cotacoes do cliente
criar cotacoes para o cliente
visualizar fornecedores
receber/assinar newsletter

`ai_fisica`

Uso tipico:

conta individual

Permissoes principais:

fluxo semelhante ao de cliente
criacao e acompanhamento de cotacoes
acesso ao proprio perfil
acesso a fornecedores
newsletter
votacoes e enquetes

`ai_juridica`

Uso tipico:

conta principal de empresa
conta corporativa

Permissoes principais:

criar e acompanhar cotacoes
gerenciar usuarios da empresa
acessar perfil da empresa
editar perfil da empresa
criar anuncios
gerenciar anuncios da empresa
acessar fornecedores
acessar revistas
newsletter
votacoes e enquetes
publicar vagas

Como Funciona o Modelo de Multi-Papeis

Agora o sistema permite multiplos papeis AI Admin para o mesmo usuario.

Exemplos validos:

ai_contact + ai_advertiser
ai_juridica + ai_advertiser
ai_client + ai_contact

Quando usar multiplos papeis

Use multiplos papeis quando o usuario acumula funcoes de negocio.

Exemplo:

um contato comercial que tambem precisa contratar anuncios
um usuario da empresa que administra usuarios e tambem acompanha cotacoes

Como o Administrador Atribui Papeis

No editor de usuario do WordPress

Caminho:

Usuarios > Todos os usuarios > Editar

Na tela de edicao ha dois pontos diferentes:

1. Select-box canonico do WordPress

Esse campo continua existindo.

Use esse campo para definir o papel do WordPress, isto e:

nivel de acesso a plataforma
menus administrativos
comportamento geral do WordPress

2. Secao AI Admin com checkboxes

Essa secao deve ser usada para definir as funcoes de negocio do usuario.

Use essa secao para:

marcar um ou mais papeis AI Admin
combinar perfis operacionais
ajustar o comportamento do usuario dentro do AI Admin

Recomendacao operacional

Nao use o campo de papel WordPress para tentar representar sozinho a funcao comercial do usuario.

A pratica correta e:

WordPress role para acesso de plataforma
AI Admin roles para acesso de negocio

Como o Usuario Recebe Newsletter

O acesso a newsletter esta ligado a capacidades presentes em varios papeis AI Admin.

Na pratica, os papeis abaixo ja contemplam newsletter:

ai_client
ai_advertiser
ai_contact
ai_fisica
ai_juridica

O que precisa existir para funcionar

O usuario precisa estar corretamente criado e com um papel AI Admin apropriado.
A pagina/shortcode de newsletter precisa estar configurada.
O provedor de envio precisa estar configurado em:

AI Admin > Settings

Como explicar para o time

Receber newsletter depende de:

permissao de negocio do usuario
configuracao operacional da newsletter
fluxo de assinaturas/listas usado pelo portal

Como o Usuario Registra e Edita Seu Perfil ou Perfil da Empresa

O sistema trabalha com dois niveis de informacao.

1. Dados do usuario

Exemplos:

nome
sobrenome
email
username
telefone
endereco

2. Dados da empresa/cliente

Exemplos:

nome da empresa
descricao
logo
website
telefone
endereco
status da pagina

Onde o usuario faz isso

Fluxo principal:

login
redirecionamento para o perfil/area da empresa
navegacao pelas abas do perfil

Abas principais hoje:

Profile Data
Users
Products
Quotations
Opportunities

Perfil da empresa e pagina do cliente

Ha dois conceitos proximos:

perfil operacional da empresa
pagina publica/institucional do cliente

A pagina do cliente usa o CPT ai_clients e pode ser editada com Gutenberg quando o usuario esta corretamente vinculado ao cliente e possui acesso adequado.

Caminhos administrativos relevantes

AI Admin > Usuarios
Clients
Usuarios > Todos os usuarios

Como Produtos Sao Vinculados

Pelo desenho atual do plugin, produtos fazem parte do contexto da empresa/cliente.

Na pratica, para o usuario operar produtos:

ele precisa estar vinculado ao cliente/empresa correto
precisa acessar a area de perfil da empresa
a aba Products precisa refletir os produtos vinculados ao cliente

O que a equipe deve validar

se o usuario esta vinculado ao cliente certo
se o cliente certo tem produtos cadastrados
se o usuario tem o papel de negocio adequado para aquele fluxo

Como Cotacoes Funcionam

Cotacao e um dos fluxos centrais do sistema.

Fluxo operacional resumido

O usuario acessa o formulario ou a area de cotacoes.
Seleciona produtos/ingredientes ou parte de um contexto de fornecedor.
Envia a solicitacao.
A cotacao fica vinculada ao cliente/empresa.
Usuarios com papeis adequados acompanham o andamento.

Papeis normalmente envolvidos

ai_client
ai_contact
ai_fisica
ai_juridica

O que o time deve conferir quando der problema

se o usuario tem papel AI Admin compativel
se o usuario esta vinculado ao cliente certo
se o fluxo esperado e pessoal ou corporativo

Como Anuncios Funcionam

O modulo de anuncios esta ligado ao cadastro de midias, categorias, exibicao e eventualmente a produtos/planos do WooCommerce.

Fluxo operacional resumido

O administrador ou time interno prepara categorias e midias.
O usuario recebe papel compatível, normalmente:

ai_advertiser
ou ai_juridica em alguns cenarios

O usuario/empresa e associado ao contexto comercial correto.
Os anuncios podem ser contratados, gerenciados ou entregues conforme o modelo comercial vigente.
A exibicao e o rastreamento acontecem pelos componentes do modulo de ads.

Onde a equipe costuma operar

AI Admin > Ads Management
produtos/planos do WooCommerce quando o contrato depende de plano

Como Planos e Assinaturas Entram no Processo

Planos sao tratados em documentacao separada, mas impactam diretamente:

newsletter
anuncios
cotacoes
servicos contratados

Onde operar

AI Admin > Plans

Se o negocio do cliente depende de assinatura, o time deve validar:

plano contratado
status da assinatura
produtos/beneficios incluidos

Diferenca Entre Aprovar o Usuario e Habilitar a Operacao

Esses dois passos nao sao a mesma coisa.

Aprovar o usuario

Significa:

validar a pessoa
validar a empresa
permitir que a conta exista e acesse o sistema

Habilitar a operacao

Significa:

vincular ao cliente correto
atribuir um ou mais papeis AI Admin
configurar campos da empresa
garantir que o usuario veja os menus e as abas certas
garantir que o contrato/plano/comercial esteja coerente

Checklist Recomendado Para Novo Usuario

Sempre que um novo usuario entrar:

Confirmar nome, email e empresa.
Confirmar se e pessoa fisica ou juridica.
Confirmar se ele sera:

contato
anunciante
usuario corporativo
usuario individual

Criar a conta WordPress.
Definir o papel WordPress.
Definir um ou mais papeis AI Admin.
Vincular ai_client_id quando aplicavel.
Preencher ai_company_name quando aplicavel.
Testar login.
Testar acesso ao perfil/empresa.
Testar se as abas corretas aparecem.
Testar, se necessario:

criacao de usuario vinculado
acesso a cotacoes
visualizacao de produtos
fluxo de anuncios
newsletter

Checklist de Teste Para Staging

Ao validar em homologacao/staging, testar pelo menos:

Usuario corporativo

login
acesso ao perfil da empresa
visualizacao do papel no cabecalho do perfil
visualizacao de multiplos papeis na interface
aba Users
criacao de usuario vinculado
aba Products
aba Quotations

Usuario anunciante

login
visualizacao dos papeis corretos
acesso ao que for esperado para anuncios

Usuario com multiplos papeis

Exemplo:

ai_contact + ai_advertiser

Verificar:

se os papeis aparecem corretamente no editor de usuario
se os papeis aparecem na listagem do plugin
se os papeis aparecem no perfil
se o usuario nao perde funcionalidades por ter mais de um papel

Limitacao Atual

O sistema ja suporta atribuicao multi-papel na interface e nos fluxos principais de exibicao.

Mas ainda existe logica de negocio que pode tratar um papel AI Admin como papel principal em alguns pontos, especialmente em partes de roteamento e decisoes de fluxo.

Em outras palavras:

atribuicao de multi-papel ja esta pronta
exibicao de multi-papel esta em boa parte pronta
algumas regras internas ainda precisam ser adaptadas para interpretar todos os papeis ao mesmo tempo

Esse e o proximo passo natural da implementacao.

Capturas de Tela e Complementos

As screenshots reais ainda nao fazem parte do repositorio. Abaixo esta a lista recomendada para producao desse material.

Shot list recomendada

1. Editor de usuario no WordPress

Arquivo sugerido:

docs/screenshots/01-user-editor-wordpress-role-and-ai-roles.png

Capturar:

Usuarios > Todos os usuarios > Editar usuario
select-box de papel do WordPress
secao de papeis AI Admin com checkboxes

Usar em:

secao sobre diferenca entre papel WordPress e papel AI Admin
secao sobre atribuicao de papeis

2. Campos adicionais de vinculacao

Arquivo sugerido:

docs/screenshots/02-user-editor-company-link-fields.png

Capturar:

ai_client_id
ai_company_name
demais campos de cadastro relevantes

Usar em:

secao de onboarding
secao de aprovacao

3. Tela AI Admin > Usuarios

Arquivo sugerido:

docs/screenshots/03-ai-admin-users-list.png

Capturar:

AI Admin > Usuarios
listagem com colunas de usuario e funcoes AI Admin
cards de funcoes no topo, se possivel

Usar em:

secao de administracao de usuarios
secao de multi-papeis

4. Perfil da empresa com abas

Arquivo sugerido:

docs/screenshots/04-company-profile-tabs.png

Capturar:

cabecalho do perfil
abas Profile Data, Users, Products, Quotations, Opportunities

Usar em:

secao de acesso apos login
secao de perfil/empresa

5. Aba Users da empresa

Arquivo sugerido:

docs/screenshots/05-company-profile-users-tab.png

Capturar:

listagem de usuarios vinculados
botoes principais da aba

Usar em:

secao de gerenciamento de usuarios vinculados

6. Formulario Add New User na area da empresa

Arquivo sugerido:

docs/screenshots/06-company-profile-add-user-form.png

Capturar:

formulario de criacao
area de selecao de multiplos papeis AI Admin

Usar em:

secao de criacao de usuario vinculado
guia rapido do cliente

7. Area de produtos

Arquivo sugerido:

docs/screenshots/07-company-profile-products-tab.png

Capturar:

aba Products
algum exemplo real de produto vinculado

Usar em:

secao de produtos

8. Area de cotacoes

Arquivo sugerido:

docs/screenshots/08-company-profile-quotations-tab.png

Capturar:

aba Quotations
listagem ou formulario, conforme o fluxo real mais importante

Usar em:

secao de cotacoes

9. Formulario publico de cotacao

Arquivo sugerido:

docs/screenshots/09-public-quotation-form.png

Capturar:

formulario de solicitacao
campos principais

Usar em:

guia rapido do cliente
secao de envio de cotacoes

10. Area ou pagina de anuncios

Arquivo sugerido:

docs/screenshots/10-ads-management-or-client-view.png

Capturar:

a tela mais relevante para o cliente/anunciante

Usar em:

secao de anuncios

11. Newsletter

Arquivo sugerido:

docs/screenshots/11-newsletter-form-or-management.png

Capturar:

formulario de newsletter ou tela mais adequada do fluxo real

Usar em:

secao de newsletter

12. Pagina publica do guia

Arquivo sugerido:

docs/screenshots/12-public-guide-page.png

Capturar:

pagina WordPress publicada com o shortcode
renderizacao final no tema

Usar em:

README
documentacao operacional
validacao final do projeto

Como Publicar Este Guia Como Pagina do Site

Agora o plugin possui um shortcode para renderizar um arquivo .md publico dentro de uma pagina normal do WordPress.

Shortcode

[ai_markdown_doc file="USER_ONBOARDING_AND_OPERATIONS_GUIDE.md" title="Guia de Operacao para Usuarios"]

Como publicar

Ir em Paginas > Adicionar nova.
Criar uma pagina, por exemplo:

titulo: Guia de Operacao
slug: guia-de-operacao

Inserir o shortcode acima no conteudo.
Publicar a pagina.
Garantir que a pagina esteja publica.

Por que isso funciona com o tema atual

O tema atual usa template de bloco com post-content. Isso significa que o shortcode sera renderizado dentro do layout normal do site, aproveitando cabecalho, menu, sidebar e rodape ja existentes.

Observacao

O shortcode foi pensado para documentacao em Markdown localizada dentro do diretorio do plugin e aceita apenas arquivos .md legiveis e internos ao plugin.