# Host Studio · Schema do Output do Motor

> **Schema completo dos 88 campos que o motor deve produzir.**
> Validado por `hoststudio_validator.py` contra o HTML do relatório.

---

## 1. CONTEXTO

O motor de análise produz um JSON estruturado que é salvo em `reports.insights` (jsonb) e renderizado pelo `hoststudio_relatorio.html` substituindo cada `data-field`.

Toda chave abaixo é obrigatória, exceto as marcadas `[opcional]`.

---

## 2. SCHEMA

### 2.1 Identificação e metadados

```json
{
  "rpt.id":                "uuid do report",
  "rpt.cliente_nome":      "Zélia Correia Souza",
  "rpt.cliente_cpf":       "000.001.001-00",
  "rpt.imovel_nome":       "Chácara Canguera",
  "rpt.imovel_tipo":       "Chácara · 3 quartos · 12 hóspedes",
  "rpt.imovel_cidade":     "São Roque, SP",
  "rpt.periodo":           "Mai/24 a Abr/26 (24 meses)",
  "rpt.periodo_inicio":    "2024-05",
  "rpt.periodo_fim":       "2026-04",
  "rpt.periodo_meses":     24,
  "rpt.gerado_em":         "Gerado em Maio/2026",
  "rpt.versao_motor":      "2.3.5"
}
```

### 2.2 Receita histórica da propriedade

```json
{
  "receita.faturamento_total":    "R$ 45.300",
  "receita.faturamento_mensal":   "R$ 7.550",
  "receita.melhor_mes":           "Outubro/2025",
  "receita.melhor_mes_valor":     "R$ 12.400",
  "receita.pior_mes":             "Junho/2025",
  "receita.pior_mes_valor":       "R$ 0",
  "receita.meses_ativos":         6,
  "receita.meses_zerados":        0
}
```

### 2.3 Mercado (compset filtrado pelo mesmo período)

```json
{
  "mercado.compset_n_imoveis":     32,
  "mercado.geral_n_imoveis":       1222,
  "mercado.adr_compset":           "R$ 830",
  "mercado.adr_geral":             "R$ 695",
  "mercado.ocupacao_compset":      "62%",
  "mercado.ocupacao_geral":        "48%",
  "mercado.receita_media_compset": "R$ 8.100",
  "mercado.receita_media_geral":   "R$ 5.400"
}
```

### 2.4 ADR e Ocupação da propriedade

```json
{
  "propriedade.adr":               "R$ 854",
  "propriedade.ocupacao":          "61%",
  "propriedade.diarias_vendidas":  165,
  "propriedade.dias_disponiveis":  270
}
```

### 2.5 Deltas (mesmo período)

```json
{
  "delta.adr_compset":             "+3%",
  "delta.adr_geral":               "+23%",
  "delta.ocupacao_compset":        "-1%",
  "delta.ocupacao_geral":          "+27%",
  "delta.receita_compset":         "-7%",
  "delta.receita_geral":           "+40%"
}
```

### 2.6 Charts (arrays mensais)

```json
{
  "chart.meses": ["Mai/24", "Jun/24", ..., "Abr/26"],

  "chart.adr_propriedade":  [854, 0, 920, ...],
  "chart.adr_compset":      [820, 0, 850, ...],
  "chart.adr_geral":        [680, 0, 700, ...],

  "chart.ocupacao_propriedade": [62, 0, 75, ...],
  "chart.ocupacao_compset":     [60, 0, 70, ...],
  "chart.ocupacao_geral":       [45, 0, 55, ...],

  "chart.receita_propriedade":  [12400, 0, 7800, ...],
  "chart.receita_compset":      [9800, 0, 8100, ...],
  "chart.receita_geral":        [7200, 0, 6300, ...]
}
```

### 2.7 Concorrentes (top 5)

```json
{
  "concorrentes": [
    {
      "nome":         "Concorrente A",
      "adr":          "R$ 920",
      "ocupacao":     "68%",
      "rating":       "4.8",
      "diferencial":  "Piscina aquecida + hidromassagem"
    },
    /* ... até 5 itens */
  ]
}
```

### 2.8 Sazonalidade

```json
{
  "sazonalidade.alta":     ["Dezembro", "Janeiro", "Julho"],
  "sazonalidade.baixa":    ["Maio", "Junho", "Agosto"],
  "sazonalidade.pico":     "Dezembro",
  "sazonalidade.pico_valor": "82% ocupação"
}
```

