Skip to content

01 - Arquitetura de Software e Fluxo de Inteligência Artificial

Este documento descreve detalhadamente a arquitetura de software, o ciclo de vida dos dados e o fluxo de integração com Inteligência Artificial (IA) no módulo de Cadastro de Produtos e Geração de Conteúdo Automático.

1. Visão Geral da Arquitetura Célula-IA

O sistema de cadastro e enriquecimento de conteúdo foi desenhado seguindo o padrão de microsserviços e processamento assíncrono baseado em filas (Event-Driven Architecture). A infraestrutura é totalmente isolada via Docker, garantindo que picos de requisições ou o processamento pesado de modelos de linguagem (LLMs) não afetem a performance do site principal ou do banco de dados relacional operacional.

O ecossistema é composto por quatro camadas principais: 1. Camada de Ingestão e Interface (Monolito Laravel): Responsável por receber os inputs dos usuários (via painel administrativo ou planilha em lote) e gerenciar os estados de aprovação humana. 2. Camada de Mensageria e Cache Rápidas (Redis): Gerencia as filas assíncronas de processamento e armazena em cache as respostas brutas das APIs externas para otimização de custos e performance. 3. Camada de Processamento Background (Laravel Workers & Scheduler): Consome as filas de IA e encapsula a inteligência de negócios. 4. Camada de Orquestração de IA (Flowise AI & ChatGPT): Fornece o motor cognitivo que realiza a engenharia de prompts e a estruturação de saídas rígidas em JSON Schema.

2. Componentes de Infraestrutura (Mapeamento Docker)

Baseado nas configurações de microsserviços declaradas no docker-compose.yml, os seguintes containers são diretamente responsáveis pela sustentação do motor de cadastro e IA:

┌────────────────────────────────────────────────────────────────────────┐
│                                  SUITE - IA                            │
├───────────────────┬────────────────────────────────────────────────────┤
│ Container         │ Função Crítica no Fluxo de Cadastro                │
├───────────────────┼────────────────────────────────────────────────────┤
│ foconopreco_app   │ Aplicação Laravel principal (PHP-FPM). Renderiza o │
│                   │ painel, valida inputs e gerencia o CRUD de         │
│                   │ templates e organizações.                          │
├───────────────────┼────────────────────────────────────────────────────┤
│ foconopreco_redis │ Broker de mensageria que sustenta as filas e o     │
│                   │ cache temporário de buscas do Google.              │
├───────────────────┼────────────────────────────────────────────────────┤
│ foconopreco_db    │ Banco de dados relacional principal (MySQL 8.0).   │
│                   │ Armazena filas, conteúdos finais e organizações.   │
├───────────────────┼────────────────────────────────────────────────────┤
│ foconopreco_flowise│ Orquestrador de IA (Low-Code/API). Expõe o        │
│                   │ endpoint interno de predição cognitivo.            │
├───────────────────┼────────────────────────────────────────────────────┤
│ laravel_worker_   │ Worker dedicado exclusivo para rodar a fila        │
│ conteudo          │ `fila_geracao_conteudo_ia`. Concurrency controlada.│
├───────────────────┼────────────────────────────────────────────────────┤
│ foconopreco_      │ Roda em loop infinito simulando um daemon Cron para│
│ scheduler         │ rodar o comando `php artisan schedule:run`.        │
└───────────────────┴────────────────────────────────────────────────────┘

3. O Ciclo de Vida do Dado: O Caminho do Input ao ERP

O fluxo de enriquecimento e automação de um produto cruza de forma síncrona e assíncrona os módulos do sistema. Abaixo está o mapeamento passo a passo desse ciclo:

Passo 1: Ingestão e Entrada de Dados

O operador do sistema possui duas portas de entrada no index.blade.php: * Adição Manual: Informa um SKU e uma Palavra-Chave (ex: Furadeira Bosch 500W) vinculando opcionalmente a um Template de IA específico. * Importação em Massa (Planilha Interativa): Utiliza o componente Jspreadsheet para colar centenas de SKUs e Palavras-Chave copiados diretamente do Excel.

