# Manual da Agência — E-radios

> Este manual cobre 100% das funcionalidades disponíveis para usuários do tipo **Agência**.
>
> Plataforma E-radios — Marketplace B2B de publicidade em rádio programática.

---

## 1. Introdução: a conta de Agência

A conta de **Agência** é uma conta de comprador na E-radios, igual à de Anunciante, mas com poderes adicionais:

| Recurso | Anunciante | Agência |
|---------|:---------:|:-------:|
| Marketplace, Mapa, Comparador | Sim | Sim |
| Carrinho e checkout | Sim | Sim |
| Minhas Campanhas | Sim | Sim |
| Cadastro e gestão de clientes | — | **Sim** |
| Comissão variável por pedido | — | **Sim** |
| Painel de performance (dashboard) | — | **Sim** |
| Propostas comerciais (criar, enviar, aprovar) | — | **Sim** |
| Templates visuais de proposta | — | **Sim** |
| Kanban com colunas personalizadas | — | **Sim** |
| Analytics de propostas | — | **Sim** |

> ℹ️ **Nota:** Toda compra feita pela agência (carrinho ou conversão de proposta) precisa estar vinculada a um **cliente cadastrado**, pois a agência opera como intermediária e recebe **comissão** sobre o pedido.

### Como o pagamento funciona

A E-radios não processa pagamento dentro da plataforma. Após você (agência) confirmar um pedido, ele entra com o status **"Aguardando contato"**, e a equipe E-radios entra em contato para combinar a forma de pagamento por fora. A comissão da agência é somada ao total do pedido, junto com a taxa técnica da plataforma (5%) e o eventual custo de monitoramento.

---

## 2. Cadastro de Agência

### Onde fica

- Tela de login → botão **"Criar conta"** → **Agência**
- Rota: `/register/agency`

### Etapa 1 — Dados da Agência

| Campo | Descrição | Obrigatório |
|-------|-----------|:---:|
| CNPJ | CNPJ da agência (com máscara `00.000.000/0000-00`, validado em tempo real) | Sim |
| Razão Social | Nome legal completo da empresa | Sim |
| Nome Fantasia | Nome comercial da agência (será exibido em propostas, pedidos e cliente) | Sim |
| Telefone | Telefone com DDD, formato `(00) 00000-0000` | Sim |

### Etapa 2 — Dados de Acesso

| Campo | Descrição | Obrigatório |
|-------|-----------|:---:|
| E-mail Corporativo | E-mail empresarial. **Domínios gratuitos (Gmail, Hotmail, Yahoo, etc.) são bloqueados** | Sim |
| Senha | Mínimo 10 caracteres com letra maiúscula, minúscula, número e caractere especial | Sim |
| Confirmar Senha | Repetir a senha exata | Sim |

### Etapa 3 — Verifique seu E-mail

Após cadastrar, a plataforma envia um e-mail com um **link de confirmação**. Você precisa clicar nele antes de conseguir fazer login.

### Regras importantes

- **CNPJ é validado** em tempo real — CNPJs inválidos são rejeitados na hora.
- **CNPJ duplicado** é rejeitado — só uma conta por documento.
- **E-mail duplicado** é rejeitado.
- O cadastro de agência é **auto-aprovado** após confirmação por e-mail.

> 💡 **Dica:** Use o e-mail corporativo principal da agência. Esse e-mail será o canal de comunicação para notificações de propostas visualizadas, aprovadas, recusadas e atualizações de pedidos.

### Erros comuns

| Erro | Causa | Solução |
|------|-------|---------|
| "Domínio de e-mail não permitido" | Tentativa de uso de Gmail, Hotmail, Outlook.com, etc. | Use um e-mail no domínio da agência |
| "CNPJ inválido" | Dígitos verificadores incorretos | Confira o CNPJ no Cartão CNPJ da Receita |
| "E-mail já cadastrado" | Conta com esse e-mail já existe | Faça login ou recupere a senha |
| "As senhas não coincidem" | Senha e confirmação diferentes | Reescreva a senha igual nos dois campos |

---

## 3. Login, 2FA e Recuperação de Senha

### Login

- Rota: `/login`
- Aceita **e-mail OU CNPJ** no primeiro campo, mais a senha.
- Se 2FA estiver ativo, um código de 6 dígitos é enviado ao e-mail; digite na tela de verificação.

### Esqueci minha senha

- Link **"Esqueceu a senha?"** na tela de login → digite o e-mail → clique no link enviado por e-mail → redefina a senha.
- Rota: `/forgot-password` → `/reset-password/:token`

### 2FA (autenticação em duas etapas)

- Ativa-se em **Minha Conta → Segurança**.
- Confirmação por link enviado ao e-mail.
- A cada login posterior, a plataforma envia um código de 6 dígitos por e-mail.
- Após 5 tentativas erradas, o código é invalidado e é preciso fazer login novamente.

> ⚠️ **Atenção:** Recomendamos fortemente ativar o 2FA em contas de agência, pois a conta tem acesso a dados de múltiplos clientes e propostas com valores comerciais.

---

## 4. Visão Geral da Plataforma e Menu Lateral

Após o login, a agência cai no **Marketplace** (`/marketplace`) e o menu lateral mostra três blocos próprios da agência:

### Bloco "Descubra"
- **Buscar Rádios** → `/marketplace`
- **Mapa de Cobertura** → `/mapa`
- **Comparar Emissoras** → `/compare`

