# Modelo de dados conceitual

## 1. Aviso

Este documento descreve a interpretação desejada. O esquema real deve ser registrado separadamente em `docs/ACTUAL_SCHEMA.md`.

Não migrar o banco original apenas para fazê-lo coincidir com este modelo.

---

## 2. Entidades essenciais

### `scrape_run`

Representa uma execução de coleta.

Campos desejáveis:

- `run_id`;
- `started_at`;
- `finished_at`;
- `status`;
- `scraper_version`;
- `configuration_hash`;
- páginas e erros;
- contagens de anúncios e fotos;
- resumo de status HTTP.

### `listing`

Identidade do anúncio na fonte.

- identificador interno;
- identificador do portal;
- URL canônica;
- primeira e última aparição;
- status;
- anunciante;
- vínculo com imóvel provável.

### `listing_observation`

Estado do anúncio em uma data de coleta.

- data;
- título e descrição;
- preço;
- condomínio e IPTU;
- áreas separadas;
- quartos, suítes, banheiros e vagas;
- endereço bruto;
- status bruto;
- hash do conteúdo;
- referência ao HTML.

Não sobrescrever histórico.

### `photo`

- anúncio ou observação;
- URL;
- caminho local;
- posição;
- hash criptográfico;
- hash perceptual;
- dimensões;
- status de download.

A posição da primeira foto deve ser preservada, pois ela é usada na auditoria visual de disponibilidade.

### `property_candidate`

Hipótese de imóvel físico comum a um ou mais anúncios.

- região e endereço normalizados;
- tipologia;
- planta original provável;
- método de deduplicação;
- confiança;
- estado de revisão.

Não converter correspondência probabilística em certeza.

---

## 3. Localização no DF

A normalização deve suportar:

- região administrativa;
- bairro;
- SHCES;
- quadra;
- bloco;
- conjunto;
- QC;
- rua;
- lote;
- unidade;
- condomínio;
- latitude e longitude;
- precisão da geocodificação.

Não forçar todos os endereços ao modelo rua/número.

---

## 4. Áreas

Manter separadas:

- privativa;
- útil;
- construída;
- total;
- terreno;
- ampliada declarada.

Preservar valor bruto e fonte.

No Mangueiral, áreas anunciadas frequentemente misturam área original e ampliação. Não calcular preço por m² sem validação.

---

## 5. Quartos e planta

Separar:

- quartos anunciados;
- quartos utilizáveis;
- suítes;
- dependência;
- escritório;
- quarto adaptado;
- planta original provável;
- confiança da classificação.

No Mangueiral, a planta original de três quartos é um filtro obrigatório.

---

## 6. Status e disponibilidade

Campos derivados desejáveis:

- ativo na última coleta;
- inativo;
- vendido na primeira foto;
- vendido na descrição;
- republicado;
- duplicata provável;
- conflito de dados;
- data da última evidência.

Ausência não é prova de venda.

---

## 7. Deduplicação

### Sinais fortes

- mesmo ID da fonte;
- endereço e unidade;
- conjunto de imagens;
- implantação idêntica;
- telefone e descrição coincidentes.

### Sinais moderados

- quadra/bloco/QC;
- área, preço e quartos;
- texto semelhante;
- datas próximas;
- fotos parcialmente coincidentes.

### Regras

- preservar anúncios originais;
- criar grupo de imóvel provável;
- registrar confiança e método;
- permitir revisão manual;
- não fundir irreversivelmente.

---

## 8. Histórico de preço

Derivar por anúncio e por imóvel provável.

Registrar:

- primeiro preço;
- preço atual;
- reduções e aumentos;
- republicações;
- mudanças simultâneas de área, quartos ou descrição;
- períodos de ausência.

Não interpretar retirada como venda.

---

## 9. Qualidade dos dados

Métricas mínimas:

- nulos por campo;
- preços implausíveis;
- áreas implausíveis;
- divergência entre título e campos;
- cobertura por dia;
- falhas por página;
- fotos ausentes;
- duplicidade estimada;
- anúncios com selo de vendido;
- mudanças de ID;
- distribuição por região e tipologia.

---

## 10. Camada derivada

Sugestão:

```text
data/derived/
├── listings_clean.parquet
├── observations_clean.parquet
├── photos_index.parquet
├── property_candidates.parquet
├── price_history.parquet
├── locations_normalized.parquet
└── quality_metrics.parquet
```

Registrar versão do código, data, banco de origem e contagens de entrada/saída.

---

## 11. Implementação aditiva v2 — 22/07/2026

Com autorização explícita do usuário e backup consistente, parte deste modelo foi incorporada ao banco operacional sem remover dados:

- campos brutos preservados e colunas normalizadas em `listings`;
- `stable_content_hash` separado do hash bruto legado;
- `is_primary_gallery`, origem e revisão em `photos`;
- `availability_observations` para evidência de disponibilidade;
- `data_quality_issues` para quarentenas reversíveis;
- `listing_change_events` para mudanças materiais futuras;
- escopo e configuração das futuras execuções em `crawl_runs`;
- visões `v_primary_photos`, `v_open_data_quality_issues` e `v_listing_current_availability`.

As tabelas e colunas antigas continuam preservadas para reprodução histórica.