Skip to content

02 - Modelagem do Banco de Dados (Módulo de IA e Cadastro)

Este documento detalha a estrutura relacional mapeada via engenharia reversa que sustenta o ecossistema de Cadastro de Produtos e Geração de Conteúdo IA.

O banco de dados principal (foconopreco - MySQL) isola os dados por Tenant através da tabela Organizacoes, garantindo que os prompts, templates e filas de conteúdo não se misturem.

1. Dicionário de Dados

1.1 Tabela: Organizacoes

Atua como o nó central de multi-tenancy e controle de acesso da API de distribuição.

  • id_organizacao (PK): Identificador único da empresa.
  • nome_empresa: Razão social ou nome fantasia.
  • cnpj_cpf: Documento fiscal.
  • api_key: Token de autorização exigido pelo endpoint /api/v1/textos-ia para consumo via ERP.
  • ativa (Boolean): Flag de bloqueio global do tenant.
  • data_cadastro (Timestamp): Mapeado como CREATED_AT no modelo Laravel.

1.2 Tabela: Produtos

Registra os produtos internos do sistema que servem como gatilho para a fila de IA. (Nota técnica: Esta tabela possui nomenclatura e PK customizadas e não utiliza os timestamps padrão do Laravel)

  • ID (PK): Identificador único do produto.
  • id_organizacao (FK): Vínculo com a empresa dona do registro.
  • SKU: Código identificador da mercadoria (utilizado como chave principal nas integrações e importações).
  • Nome: Palavra-chave ou título base utilizado para disparar as buscas no Google.
  • id_template_ia (FK - Nullable): Template de comportamento associado a este produto.
  • ia_processado (Boolean/Tinyint): Flag que indica se o produto já possui um conteúdo gerado e salvo.
  • ativo (Boolean/Tinyint): Status do produto no painel.

1.3 Tabela: templates_ia

Armazena a inteligência e as regras de engenharia de prompt geradas dinamicamente.

  • id (PK): Identificador do template.
  • id_organizacao (FK): Garante que a empresa só visualize seus próprios templates.
  • nome_template: Nome de exibição no painel (ex: "Descrição SEO Premium").
  • prompt_sistema (Text/LongText): O bloco massivo de instruções, persona e tom de voz lido pelo Flowise.
  • json_schema_saida (Text/LongText): A estrutura JSON obrigatória para validação dos dados de retorno da IA.
  • ativo (Boolean): Permite desativar templates antigos sem perder o histórico.
  • created_at / updated_at: Timestamps padrão.

1.4 Tabela: FilaGeracaoConteudo

O "coração" do processamento assíncrono. Gerencia o ciclo de vida do Worker.

  • id (PK): Identificador da tarefa.
  • id_produto (FK): Vincula a tarefa ao registro na tabela Produtos.
  • id_organizacao (FK): Vínculo com a empresa.
  • id_template_ia (FK): Template de IA a ser usado na execução atual.
  • sku: Cache do SKU para facilitar buscas na UI.
  • nome_produto: Nome base para a busca.
  • palavra_chave_entrada: O termo exato digitado no formulário ou planilha.
  • status (Varchar): Estado da fila (pendente, processando, concluido, erro).
  • mensagem_erro (Text - Nullable): Grava a exceção capturada caso o Worker falhe.
  • aprovado (Tinyint): Status da curadoria humana (0 = Não revisado, 1 = Aprovado).
  • data_aprovacao (Timestamp - Nullable): Momento exato em que o operador clicou em "Salvar e Aprovar".
  • created_at / updated_at: Timestamps padrão.

1.5 Tabela: conteudo_gerado_ia

Armazena o payload final purificado retornado pelo Gemini/Flowise e tratado pelo Laravel.

  • id (PK): Identificador do conteúdo.
  • produto_id (FK): Vínculo com o produto.
  • id_template_ia (FK): Rastreia com qual template essa versão específica foi gerada.
  • conteudo_gerado_json (JSON): O documento completo contendo títulos, especificações, galerias de imagens e SEO.
  • modelo_usado: Armazena a string do modelo (ex: gemini-2.5-flash).
  • versao_prompt: Controle de versionamento do prompt enviado.
  • gerado_em (Timestamp): Data de conclusão da geração.

1.6 Tabela: cache_api_google

Estratégia de redução de custos (Cost-Saving) da infraestrutura.

  • id (PK): Identificador do registro de cache.
  • produto_id (FK): Vínculo com o item pesquisado.
  • tipo_busca (Varchar): Indica a finalidade da coleta (texto ou imagem).
  • resposta_bruta_json (LongText/JSON): Dump da resposta original do Google Custom Search.
  • buscado_em (Timestamp): Utilizado para calcular a expiração do cache e forçar renovações caso necessário.

2. Relacionamentos e Integridade

A arquitetura garante isolamento de dados baseada nas seguintes regras de negócio (ON DELETE e ON UPDATE): 1. Nó Multi-Tenancy: A exclusão de uma Organizacao deve realizar o CASCADE de todos os Produtos, templates_ia e tarefas na FilaGeracaoConteudo. 2. Proteção de Templates: O sistema impede (via exceção capturada no Controller) a exclusão de um template_ia caso existam registros vinculados na tabela de Produtos ou na Fila. 3. Múltiplas Versões de Conteúdo: O relacionamento entre Produtos e conteudo_gerado_ia é de 1:N. A API externa utiliza queries agregadoras (MAX(id)) para recuperar sempre a versão cronologicamente mais recente e que possua aprovação na fila associada.