### Bloco "Agência" (exclusivo da agency)
- **Painel da Agência** → `/agency/dashboard`
- **Propostas** → `/proposals`
- **Meus Clientes** → `/agency/clients`

### Bloco "Campanhas"
- **Minhas Campanhas** → `/campaigns`
- **Radio Analytics** → abre site externo de monitoramento em nova aba

### Bloco "Configurações"
- **Ajustes** → `/my-account`

> 💡 **Dica:** O menu pode ser recolhido (collapsed) para ganhar espaço de tela. O estado é persistido no navegador.

No header (topo da tela) há também:
- **Carrinho** (ícone) — abre o carrinho lateral.
- **Avatar/Nome** — atalho para Minha Conta e Sair.

---

## 5. Painel da Agência (Dashboard)

### Onde fica
- Menu **Agência → Painel da Agência**
- Rota: `/agency/dashboard`

### O que aparece

#### Stat Cards (KPIs do topo)

| Card | O que mostra |
|------|--------------|
| **Total Faturado** | Soma de `totalAmount` de todos os pedidos da agência. Indicador "vs. mês anterior" em verde/vermelho |
| **Comissões (Total)** | Soma de `agencyCommission` (valor) de todos os pedidos. Indicador "vs. mês anterior" |
| **Campanhas Ativas** | Pedidos em status `paid`, `pending_approval`, `approved`, `scheduled` ou `in_progress` |
| **Pedidos no Mês** | Quantidade de pedidos criados no mês atual. Indicador "vs. mês anterior" |

#### Gráficos

| Gráfico | Descrição |
|---------|-----------|
| **Desempenho de Vendas** (linha) | Faturamento (linha cheia) e Comissões (linha tracejada) por mês, últimos 12 meses |
| **Top Categorias** (donut) | Distribuição de pedidos por tipo de produto (Comercial, Testemunhal, Patrocínio, etc.) |

#### Tabela "Campanhas por Clientes"

Mostra cada cliente com:
- Nome + iniciais + documento
- Total de Pedidos
- Faturamento
- Comissão acumulada
- Data do último pedido

Paginação: 5 clientes por página. Botões **Filtrar** e **Exportar**.

#### Tabela "Pedidos Recentes"

Últimos 10 pedidos com:
- Número do pedido (`#PEDIDO-...`)
- Cliente
- Quantidade de itens
- Total
- Comissão
- Status (Aguardando Contato, Pago, Em Veiculação, Concluído, etc.)
- Data (formato relativo: "Hoje", "Ontem", ou "DD MMM AAAA")

Filtro por busca textual (número do pedido ou nome do cliente). Botão **Ver todos os pedidos** leva para `/campaigns`.

> 💡 **Dica:** O dashboard é a forma mais rápida de saber se algum cliente parou de movimentar. Clientes sem pedido recente aparecem com data antiga na coluna "Último Pedido".

---

## 6. Meus Clientes

### Onde fica
- Menu **Agência → Meus Clientes**
- Rota: `/agency/clients`

### O que aparece

#### Cabeçalho
- KPIs: total, ativos, inativos, pendentes
- Botão **+ Novo Cliente**
- Abas: **Todos / Ativos / Inativos**

#### Tabela
Para cada cliente:
- Avatar com iniciais (cor automática a partir do nome)
- Nome
- Documento (CNPJ/CPF)
- E-mail
- Telefone
- Pessoa de contato
- Status (badge verde "Ativo" ou cinza "Inativo")
- Menu de ações (Editar / Excluir)

Paginação: 10 clientes por página.

### Cadastrar / Editar Cliente

Modal com os campos:

| Campo | Descrição | Obrigatório |
|-------|-----------|:---:|
| Nome | Nome ou razão social do cliente | Sim |
| CNPJ ou CPF | Documento do cliente — único por agência | Sim |
| E-mail | E-mail de contato | Não |
| Telefone | Telefone com DDD | Não |
| Pessoa de contato | Nome do responsável no cliente | Não |
| Endereço | CEP, rua, número, complemento, bairro, cidade, estado | Não |
| Observações | Anotações livres | Não |

Status (`active` / `inactive`) é definido automaticamente na criação como `active` e pode ser alterado depois.

### Regras de negócio

- Cada agência só vê e edita os **próprios** clientes (isolamento por `agencyId`).
- O **mesmo CNPJ/CPF não pode ser duplicado dentro da mesma agência** (a mensagem é "Já existe um cliente cadastrado com este documento").
- **Apenas clientes ativos** aparecem como opção no carrinho e em propostas.
- A exclusão é **definitiva** (hard delete) — pedidos e propostas antigas mantêm o nome do cliente como snapshot, mas o vínculo é perdido.

> ⚠️ **Atenção:** Ao excluir um cliente, ele desaparece da seleção de carrinho e de propostas, mas os pedidos e propostas já criados continuam existindo (com o nome do cliente preservado).

> 💡 **Dica:** Use o campo **Observações** para guardar peculiaridades do cliente (ex.: "fatura sempre dia 10", "exige NF antes de veicular").

### Erros comuns

| Erro | Causa | Solução |
|------|-------|---------|
| "Nome e CPF/CNPJ são obrigatórios" | Campos vazios | Preencha os dois |
| "Já existe um cliente cadastrado com este documento" | Documento duplicado | Procure o cliente na lista — provavelmente já cadastrou |
| "Cliente não encontrado ou não pertence a esta agência" | ID inválido na edição/exclusão | Recarregue a página |

