Initial commit

docs/data-model.md

@@ -0,0 +1,129 @@
+# 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`