### 2.9 Insights — 9 cards (passado observado)

```json
{
  "insight.resumo_executivo":     "Texto · 80-150 palavras",
  "insight.mercado_resumo":       "Texto · 80-150 palavras",
  "insight.sazonalidade":         "Texto · 80-150 palavras",
  "insight.posicionamento":       "Texto · 80-150 palavras",
  "insight.pontos_fortes":        "Texto · cruzar briefing × compset",
  "insight.oportunidades":        "Texto · gaps acionáveis",
  "insight.comodidades":          "Texto · tem/não tem vs mercado",
  "insight.calendario":           "Texto · datas e janelas",
  "insight.conclusao":            "Texto · 100-150 palavras"
}
```

#### Ações (lista estruturada para cards)

```json
{
  "insight.acoes_lista": [
    {
      "titulo": "Revisar fotos profissionais",
      "impacto": "alto",
      "esforco": "baixo",
      "prazo":   "30 dias"
    },
    /* ... 3-6 itens */
  ]
}
```

### 2.10 Previsão — 4 KPIs + tabela de cenários

```json
{
  "previsao.receita_anual_p25":      "R$34k",
  "previsao.receita_anual_p50":      "R$108k",
  "previsao.receita_anual_p50_full": "R$107.939",
  "previsao.receita_anual_p75":      "R$291k",
  "previsao.receita_anual_p90":      "R$501k",
  "previsao.intervalo":              "Intervalo: R$34k – R$291k",
  "previsao.mensal_p50":             "R$8.994/mês",
  "previsao.adr_medio":              "R$1.381",
  "previsao.ocupacao_media":         "20%",
  "previsao.imoveis_ref":            "baseado em 40 imóveis"
}
```

### 2.11 Previsão — dados mensais

```json
{
  "previsao.meses": [
    {
      "mes":        "Jan",
      "avg_occ":    61.7,
      "n_listings": 44,
      "adr_25":     1357.2,
      "adr_50":     1934.7,
      "adr_75":     3188.5,
      "adr_90":     4260.7,
      "occ_25":     26.6,
      "occ_75":     85.3,
      "rev_25":     13852.7,
      "rev_50":     31944.2,
      "rev_75":     46946.0,
      "rev_90":     66382.2
    },
    /* ... 12 itens (Jan a Dez) */
  ]
}
```

### 2.12 Previsão — 3 insights cruzados

```json
{
  "previsao.insight_cenarios":          "Texto · explicar 4 cenários",
  "previsao.insight_oportunidades_mes": "Texto · meses fortes/zerados",
  "previsao.insight_acelerar":          "Texto · caminho P50 → P75"
}
```

### 2.13 Comodidades (briefing × compset)

```json
{
  "comodidades.tem": [
    { "nome": "Piscina",       "percent_compset": 85 },
    { "nome": "Churrasqueira", "percent_compset": 92 },
    { "nome": "Hidromassagem", "percent_compset":  3 }
  ],
  "comodidades.nao_tem_desejadas": [
    { "nome": "Sauna",         "percent_compset": 28 },
    { "nome": "Forno de pizza","percent_compset": 22 }
  ]
}
```

---

## 3. VALIDAÇÃO

Executar:

```bash
python3 hoststudio_validator.py
```

Output esperado:
```
✓ Tudo OK — HTML alinhado com o schema esperado
```

Se mostrar campos faltando ou tipos errados, **corrigir antes de subir**.

---

## 4. CAMPOS OPCIONAIS

Marcados com `[opcional]` no código:

- `insight.posicionamento_mercado` (legado, sinônimo de `posicionamento`)
- `insight.acoes` (string concatenada, redundante com `acoes_lista`)

---

## 5. EXEMPLO DE OUTPUT COMPLETO

Ver `samples/insights_exemplo.json` no ZIP de auditoria.

---

## 6. EVOLUÇÃO DO SCHEMA

Adicionar campos novos:

1. Atualizar este documento
2. Atualizar `hoststudio_validator.py` com novo campo em `EXPECTED_SCHEMA`
3. Atualizar HTML com novo `data-field`
4. Atualizar versão em `engine_versions` (incremento MINOR)

**Remover campos**:

1. Documentar deprecação em `motor_contrato.md`
2. Marcar como `[deprecado]` por 1 release
3. Remover na versão MAJOR seguinte

---

Bom trabalho.