---

## 7. Marketplace, Mapa e Comparador

A agência usa essas três páginas exatamente como um anunciante.

### Marketplace (`/marketplace`)
Vitrine pública de emissoras aprovadas. Filtros por nome, cidade, estado, faixa de preço, categorias. Cards com logo, nome, cidade, audiência e produtos disponíveis (Comercial 15s/30s/45s/60s, Testemunhal 30s/60s e Patrocínios). Botão **+ Adicionar** envia para o carrinho lateral.

### Mapa de Cobertura (`/mapa`)
Mapa interativo do Brasil com marcadores das emissoras e raios de cobertura por classe de antena. Clusterização automática quando há muitas próximas. Permite adicionar produtos direto do popup do marcador.

### Comparador (`/compare`)
Compara **até 5 emissoras** lado a lado: audiência, preços por inserção, cobertura, perfil demográfico e CPM (Custo por Mil ouvintes). Botão **Montar sua campanha** simula orçamento.

> 💡 **Dica de agência:** O comparador é poderoso para justificar a escolha de mídia para o cliente final. Os dados de CPM podem ser exportados (em propostas) para anexar ao orçamento.

---

## 8. Carrinho e Checkout

### Onde fica
- Ícone do carrinho no header → painel lateral
- Tela completa: `/cart`

### Diferenças exclusivas da Agência

Quando o usuário logado é uma **agência**, o carrinho mostra um **painel "Dados da Agência"** ao lado do checkout, com dois campos obrigatórios:

| Campo | Descrição |
|-------|-----------|
| **Cliente Anunciante** | Dropdown com seus clientes cadastrados (apenas ativos selecionáveis). É **obrigatório** escolher um antes de finalizar |
| **Sua Comissão (%)** | Campo numérico (0–100, com passo de 0,5). É somado ao total do pedido como acréscimo do cliente |

Se você não tiver nenhum cliente cadastrado, aparece um aviso `"Nenhum cliente cadastrado. Cadastre no seu painel."` apontando para `/agency/clients`.

### Composição do preço (visão da agência)

| Componente | Descrição |
|------------|-----------|
| **Produtos** | Soma de `preço × quantidade` de cada item |
| **Patrocínios** | Valor mensal por patrocínio selecionado |
| **Produção** | R$ 50,00 por item que pediu gravação profissional (não cobra em testemunhais) |
| **Taxa da plataforma** | 5% sobre o valor dos produtos (taxa técnica) |
| **Monitoramento** | R$ 70,00 por emissora monitorada (Radio Analytics, opcional) |
| **Comissão de agência** | Percentual definido pela própria agência, somado ao total |
| **Total** | Tudo acima somado, exibido para o cliente |

### Checkout em 3 etapas

#### Etapa 1 — Agendamento
Calendário de cada item: distribua as inserções nas datas desejadas (manualmente ou via "distribuir automaticamente"). Mínimo de 3 dias úteis de antecedência. Patrocínios pedem apenas a seleção do mês.

> ⚠️ **Bloqueio para agência:** o botão **Próxima Etapa** só avança se houver um **cliente selecionado** no painel "Dados da Agência".

#### Etapa 2 — Materiais
Para cada item, envie:
- **Áudio pronto** (MP3 ou WAV)
- **Texto/roteiro digitado**
- **Solicitação de gravação** (com gênero da voz, estilo musical, pronúncia fonética, roteiro)

#### Etapa 3 — Confirmação
Revisão final + resumo financeiro com a comissão da agência destacada. Botão **Confirmar Pedido** cria a campanha em status `pending_contact`.

### Botões adicionais para agência

- **Gerar PDF de Plano de Mídia**: exporta um PDF com dados da agência, dados do cliente selecionado, lista de itens, agendamento e comissão. Útil para enviar cotação ao cliente antes mesmo de fechar o pedido.

### Modo Proposta

A agência pode entrar no **Modo Proposta** (clicando em **Nova Proposta** em `/proposals` ou em **Criar Proposta** no estado vazio). Nesse modo:
- O carrinho funciona como **montagem da proposta** (não cria pedido).
- O stepper passa a ter **2 etapas** (Agendamento → Confirmação).
- Materiais não são pedidos.
- Ao confirmar, é criada uma **proposta em rascunho** (não um pedido) e você cai no editor de proposta.
- Um banner no topo indica que você está nesse modo.

### Erros e regras

| Erro | Causa | Solução |
|------|-------|---------|
| "Selecione o cliente" | Agência não escolheu o cliente | Selecione no painel "Dados da Agência" |
| "Por favor, agende todas as inserções antes de continuar" | Algum item sem data | Volte ao Etapa 1 e complete o calendário |
| "Por favor, envie todos os materiais antes de continuar" | Algum item sem material | Volte à Etapa 2 e suba os arquivos |

---

## 9. Minhas Campanhas (pedidos da agência)

### Onde fica
- Menu **Campanhas → Minhas Campanhas**
- Rota: `/campaigns`

Funcionalidade idêntica à de anunciante, com o detalhe que cada cartão exibe também o **cliente vinculado** e a **comissão** apurada.

### Ciclo de vida do pedido