Ao submeter, o ProdutoDashboardController executa uma trava de segurança máxima (Backend): filtra registros vazios e aplica um unique('sku') para impedir duplicidades no mesmo lote. O sistema cria ou recupera o registro na tabela Produtos e faz um INSERT INTO FilaGeracaoConteudo com o status inicial pendente.

Passo 2: Despacho para a Fila (Redis)

Imediatamente após a persistência no banco, o Laravel despacha o Job ProcessarConteudoProdutoIA passando o produtoId e o idTemplateIa. Este Job é serializado e empurrado para o Redis dentro da fila de prioridade alta fila_geracao_conteudo_ia. (Nota: Caso algum item falte na fila por oscilações, o Artisan Command DispararJobsConteudo mapeia os itens órfãos com status pendente e força o redespacho via Scheduler).

Passo 3: Consumo e Coleta Externa (Minerador)

O container laravel_worker_conteudo captura o Job pendente e altera o status na tabela FilaGeracaoConteudo para processando. O Job invoca o ConteudoIAService, que inicia a mineração de dados em tempo real: 1. Busca de Contexto Textual: Dispara uma chamada à API do Google Custom Search com a palavra-chave informada para coletar os top 5 resultados indexados (títulos e snippets técnicos). 2. Busca de Imagens: Dispara uma segunda chamada simultânea ao Google com o parâmetro searchType => image para minerar os URLs originais das fotos do fabricante espalhadas na web.

Passo 4: Engenharia Reversa e Processamento Cognitivo

Com os dados brutos consolidados, o ConteudoIAService recupera as configurações do Template de IA associado (templates_ia). Ele constrói um Meta-Prompt Rígido unindo três blocos maciços de informação: 1. Instruções de Personalidade (prompt_sistema): O tom de voz e a persona comercial extraídos via engenharia reversa. 2. JSON Schema Restrito (json_schema_saida): A tipagem e os campos obrigatórios exigidos pela aplicação, injetando travas explícitas como a proibição de hifens nos títulos e regras matemáticas rígidas de cálculo de prazos de garantia. 3. Contexto Minerado: Os dados e especificações reais do produto trazidos pelo Google.

Este bloco massivo é transmitido via protocolo HTTP interno para o container do Flowise AI (/api/v1/prediction/...), que por sua vez se comunica com a API do ChatGPT. O modelo processa o prompt e devolve uma estrutura JSON purificada contendo toda a cópia comercial, metadados SEO e fichas técnicas limpas.

Passo 5: Sanitização de Resposta e Blindagem de Imagens

