# 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`