| Status | Significado |
|--------|-------------|
| Aguardando contato | Pedido criado, equipe E-radios vai entrar em contato |
| Pagamento pendente | Combinaram pagamento, aguardando confirmação |
| Pago | Pagamento confirmado |
| Em análise | Materiais sendo revisados |
| Aprovado | Tudo OK, esperando data |
| Agendado | Inserções agendadas na grade da emissora |
| Em veiculação | Spots no ar |
| Concluído | Veiculação totalmente cumprida |
| Cancelado | Pedido cancelado |

### Detalhe do pedido (`/campaigns/:id`)
Lista de itens, agendamento, materiais, resumo financeiro com comissão da agência destacada.

> 💡 **Dica:** Use os filtros de status para focar nos pedidos ativos no dia a dia.

---

## 10. Propostas Comerciais — visão geral e Kanban

### Onde fica
- Menu **Agência → Propostas**
- Rota: `/proposals`

### O que é

Uma proposta é um documento comercial gerado pela agência para apresentar uma campanha ao cliente final, com:
- Itens (do marketplace ou customizados)
- Personalização visual completa (cores, logo, capa, fontes, KPIs)
- Briefing, mapa de cobertura, tabela de itens, observações
- Link público com slug único (`/p/:slug`)
- Status próprios e ciclo de vida independente do pedido

### Cabeçalho da página

- **Título**: "Propostas Comerciais"
- **Subtítulo**: "X propostas no total" + chip de propostas ativas + chip de valor total acumulado
- **Busca** por título, cliente ou número
- **Toggle "Encerradas"** — esconde/mostra colunas de Recusada, Expirada e Convertida
- **Botão Analytics** → `/proposals/analytics`
- **Botão Atualizar** (refresh)
- **Botão "+ Nova Proposta"** → entra no Modo Proposta e leva para o Marketplace

### Kanban com 7 colunas de sistema

| Coluna | Cor | Status técnico |
|--------|:---:|:---:|
| Rascunho | cinza | `draft` |
| Enviada | azul | `sent` |
| Visualizada | roxo | `viewed` |
| Aprovada | verde | `approved` |
| Recusada | vermelho | `rejected` |
| Expirada | laranja | `expired` |
| Convertida | turquesa | `converted` |

### Cartão da proposta

Mostra:
- Número da proposta (ex: `PROP-20260504-0007`)
- Cliente (ou título, se não vinculado a cliente)
- Quantidade de itens
- Quantidade de visualizações
- Indicador de validade (ex: "3d restantes" em laranja se ≤3 dias)
- Valor total formatado (ex: `R$ 24,5k` ou `R$ 980,00`)
- Data de criação relativa ("Hoje", "Ontem", "5d atrás")
- **Menu de 3 pontos** com ações:
  - **Editar** → `/proposals/:id/edit`
  - **Duplicar** → cria cópia em rascunho
  - **Enviar** (apenas em rascunho) → muda status para `sent` e abre modal com link público
  - **Compartilhar** → modal com URL pública para copiar
  - **Excluir** (com confirmação)

> 💡 **Dica:** Clique no cartão para abrir os detalhes (`/proposals/:id`). O menu de 3 pontos é só para ações rápidas.

### Drag-and-drop entre colunas

Você pode **arrastar cartões** entre colunas do Kanban, mas:
- Mover entre colunas de sistema com status diferentes (ex: arrastar uma proposta de "Rascunho" para "Aprovada") é **bloqueado** com aviso — porque colunas de sistema espelham o status real, e você não muda o status manualmente.
- Mover para uma **coluna customizada criada por você** apenas reorganiza visualmente. Quando o status muda automaticamente (ex: cliente aprova), a proposta sai da coluna customizada e volta para a coluna de sistema correspondente.

### Estado vazio

Quando não há propostas, aparece um "ghost board" com cards translúcidos e um cartão central:
- **"Crie sua primeira proposta"**
- Botão **"+ Criar Proposta"** que entra em Modo Proposta e leva para o Marketplace

---

## 11. Criar uma Nova Proposta

### Fluxo completo

1. Em `/proposals`, clique em **"+ Nova Proposta"** (ou no estado vazio, em "Criar Proposta").
2. A plataforma entra em **Modo Proposta** (banner no topo) e leva você ao **Marketplace**.
3. Use Marketplace, Mapa ou Comparador para adicionar **produtos** e **patrocínios** ao carrinho.
4. (Opcional) Selecione preços ajustados, marque itens que precisam de gravação.
5. No carrinho, vá para `/cart`.
6. **Etapa 1 (Agendamento)**: distribua as inserções e selecione um **Cliente** no painel "Dados da Agência" (obrigatório para agência) e defina sua **Comissão (%)**.
7. **Etapa 2 (Confirmação)**: revise tudo. Você verá:
   - Itens agrupados por emissora
   - Resumo financeiro completo com comissão
   - Botão **Confirmar Proposta** (em vez de "Confirmar Pedido")
8. Ao confirmar, é criada uma **proposta em rascunho** (status `draft`) e você é redirecionada para o **Editor Visual da Proposta**.

### Campos da proposta criada

A proposta nasce com:
- Número automático no formato `PROP-AAAAMMDD-NNNN`
- Slug único para a URL pública
- Snapshot de cada item: produto, emissora, preço, audiência, geo, dial/banda
- `grossAmount` (soma dos itens + custo de produção)
- `techFee` = 5% do `grossAmount`
- `agencyCommission` (%) e `agencyCommissionAmount` (R$)
- `monitoringCost` (R$ 70 × emissoras monitoradas, se ativado)
- `discountAmount` (se aplicado desconto global)
- `totalAmount` = grossAmount + techFee − discountAmount + agencyCommissionAmount + monitoringCost
- Status inicial: `draft`
- Customização visual padrão (cores E-radios, fontes Space Grotesk + Fira Sans Condensed)

