AI Studio

O AI Studio é o módulo em que a IA **conversa com o banco** e **cria telas HTML** para o Tavoli. Ele fica em **Administração → AI Studio** (`/admin/ai-studio`) e é exclusivo de usuários ADMIN.

Diferente do Construtor de Telas, onde você escolhe campos dentro de um layout fixo, aqui a IA escreve o HTML inteiro — design, tabela, gráfico e comportamento — e o resultado vira uma tela real do sistema.

---

Antes de começar

Sem o parâmetro ligado, todas as rotas do módulo respondem "AI Studio desabilitado nos parâmetros do sistema".

---

1. Projetos

A tela inicial lista os projetos. Um projeto agrupa conversas, telas, arquivos de referência e skills de um mesmo assunto (por exemplo, "Painéis do comercial").

---

2. Aba Conversa — perguntar ao banco

Escolha o provedor e o modelo no topo e escreva sua pergunta em português. A IA tem três ferramentas de leitura:

• listar_tabelas — procura tabelas por nome ou módulo;
• descrever_tabela — mostra os campos e os três nomes da mesma entidade (model, tabela física e alias da API);
• executar_consulta — roda um SELECT somente leitura, com limite de linhas e tempo.

Você acompanha o raciocínio ao vivo. Enquanto o assistente trabalha, aparece a *cadeia de execução*: cada ferramenta chamada, com quais argumentos, e o que voltou — passo a passo, no instante em que acontece.

`

1. ✓ listar_tabelas → 8 item(ns)

busca: produto · limite: 30

1. ✓ descrever_tabela → 30 campo(s) de Produto

nome: Produto

1. ✓ executar_consulta → 1 linha(s)

sql: SELECT COUNT(*) AS total_ativos FROM "Produto" WHERE "ativo" = TRUE

`

Depois que a resposta chega, a cadeia continua visível como "Como cheguei nessa resposta". Tudo isso também fica gravado na conversa e na Auditoria.

A conversa nunca escreve no banco. Se você pedir para alterar dados, a IA vai explicar que não pode por esse caminho.

> Atenção ao nome da tabela. Algumas entidades têm um "espelho" low-code com nome diferente (por exemplo, notas espelha NotaFiscal). Consultar o espelho pode devolver dado defasado e todo campo como texto. O sistema recusa consultas que usem o espelho e indica o nome físico correto.

---

3. Aba Telas — criar e melhorar

Gerar a primeira versão

Descreva a tela que você quer, por exemplo:

> Painel de faturamento por mês dos últimos 12 meses, com um gráfico de barras e uma tabela com total por vendedor.

A IA consulta o schema, confere os campos, escreve o HTML e declara no manifesto tudo que a tela consome. Antes de a versão ser gravada, o sistema verifica:

1. cada tabela e cada campo existem de verdade;
2. cada consulta SQL roda no banco em modo de teste (LIMIT 0), então erro de coluna ou de tipo aparece na hora;
3. o HTML não tenta acessar a internet nem usar id que não esteja no manifesto;
4. as tags do documento estão balanceadas.

Se algo falhar, a IA recebe o erro e corrige sozinha, na mesma tentativa.

Melhorar sem refazer

Com uma tela aberta, o botão passa a ser Melhorar. Descreva só a mudança ("adicione um filtro por período"). A IA lê apenas as regiões que precisa e devolve um patch. Cada melhoria cria uma versão nova, com o HTML completo — nada é sobrescrito.

Se o conteúdo tiver mudado desde a leitura, o patch é recusado inteiro. Nunca fica pela metade.

Preview

O preview é a tela de verdade rodando, com dados reais do seu banco, respeitando suas permissões e sua empresa. Ele roda isolado do ERP: a tela não enxerga sua senha, seu token nem consegue mandar dados para fora.

Versões

O seletor ao lado do nome da tela lista todas as versões. Restaurar traz uma versão antiga de volta como versão nova — o histórico nunca perde nada.

---

4. Publicar

Informe a rota (formato /modulo/nome-da-tela) e clique em Publicar. Antes de publicar, o sistema:

1. revalida o manifesto contra o banco;
2. roda a tela em um navegador de teste para pegar erro de JavaScript;
3. só então cria a tela no sistema, apontando para aquela versão específica.

Se o navegador de teste não estiver disponível no servidor, a publicação continua e um aviso informa que a checagem de renderização foi pulada.

Publicar de novo aponta a mesma rota para a versão nova. Despublicar esconde a tela sem apagar nada.

> Telas publicadas pelo AI Studio são visíveis para usuários ADMIN. Um usuário comum que abrir a rota verá um aviso de permissão.

---

5. Aba Contexto — skills e arquivos de referência

• Skills são instruções reutilizáveis coladas no pedido da IA: padrão visual do cliente, glossário de campos, regra de negócio recorrente. Escopo PROJETO vale só no projeto; GLOBAL vale em todos. Desmarcar "ativa" tira a skill do prompt sem apagá-la.
• Arquivos de referência (briefing, planilha, layout, imagem) aceitam até 10 MB. Ficam em área privada do servidor e só podem ser baixados por rota autenticada — nunca por link público. De arquivos de texto o sistema extrai o conteúdo para usar como contexto.

---

6. Escrita no banco pela tela

Uma tela pode alterar dados por três caminhos, nesta ordem de preferência:

O SQL de escrita só funciona com o parâmetro AI Studio — escrita por SQL ligado, e mesmo assim:

• UPDATE e DELETE sem WHERE são recusados;
• tabelas de controle (usuários, auditoria, telas, parâmetros, certificados) não aceitam escrita;
• antes de executar, o sistema conta quantas linhas seriam afetadas e mostra para você confirmar;
• acima do teto configurado em AI Studio — teto de linhas por escrita, a operação é abortada;
• cada usuário tem cota por tela em janela de uma hora: AI Studio — escritas por hora (padrão 20) e AI Studio — linhas por hora (padrão 2000). Tentativa recusada não consome cota;
• toda execução grava um registro na Auditoria com a ação AI_SQL_WRITE, o SQL, os valores e o número de linhas.

---

Perguntas comuns

A tela gerada pode ver a senha ou o token de quem abriu?

Não. Ela roda isolada e sem acesso à rede; todo dado passa pelo ERP, que aplica as suas permissões.

Dá para editar o HTML na mão?

Nesta versão a edição é pela IA (por instrução). O histórico de versões permite voltar a qualquer ponto.

A IA pode inventar um campo que não existe?

Ela pode tentar, mas a validação recusa antes de gravar — e devolve o erro para ela corrigir.

Onde vejo o que a IA fez?

Na conversa (cada chamada de ferramenta) e em Administração → Auditoria (cada operação do módulo).

Telas do sistema

Capturas reais desta tela, com dados sensíveis mascarados.