AI-inovyo-assistende-db/docs/data-model.md

Modelo de Dados

Visão Geral

Os dados de contexto e relatórios pré-processados são armazenados e consumidos diretamente do DynamoDB.

Estrutura de Tabelas

Cada combinação cliente + dashboard gera três tabelas:

{cliente}_{dashboard}_contatos
{cliente}_{dashboard}_respostas
{cliente}_{dashboard}_pesquisa

Convenção de Nomenclatura

• Letras minúsculas
• Espaços e hífens substituídos por _

Exemplo:

• Cliente: Bacio Di Latte, Dashboard: Transacional Loja App
• Tabelas: bacio_transacional_loja_app_contatos, bacio_transacional_loja_app_respostas, bacio_transacional_loja_app_pesquisa

---

1. {cliente}_{dashboard}_contatos

Contatos recebidos para ativar as pesquisas. Cada linha = um contato único.

Colunas Fixas:

Coluna	Descrição
contact_id	Identificador único do contato
surveyid	Identificador da pesquisa associada
name	Nome do contato
email	E-mail
phone	Telefone
status	Status (enviado, inválido, abriu e-mail, etc.)
url	Link único de resposta
data_recebimento	Data de recebimento (yyyy-mm-dd)
mes_recebimento	Mês de recebimento (mm/yyyy)

Colunas Variáveis (dependem do cliente): cidade, estado, cpf, produto_comprado, canal_de_compra, nome_da_loja, valor_da_venda, etc.

---

2. {cliente}_{dashboard}_respostas

Respostas consolidadas da pesquisa. Cada linha = um respondente único (versão mais atualizada).

Colunas Fixas:

Coluna	Descrição
responseid	Identificador único da resposta
status	Status (completou, parcial, inválida)
contact_id	Referência ao contato (FK)
data_resposta	Data da resposta (yyyy-mm-dd)
mes_resposta	Mês da resposta (mm/yyyy)

Colunas Variáveis (Perguntas): Uma coluna por pergunta, nomeada pelo shortname da tabela pesquisa. Exemplos: nps, atendimento_cordialidade, achou_produto, comentarios.

---

3. {cliente}_{dashboard}_pesquisa

Catálogo de perguntas dos questionários. Dicionário das colunas dinâmicas da tabela de respostas.

Coluna	Descrição
order_by	Ordem da pergunta no questionário
title	Texto completo da pergunta
shortname	Alias usado como nome de coluna em respostas
status	Status (ativa, oculta, inativa)

---

Relacionamentos

contatos (1) ─── (N) respostas     (join via contact_id)

pesquisa  ──────────▶ respostas    (shortname = nome das colunas dinâmicas)

DynamoDB — Tabela poc_dnx_monthly_summary

Armazena dados pré-processados e contexto para o agente.

Estrutura

Campo	Tipo	Descrição
id	string (PK)	Identificador (ex: 1, 2, bacio_transacional_loja_app_contexto)
item_type	string (GSI)	Tipo do item (ex: contexto)
contexto	string	Descrição contextual do dashboard
filter_key	string	Tipo de filtro: period ou event
itens_disponiveis	map	Dicionário {id: descrição} dos dados disponíveis
chaves_consolidadas	string	Lista de colunas/variáveis disponíveis por ID
variáveis dinâmicas	string	Dados pré-processados (resumos mensais, NPS, etc.)

Índice Secundário Global

• item_type_index — Permite consultar todos os itens de um tipo (ex: listar todas as bases com item_type = "contexto")

Formato do ID de Período

Quando filter_key = "period", os IDs seguem o formato year_month:

• Ano: 4 dígitos (2025, 2024, etc.)
• Mês: 2 dígitos (01 a 12)
• Exemplo: 2025_05 = maio de 2025

Formato do ID de Evento

Quando filter_key = "event", os IDs descrevem o evento:

• Formato: Nome - Cidade DD/MM/YYYY

Cálculo de NPS

Dentro dos dados existe a variável NPS que contém distribuicao com notas e quantidade de respondentes:

• Notas 0-6: Detratores
• Notas 7-8: Neutros
• Notas 9-10: Promotores

Fórmula: NPS = %Promotores - %Detratores