O Worker do Laravel recebe a resposta da IA, remove os delimitadores de bloco Markdown (```json), valida se o retorno é um array PHP tratável e persiste os dados na tabela conteudo_gerado_ia em formato nativo JSON. O status da fila é alterado para concluido e a flag ia_processado do produto vai para 1.

O Desafio Antibot e a Solução de Padronização: Muitos URLs de imagens retornados pelo Google vêm em formatos modernos (.webp) ou protegidos por Firewalls/Antibot do fabricante original, o que causaria quebras massivas na integração com o banco de dados Oracle externo ou ERP. Para mitigar isso: * Durante a abertura do modal de revisão pelo usuário, o método getConteudo varre os links dinamicamente. * Os links externos válidos passam por um motor cURL customizado (baixarImagemSegura) que simula cabeçalhos reais de navegadores desktop e ignora travas de SSL. * O arquivo binário é capturado, processado pela biblioteca Intervention/Image, onde é convertido para JPEG (qualidade 85%), redimensionado para uma proporção quadrada perfeita de 1000x1000 pixels, centralizado sob um fundo branco sólido (->pad(1000, 1000, 'ffffff')) e armazenado de forma estática no armazenamento do servidor local (public/uploads/ia/ready_...). Links corrompidos ou que retornam telas de bloqueio HTML são expurgados do JSON automaticamente para blindar a aplicação.

Passo 6: Curadoria Humana e Validação de Segurança

Nenhum dado gerado pela IA vai diretamente para o ambiente produtivo ou ERP externo sem antes passar pelo crivo de um operador. Na interface do Dashboard, o produto finalizado exibe um botão para abrir o Editor de Conteúdo IA.

O painel monta inputs individuais e expansíveis para cada chave gerada (titulo_produto, especificacoes_tecnicas, etc). O operador pode ajustar textos pontualmente ou gerenciar a galeria de fotos (excluir imagens inválidas por clique ou realizar o upload de arquivos .jpg e .png locais da sua máquina).

Ao clicar em "Salvar e Aprovar", uma trava de segurança no Frontend inspeciona a galeria: 1. Trava de Quantidade: É proibido aprovar produtos que não possuam pelo menos uma foto ativa. 2. Trava de Link Externo: O sistema varre o atributo src das imagens. Se qualquer imagem mantiver um link externo que não foi internalizado pelo servidor local (ou seja, que não contenha a assinatura de segurança uploads/ia/ready_), o botão é bloqueado exibindo uma mensagem de erro grave ao usuário. Isso garante o isolamento total da infraestrutura de mídia.

Após a validação bem-sucedida, o endpoint registrarAprovacao carimba a linha da fila com aprovado = 1 e data_aprovacao = NOW().

Passo 7: Distribuição e Ingestão no ERP (API Externa)

Sistema sankhya e as rotinas do banco de dados Oracle (sankhya) realizam requisições periódicas no endpoint de saída da aplicação (/api/v1/textos-ia). A requisição exige no cabeçalho um token de segurança X-API-KEY validado dinamicamente contra a tabela Organizacoes.

O ContentApiController@getConteudoCompleto faz a mágica final de distribuição: * Realiza subqueries complexas para agrupar as SKUs e extrair estritamente a última versão do conteúdo aprovado de cada produto, ignorando rascunhos. * Formatador de Listas e Pontuações: Aplica rotinas de regex estruturais baseadas em regras gramaticais severas: * Substitui duplicidades de pontuação acidentais no meio do texto (como ., ou ,.). * Varre as especificações técnicas e itens inclusos linha por linha, removendo hifens iniciais duplicados e marcadores genéricos. * Força todas as linhas a iniciarem com letras maiúsculas e terminarem obrigatoriamente com ponto e vírgula (;), exceto a última linha da lista, que recebe um ponto final (.). * Preserva de forma inteligente as linhas que terminam nativamente com pontos de interrogação ou exclamação (? ou !), pulando a injeção do caractere. * Isola as notas de rodapé normativas (ex: *Imagens meramente ilustrativas.) removendo hifens de lista e mantendo a formatação limpa. * O endpoint responde com um JSON contendo uma paginação robusta e os códigos de identificação interna perfeitamente formatados para consumo imediato.

4. Diagrama Conceitual do Fluxo Técnico

[Painel Admin / Planilha] 
           │
           ▼
   (Fila Gerada: 'pendente')
           │
           ▼
[Redis: fila_geracao_conteudo_ia] ◄─── [Artisan Command: conteudo:disparar]
           │
           ▼
[Worker Laravel background] ───► Altera status para 'processando'
           │
           ├─► [Verifica Cache API Google] 
           │     ├─► Encontrou? Usa os dados locais a custo zero.
           │     └─► Não encontrou? Consulta Google Search API e salva em Cache.
           │
           ▼
[Construção do Meta-Prompt] (Prompt de Sistema + Schema Rígido + Contexto Google)
           │
           ▼
  [Microsserviço Flowise AI] ───► [API ChatGPT]
           │
           ▼
[Resposta JSON Purificada] ───► Salva em `conteudo_gerado_ia` & Status = 'concluido'
           │
           ▼
[getConteudo (Processamento de Imagens)] ───► Normalização via cURL e Intervention/Image
           │                                 (JPEG Quadrado 1000x1000 fundo branco)
           ▼
[Painel de Revisão Humana] ◄─── Trava de segurança (Bloqueia imagens externas ou vazias)
           │
           ▼
[Aprovação / Carimbo de Sucesso] (aprovado = 1, data_aprovacao = NOW())
           │
           ▼
[API Externa: /v1/textos-ia] ───► Higienização Gramatical Rígida ───► [Ingestão no ERP]