### Itens customizados

Além de itens do marketplace, dentro do editor você pode adicionar **itens manuais** (sem vínculo com produto cadastrado). Para cada item customizado:
- Nome
- Tipo
- Quantidade
- Preço unitário (mínimo R$ 0,01)
- Descrição livre

> ⚠️ **Limite de preço ajustado:** ao negociar preço diferente do tabelado, o **piso é 50% do preço original**. Tentar valor menor é rejeitado pelo backend.

### Combos de emissora (quando aparecem)

Combos são pacotes pré-definidos criados por **emissoras** para acelerar montagem. Quando você navega no marketplace de uma emissora que tem combos, eles podem aparecer como "Pacote sugerido" com quantidades e descontos default já preenchidos. Você pode editar quantidade e desconto de cada item depois.

> ℹ️ **Nota:** Combos pertencem ao broadcaster. Você é apenas consumidora deles.

---

## 12. Editor Visual da Proposta

### Onde fica
- Da lista de propostas → menu de 3 pontos → **Editar**
- Direto pela URL: `/proposals/:id/edit`

### Status que aceitam edição completa

- **Rascunho (`draft`)** — edita tudo (itens, valores, customização, validade, cliente).
- **Devolvida (`returned`)** — quando uma proposta foi reaberta para revisão; também aceita edição completa.

### Status que aceitam apenas edição cosmética

Para propostas em `sent`, `viewed`, `approved`, `rejected`, `expired` ou `converted`, você pode editar **apenas**:
- Título
- Descrição
- Personalização visual (cores, fontes, capas, KPIs)
- Notas internas

Tentar mexer em itens, comissão, monitoramento, desconto, validade ou cliente nesses estados retorna erro:
> "Proposta em estado X não pode ter itens, valores, cliente ou validade alterados"

### Painel de Personalização Visual

#### Cores
- Cor primária, secundária, fundo, texto, accent (5 cores em hex)

#### Fontes
- Fonte de títulos
- Fonte de corpo

#### Imagens
- **Logo** — upload (JPG/PNG/WebP, até 5MB)
- **Imagem de capa**

#### KPIs dinâmicos (até 8)
Cada KPI tem:
- Valor (ex: "100K")
- Label (ex: "Ouvintes diários")
- Cor
- Visível (sim/não)

#### Métricas dinâmicas (até 6)
Cada métrica tem:
- Valor
- Label
- Ícone
- Visível

#### Seções customizadas (blocos livres)
Você pode adicionar quantos quiser dos seguintes tipos:
- **Rich Text** (HTML formatado)
- **Imagem** (com legenda)
- **Vídeo** (URL embed + legenda)
- **Galeria** (várias imagens com legendas)
- **Divisor** (linha separadora)

Cada seção tem `order` (posição) e `visible`. Pode reordenar e ocultar individualmente.

#### Seção "Sobre a Agência"
Toggle on/off + descrição rich-text + website + e-mail + telefone + posição (início ou fim do documento).

#### Layout em linhas
Permite organizar quais seções ficam lado a lado em cada linha. Ex: `[['header'], ['kpis', 'metrics'], ['map'], ['table']]`.

#### Esconder seções
Toggle de visibilidade para qualquer seção do template.

### Customização de textos

Cada bloco do template aceita texto customizado:
- `headerTitle`, `headerSubtitle`
- `briefingTitle`, `briefingContent` (HTML rico)
- `videoUrl`, `videoCaption`
- `mapTitle`, `tableTitle`
- `notesTitle`, `notesContent` (HTML rico)
- `footerNote`

### Auto-save

Mudanças na customização são salvas automaticamente. Mudanças em itens/valores requerem clique em **Salvar**.

### Edição de itens da proposta

Lista cada item com:
- Nome do produto
- Emissora
- Quantidade (editável)
- Preço unitário (editável, com piso de 50%)
- Motivo do ajuste
- Toggle "Precisa de gravação" (R$ 50 extras)
- Botão remover

Botão **+ Adicionar item personalizado** abre modal para criar item livre.

### Desconto global

| Campo | Descrição |
|-------|-----------|
| Tipo | Percentual ou Fixo |
| Valor | Número (% ou R$) |
| Motivo | Texto livre justificativo |

Aplica-se sobre o `grossAmount` ANTES de somar comissão e monitoramento.

### Validade (`validUntil`)

Data limite para o cliente responder. Após essa data:
- Cron noturno move para status `expired`
- Cliente recebe HTTP 410 ao tentar abrir o link público
- Conversão em pedido fica bloqueada

### Contrato / Condições de Pagamento

Painel opcional para emitir um **PI (Pedido de Inserção) com condições contratuais**:
- Número do contrato (gerado automaticamente)
- Snapshot do cliente e da agência
- Vigência (início e fim)
- Valor total
- Quantidade de parcelas
- Data do primeiro vencimento
- Procedimento ("Nota Fiscal", "Boleto", etc.)
- Intervalo entre parcelas (dia, semana, quinzena, mês)
- Dia de vencimento (1-31)
- Lista de parcelas geradas (botão **Gerar Parcelas**)
- Descrição com tags

Esse contrato é copiado para o pedido quando a proposta vira campanha.

---

## 13. Enviar, Compartilhar e Acompanhar a Proposta

### Enviar

Pelo menu da proposta (3 pontos) ou dentro do detalhe → botão **Enviar**.

O que acontece:
1. Status muda de `draft` para `sent`.
2. Campo `sentAt` é preenchido.
3. Histórico de status registra o envio.
4. Versão snapshot é criada automaticamente.
5. Modal exibe a **URL pública** no formato `https://[seu-dominio]/p/:slug`.

> 💡 **Dica:** Copie o link e envie ao cliente por e-mail ou WhatsApp. Não há envio automático de e-mail ao cliente — você é responsável por entregar o link.

### Compartilhar

Mesma URL pública. Modal com botão **Copiar** que dá feedback visual ("Copiado!").

### Acompanhar

Sinais que você recebe automaticamente:

| Evento | Como você fica sabendo |
|--------|------------------------|
| Cliente abriu pelo link | E-mail "Proposta visualizada!" + status muda para `viewed` |
| Cliente comentou em uma seção | E-mail "Novo comentário na proposta" + comentário aparece no detalhe |
| Cliente aprovou | E-mail "Proposta aprovada!" + status muda para `approved` |
| Cliente recusou | E-mail "Proposta recusada!" + status muda para `rejected` (com a observação dele) |
| Validade expirou sem resposta | Status muda automaticamente para `expired` |

### Detalhe da proposta (`/proposals/:id`)

Inclui:
- Cabeçalho com número, status, datas
- Itens
- Resumo financeiro completo
- **Histórico de status** (linha do tempo com quem fez cada ação e quando)
- **Tracking de visualizações**: quantidade total, última visualização, sessões com duração e profundidade de scroll
- **Comentários** (organizados por seção da proposta)
- Link público para abrir em nova aba
- Botão **Converter em Pedido** (aparece quando status = `approved`)
- Botão **Exportar XLSX**
- Botão **Definir PIN de proteção**

### Proteção por PIN (opcional)

No detalhe da proposta, você pode ativar **proteção PIN** e definir:
- PIN numérico (armazenado como hash bcrypt)
- E-mail autorizado (opcional)
- Validade da proteção

Quando ativada:
- O cliente, ao abrir a URL pública, vê apenas o número e o título da proposta.
- Precisa digitar o PIN para liberar o conteúdo.
- Após 5 tentativas erradas, fica bloqueado e precisa pedir um novo PIN.

> 💡 **Dica:** Use PIN para propostas com valores sensíveis ou quando o link puder cair em mãos erradas.

---

## 14. Página Pública: como o cliente vê e responde

### URL
`https://[dominio]/p/:slug` — sem login.

### O que o cliente vê

- Capa com sua logo, cor e fonte
- Cabeçalho com título, subtítulo e número da proposta
- Briefing (HTML rico)
- KPIs (até 8)
- Métricas (até 6)
- **Mapa** com marcadores das emissoras + raios de cobertura
- **Tabela** dos itens (sem mostrar `netPrice`, dados financeiros internos da agência)
- Comissão da agência aparece como "Comissão" no resumo (ele vê o valor que vai pagar)
- Custo de produção, taxa técnica, monitoramento e desconto, se houver
- **Total final**
- Seções customizadas que você adicionou
- Sobre a Agência (se ativado)
- **Notas e termos**
- Rodapé customizado

### Ações disponíveis para o cliente

| Ação | Limite (rate limit) |
|------|---------------------|
| Visualizar a proposta | 30 requisições/min |
| Comentar em uma seção | 10/h |
| Aprovar a proposta | 3/h |
| Recusar a proposta | 3/h |
| Exportar XLSX | 5/min |
| Tentar PIN (se houver proteção) | 5/min |

### Aprovação formal

Ao aprovar, o cliente preenche:
- Nome
- E-mail
- Aceita os termos

A plataforma registra: nome, e-mail, IP, user-agent, data/hora — equivalente a uma **assinatura digital de aceite**.

### Estados especiais que o cliente vê

- **Expirada** (HTTP 410): mensagem "Esta proposta expirou".
- **Devolvida** (`returned`, HTTP 409): "Esta proposta está sob revisão pela agência. Você será notificado quando for reenviada."
- **Já respondida**: "Esta proposta já foi respondida".
- **Protegida por PIN**: tela de digitação do PIN.

---

## 15. Conversão de Proposta em Campanha

### Quando aparece

Botão **Converter em Pedido** dentro do detalhe da proposta, **somente** quando:
- Status = `approved`
- Ainda não foi convertida (`convertedOrderId` vazio)
- Validade ainda não expirou

### O que acontece

1. Plataforma cria um **Order** (pedido) usando os itens, valores, comissão, monitoramento e contrato da proposta.
2. Status do pedido nasce como `pending_contact`.
3. Cálculos do pedido:
   - `grossAmount` = igual à proposta
   - `broadcasterAmount` = 75% do `grossAmount` (vai para a emissora)
   - `platformSplit` = 20% do `grossAmount` (margem da plataforma)
   - `techFee` = 5% do `grossAmount`
   - `agencyCommission` = valor calculado da comissão
   - `monitoringCost` = R$ 70 × emissoras monitoradas
   - `totalAmount` = grossAmount + techFee + agencyCommission + monitoringCost
4. Status da proposta muda para `converted` e guarda referência ao pedido (`convertedOrderId`).
5. E-mail de "Pedido recebido" é enviado para a agência.

### Após conversão

A proposta fica congelada (não aceita mais edição financeira). Você acompanha como **campanha** em `/campaigns`. A equipe E-radios entra em contato para combinar o pagamento.

> ⚠️ **Atenção:** Conversão é **um caminho só**. Não há "desfazer". Antes de converter, certifique-se de que cliente e itens estão corretos.

---

## 16. Templates de Proposta

### Onde ficam

Acessíveis no editor de proposta (botão **Aplicar Template**) e quando criando uma nova proposta.

### Tipos

- **Templates da plataforma** — disponíveis para todas as agências (criados pela equipe E-radios).
- **Templates da sua agência** — criados por você, visíveis apenas para sua conta.

### Criar template

A partir de uma proposta existente, exporte sua customização atual como template:
- Nome (obrigatório)
- Categoria (opcional, ex: "Rádio FM AM", "Promoção", "Cliente fixo")
- Customização (capturada da proposta atual)

### Editar / Excluir

- Você pode editar e excluir **apenas seus templates**.
- Templates padrão da plataforma são read-only.

### Aplicar template

Ao criar uma nova proposta com `templateId`, a customização do template é copiada para a proposta. Ajustes posteriores não afetam o template original.

> 💡 **Dica:** Mantenha 2–3 templates de marca: um "executivo" (cores sóbrias), um "criativo" (cores fortes) e um "pitch novo cliente" com mais seções de "Sobre a Agência" e KPIs.

---

## 17. Versionamento de Propostas

### Como funciona

A cada mudança relevante, a plataforma cria automaticamente uma **versão snapshot** da proposta:

| Evento | Tipo de versão |
|--------|----------------|
| Criação inicial | `manual` ("Versão inicial") |
| Edição manual via editor | `auto_update` |
| Envio (rascunho → enviada) | `auto_send` ("Proposta enviada") |
| Antes de restaurar versão antiga | `manual` ("Antes de restaurar") |

### Onde acessar

No detalhe da proposta → aba/painel **Versões**.

### O que cada versão guarda

- Título
- Itens completos
- Valores (`grossAmount`, `techFee`, `productionCost`, comissão, monitoramento, desconto, total)
- Customização visual completa
- Quem fez (`changedBy`)
- Quando (`createdAt`)
- Tipo (`changeType`)
- Nota opcional (`changeNote`)

### Restaurar versão

Botão **Restaurar** em qualquer versão antiga aplica o snapshot na proposta atual. A versão atual é salva antes da restauração para não perder histórico.

### Limite

A plataforma mantém as **últimas 20 versões**. Quando excede, as mais antigas são removidas automaticamente.

---

## 18. Analytics de Propostas

### Onde fica
- Dentro de **Propostas** → botão **Analytics**
- Rota: `/proposals/analytics`

### Filtro de período

Padrão: 30 dias. Pode mudar via parâmetro (7, 30, 90 dias, etc.).

### O que aparece

#### Hero Cards (ciclo de vida)

| Métrica | Cálculo |
|---------|---------|
| **Enviadas** | sent + viewed + approved + rejected + expired + converted |
| **Aprovadas** | approved + converted |
| **Recusadas** | rejected |

#### Funil de conversão

Sent → Viewed → Responded → Approved.

#### KPIs financeiros

- Valor total em propostas no período
- Valor aprovado
- Valor recusado
- Quantidade de propostas aprovadas
- **Tempo médio de resposta** (em horas, calculado entre `sentAt` e `respondedAt`)
- **Taxa de conversão** (% aprovadas/enviadas)

#### Atividade recente

Lista das últimas 50 propostas com status, valor, datas-chave (criação, envio, visualização, resposta).

#### Distribuição por status

Gráfico mostrando quantas propostas existem em cada status no período.

> 💡 **Dica:** Acompanhe a **taxa de conversão** semanalmente. Se cair abaixo de 30%, pode ser sinal de que o tom das propostas precisa ajuste, ou que o briefing pré-proposta não está alinhado com o que o cliente quer.

---

## 19. Kanban Customizado e Drag-and-Drop

### Contexto

A agência tem um Kanban próprio para o contexto **propostas**. O Kanban é compartilhado entre **toda a conta da agência** (uma só visão por agência).

### Colunas de sistema (fixas, não removíveis)

São as 7 colunas listadas em [Propostas](#10-propostas-comerciais-visão-geral-e-kanban). Refletem `status` real e mudam automaticamente quando o cliente responde.

### Colunas customizadas (até 20)

Você pode criar suas próprias colunas para organizar visualmente. Exemplos: "Aguardando briefing", "Em negociação avançada", "Cliente VIP".

#### Criar coluna

Botão **+ Nova Coluna** no Kanban abre modal com:

| Campo | Validação |
|-------|-----------|
| Nome | Obrigatório, até 40 caracteres |
| Cor | Hex `#RRGGBB` (paleta com 12 cores sugeridas) |
| Ícone | Obrigatório, escolhido entre ~32 ícones curados |

#### Editar / Excluir coluna

- Editar: muda nome, cor e ícone.
- Excluir: remove a coluna e devolve todos os cards para a coluna do status real deles.

#### Reordenar colunas

Arraste o cabeçalho da coluna para mudar a posição. A ordem é salva.

### Mover cartões

- **Sistema → Customizada**: permitido. O cartão fica visualmente parado lá até alguém interagir.
- **Customizada → Customizada**: permitido.
- **Customizada → Sistema**: cancela o "placement" e o cartão volta ao status real.
- **Sistema → Sistema com status diferente**: bloqueado (status não muda manualmente).

### Quando o status real muda

Se uma proposta estava em uma coluna customizada (ex: "Em negociação") e o cliente aprovou, a plataforma **automaticamente remove o placement** e o cartão aparece na coluna "Aprovada" do sistema.

> 💡 **Dica:** Use cores e ícones consistentes com seu fluxo. Ex: vermelho para "Risco", amarelo para "Aguardando cliente", verde para "Pronto para fechar".

---

## 20. Radio Analytics (monitoramento)

### O que é

Plataforma externa de checking de mídia que confirma se as inserções foram efetivamente veiculadas. É um serviço **opcional** com custo adicional de **R$ 70,00 por emissora** monitorada.

### Como ativar

No carrinho/proposta, ative o toggle **"Monitoramento (Radio Analytics)"** antes de confirmar.

### Regras

- Cobra apenas em emissoras com **produtos comerciais** (não em testemunhais).
- O custo é fixo R$ 70 × número de emissoras únicas no pedido.
- Aparece como linha "Monitoramento" no resumo financeiro.

### Acesso ao serviço

Menu lateral → **Radio Analytics** → abre site externo em nova aba (login separado, configurado pela equipe E-radios após contratar).

> ℹ️ **Nota:** O acesso ao painel de Radio Analytics é provisionado pela equipe E-radios. Aguarde o contato após contratar o monitoramento na sua primeira campanha.

---

## 21. Minha Conta

### Onde fica
- Avatar no canto superior direito → **Menu de Ajustes** ou **Ajustes**
- Rota: `/my-account`

### Seções

#### Dados da Agência

| Campo | Editável |
|-------|:---:|
| Nome Fantasia | Sim |
| Razão Social | Sim |
| E-mail | Não (após cadastro) |
| Telefone | Sim |
| CNPJ | Não (após cadastro) |

#### Endereço

CEP (auto-preenchimento via ViaCEP), logradouro, número, complemento, bairro, cidade, estado.

#### Segurança — Alterar Senha

| Campo | Obrigatório |
|-------|:---:|
| Senha atual | Sim |
| Nova senha (10+ chars, complexa) | Sim |
| Confirmar nova senha | Sim |

#### Segurança — 2FA

- Ativar (link de confirmação por e-mail)
- Desativar
- Gerenciar dispositivos confiáveis

#### Preferências de Notificação

A agência pode ligar/desligar e-mails para:

| Notificação | Default |
|-------------|:---:|
| Proposta aceita/recusada | Ativada |
| Atualizações dos meus pedidos | Ativada |

> 💡 **Dica:** Mantenha as duas ligadas para receber tudo que importa. Se o volume estiver alto, desligue **temporariamente** "atualizações dos meus pedidos" durante períodos de muitos pedidos simultâneos.

---

## 22. Documentação, Suporte e Contato

### Documentação na plataforma
- Rota `/docs` — manual público com guias rápidos.
- Rota `/docs/:page` — páginas específicas.

### Páginas legais
- Termos de Uso → `/terms`
- Política de Privacidade → `/policy`

### Suporte
- Formulário de **Fale Conosco** no rodapé (Footer) de qualquer página.
- E-mail da equipe E-radios (informado no rodapé).

### Conta bloqueada / Problemas operacionais

| Situação | Solução |
|----------|---------|
| Conta bloqueada | Entre em contato com a equipe E-radios |
| Pedido cancelado | Verifique o motivo no detalhe da campanha e refaça se aplicável |
| Cliente não aparece no carrinho | Cliente está inativo — ative em `/agency/clients` |
| Proposta não envia | Status já é `sent` ou `draft` está incompleto — verifique itens e cliente |
| Erro 500 ao salvar | Recarregue a página e tente de novo; se persistir, contate suporte |

---

## 23. Glossário rápido

| Termo | Significado |
|-------|-------------|
| **Marketplace** | Vitrine de emissoras aprovadas para compra |
| **Inserção** | Veiculação única de um spot |
| **Spot** | Comercial publicitário de áudio (15s/30s/45s/60s) |
| **Testemunhal** | Locutor da rádio falando sobre o anunciante (30s/60s) |
| **Patrocínio** | Vínculo mensal a um programa específico da emissora |
| **netPrice** | Preço líquido da emissora (não exibido ao cliente final da agência) |
| **unitPrice** | Preço com markup da plataforma (preço de tabela) |
| **adjustedPrice** | Preço negociado em uma proposta (mínimo 50% do unitPrice) |
| **Tech Fee** | Taxa técnica de 5% da plataforma sobre o `grossAmount` |
| **Agency Commission** | Comissão da agência, definida por ela própria, somada ao total |
| **Monitoramento** | Radio Analytics, R$ 70 por emissora |
| **Proposta** | Documento comercial gerado pela agência, com link público para o cliente final |
| **PI / Contrato** | Pedido de Inserção com condições de pagamento, gerado a partir da proposta |
| **Slug** | Identificador único na URL pública da proposta (ex: `proposta-comercial-aB3xY9pQ`) |
| **Kanban** | Quadro de cartões organizados em colunas (status + colunas customizadas) |

---

> 📬 **Precisa de ajuda?** Use o formulário de contato no rodapé da plataforma ou entre em contato pelo e-mail da equipe E-radios.