# Esquema físico do banco `dfimoveis.sqlite3`

> **Atualização de 22/07/2026:** as seções históricas deste documento descrevem o schema v1. A migração aditiva v2 descrita na seção final prevalece para consultas atuais.

## 1. Escopo e identificação do snapshot

Este documento descreve o esquema observado e revalidado em 21 de julho de 2026. Ele não altera o modelo conceitual de `docs/DATA_MODEL.md` e não atribui significado não comprovado às colunas.

| Item | Valor |
|---|---|
| Caminho | `dfimoveis_data/dfimoveis.sqlite3` |
| Tamanho | 9.478.144 bytes |
| SHA-256 | `bfbbdd09e88f76afd917ebd981b848b9321aeb5fc0602f712645d33e1a5ea76c` |
| Data de referência | `2026-07-21` |
| Codificação | UTF-8 |
| `journal_mode` persistido | WAL |
| Páginas | 2.314 páginas de 4.096 bytes; `freelist_count = 2` |
| `user_version` / `application_id` | 0 / 0 |
| Método de abertura | URI `mode=ro`, `PRAGMA query_only = ON` e transação de leitura |

Como este arquivo é atualizado pelo scraper, não foi usado `immutable=1`. `PRAGMA quick_check` retornou `ok` e `PRAGMA foreign_key_check` não retornou violações. Nenhum sidecar foi removido.

## 2. Visão geral

O banco possui cinco tabelas da aplicação e a tabela interna `sqlite_sequence`. Não há views nem triggers. Os quatro índices existentes são autoíndices criados por chaves primárias ou restrições `UNIQUE`.

```mermaid
erDiagram
    listings ||--|{ listing_history : "listing_id"
    listings ||--|{ listing_searches : "listing_id"
    listings ||--|{ photos : "listing_id"
    crawl_runs {
        INTEGER id PK
        TEXT started_at
        TEXT finished_at
        TEXT status
        TEXT stats_json
    }
    listings {
        TEXT listing_id PK
        TEXT url
        REAL price_brl
        REAL area_m2
        TEXT first_seen_at
        TEXT last_seen_at
        TEXT content_hash
    }
    listing_history {
        INTEGER id PK
        TEXT listing_id FK
        TEXT captured_at
        TEXT content_hash
        TEXT data_json
    }
    listing_searches {
        TEXT listing_id PK,FK
        TEXT search_url PK
        TEXT first_seen_at
        TEXT last_seen_at
    }
    photos {
        TEXT listing_id PK,FK
        TEXT source_url PK
        INTEGER ordinal
        TEXT sha256
        TEXT local_path
    }
```

`crawl_runs` não possui relacionamento físico com anúncios ou snapshots. Portanto, a execução que gerou uma linha só pode ser inferida pelos horários, não recuperada por uma chave.

### Contagens e cardinalidades observadas

| Tabela | Linhas | Interpretação física |
|---|---:|---|
| `crawl_runs` | 20 | Execuções do coletor |
| `listings` | 161 | Identidades de anúncios e seu estado corrente |
| `listing_history` | 562 | Estados distintos dos anúncios por hash |
| `listing_searches` | 161 | Vínculos entre anúncio e URL de busca |
| `photos` | 7.363 | Mídias associadas diretamente aos anúncios |
| `sqlite_sequence` | 2 | Sequências internas de tabelas `AUTOINCREMENT` |

No snapshot avaliado:

- cada anúncio está ligado a exatamente uma URL de busca;
- cada anúncio possui de 1 a 4 registros em `listing_history`;
- cada anúncio possui de 5 a 79 linhas em `photos`;
- não há órfãos nas três relações com `listings`;
- o hash corrente de cada anúncio possui registro correspondente no histórico;
- grande parte dos snapshots adicionais reflete instabilidade de campos contaminados, sobretudo `creci`, e não mudança imobiliária real.

## 3. Dicionário de tabelas

### 3.1 `crawl_runs`

Representa execuções técnicas do coletor. Não registra fonte, versão do scraper, configuração, texto de erro ou relacionamento direto com os itens coletados.

| Coluna | Tipo | Nulo? | Chave/default | Interpretação |
|---|---|---:|---|---|
| `id` | INTEGER | Não | PK, `AUTOINCREMENT` | Identificador da execução; a PK inteira atribui um valor quando omitido |
| `started_at` | TEXT | Não | — | Início em ISO 8601, observado em UTC |
| `finished_at` | TEXT | Sim | — | Término em ISO 8601 |
| `status` | TEXT | Não | — | Estado textual da execução; `ok` e `failed` foram observados |
| `stats_json` | TEXT | Não | `'{}'` | Contadores técnicos em JSON |

As estruturas JSON observadas são válidas. Além das chaves originais, execuções recentes também registram `photos_skipped`.

### 3.2 `listings`

Representa a identidade do anúncio no portal e uma cópia mutável de seu estado mais recente. Não representa um imóvel físico deduplicado.

| Coluna | Tipo | Nulo? | Chave/default | Interpretação e ressalvas |
|---|---|---:|---|---|
| `listing_id` | TEXT | Sim no DDL; não observado | PK | Identificador do anúncio no portal; todos os valores atuais têm 6–7 dígitos. Por peculiaridade do SQLite, PK textual sem `NOT NULL` explícito merece validação na aplicação |
| `url` | TEXT | Não | — | URL do anúncio |
| `title` | TEXT | Sim | — | Título extraído |
| `description` | TEXT | Sim | — | Descrição curta extraída; não é o HTML bruto completo |
| `transaction_type` | TEXT | Sim | — | Tipo da transação; somente `venda` no snapshot |
| `property_type` | TEXT | Sim | — | Tipo anunciado; `apartamento` ou `casa` |
| `price_brl` | REAL | Sim | — | Preço anunciado em reais; sujeito a erros de escala |
| `condominium_brl` | REAL | Sim | — | Condomínio anunciado; periodicidade não está formalizada |
| `iptu_brl` | REAL | Sim | — | IPTU anunciado; periodicidade não está formalizada |
| `area_m2` | REAL | Sim | — | Uma única área em m², sem indicar se é útil, privativa, construída, total ou terreno |
| `bedrooms` | INTEGER | Sim | — | Quartos anunciados, não a planta original comprovada |
| `suites` | INTEGER | Sim | — | Suítes anunciadas |
| `parking_spaces` | INTEGER | Sim | — | Vagas anunciadas |
| `address` | TEXT | Sim | — | Texto de endereço; fortemente contaminado pela página na coleta atual |
| `neighborhood` | TEXT | Sim | — | Bairro; fortemente contaminado pela página na coleta atual |
| `city` | TEXT | Sim | — | Cidade; 100% nula atualmente |
| `state` | TEXT | Sim | — | UF; 100% nula atualmente |
| `advertiser_name` | TEXT | Sim | — | Nome do anunciante; 100% nulo atualmente |
| `advertiser_code` | TEXT | Sim | — | Código do anunciante; parte relevante dos valores está contaminada |
| `creci` | TEXT | Sim | — | Registro do anunciante; parte relevante dos valores está contaminada |
| `latitude` | REAL | Sim | — | Latitude; 100% nula atualmente |
| `longitude` | REAL | Sim | — | Longitude; 100% nula atualmente |
| `published_at` | TEXT | Sim | — | Data publicada pelo portal; 100% nula atualmente |
| `first_seen_at` | TEXT | Não | — | Primeira observação do anúncio |
| `last_seen_at` | TEXT | Não | — | Última observação do anúncio |
| `inactive_at` | TEXT | Sim | — | Momento de inativação inferida pelo coletor; 100% nulo atualmente |
| `content_hash` | TEXT | Sim | — | SHA-256 do conteúdo normalizado usado para detectar mudança |
| `raw_html_path` | TEXT | Sim | — | Caminho relativo para o HTML bruto do anúncio |
| `extra_json` | TEXT | Não | `'{}'` | JSON adicional; contém apenas `json_ld`, um array vazio nos 156 anúncios |

Exemplo não sensível de identidade: o anúncio `1026522` aponta para uma URL sob `www.dfimoveis.com.br` e para um HTML em `raw/listing/1026522/...html.gz`.

### 3.3 `listing_history`

Representa estados distintos de um anúncio, não cada tentativa ou observação do coletor.

| Coluna | Tipo | Nulo? | Chave/default | Interpretação |
|---|---|---:|---|---|
| `id` | INTEGER | Não | PK, `AUTOINCREMENT` | Identificador do estado histórico; a PK inteira atribui um valor quando omitido |
| `listing_id` | TEXT | Não | FK | Anúncio ao qual o estado pertence |
| `captured_at` | TEXT | Não | — | Momento em que o estado foi capturado |
| `content_hash` | TEXT | Não | `UNIQUE` com `listing_id` | Hash que impede repetir um estado idêntico para o anúncio |
| `data_json` | TEXT | Não | — | Snapshot JSON dos principais campos extraídos |

`data_json` é JSON válido em todas as 156 linhas. Ele contém os campos correntes de conteúdo, mas não contém `first_seen_at`, `last_seen_at`, `inactive_at`, `raw_html_path` ou uma referência à execução. Como a restrição é `UNIQUE(listing_id, content_hash)`, observações repetidas sem mudança não geram novos snapshots.

### 3.4 `listing_searches`

Tabela de associação entre anúncio e consulta de busca que o encontrou.

| Coluna | Tipo | Nulo? | Chave/default | Interpretação |
|---|---|---:|---|---|
| `listing_id` | TEXT | Não | PK parcial, FK | Anúncio |
| `search_url` | TEXT | Não | PK parcial | URL/configuração da busca |
| `first_seen_at` | TEXT | Não | — | Primeira observação nessa busca |
| `last_seen_at` | TEXT | Não | — | Última observação nessa busca |

A chave primária composta é `(listing_id, search_url)`. Há duas URLs distintas no banco, uma para apartamentos de três quartos no Cruzeiro Novo e outra para casas anunciadas com três ou quatro quartos no Jardins Mangueiral.

### 3.5 `photos`

Representa arquivos de mídia associados diretamente ao anúncio. A tabela não preserva associação por snapshot.

| Coluna | Tipo | Nulo? | Chave/default | Interpretação |
|---|---|---:|---|---|
| `listing_id` | TEXT | Não | PK parcial, FK | Anúncio |
| `ordinal` | INTEGER | Não | — | Ordem da imagem no anúncio |
| `source_url` | TEXT | Não | PK parcial | URL de origem da imagem |
| `sha256` | TEXT | Sim | — | Hash do arquivo baixado |
| `mime_type` | TEXT | Sim | — | Tipo MIME detectado |
| `bytes` | INTEGER | Sim | — | Tamanho do arquivo |
| `local_path` | TEXT | Sim | — | Caminho relativo sob `dfimoveis_data/` |
| `first_seen_at` | TEXT | Não | — | Primeira observação da mídia |
| `last_seen_at` | TEXT | Não | — | Última observação da mídia |

A chave primária é `(listing_id, source_url)`, e não `(listing_id, ordinal)`. Não há ordinais repetidos dentro de um anúncio na amostra atual. Exemplo de caminho: `photos/1026522/001_9d7f11205f0a4a3f.jpg`.

### 3.6 `sqlite_sequence`

Tabela interna do SQLite que mantém as sequências `AUTOINCREMENT` de `crawl_runs` e `listing_history`. Não é entidade do domínio.

## 4. Chaves, índices e integridade referencial

| Índice | Tabela | Origem | Colunas lógicas |
|---|---|---|---|
| `sqlite_autoindex_listings_1` | `listings` | PK | `listing_id` |
| `sqlite_autoindex_listing_history_1` | `listing_history` | `UNIQUE` | `listing_id`, `content_hash` |
| `sqlite_autoindex_listing_searches_1` | `listing_searches` | PK | `listing_id`, `search_url` |
| `sqlite_autoindex_photos_1` | `photos` | PK | `listing_id`, `source_url` |

As FKs de `listing_history`, `listing_searches` e `photos` apontam para `listings(listing_id)`, com `NO ACTION` para atualização e exclusão. Não há índices explícitos por data, preço, região ou hash de foto. Com o volume atual isso não é um problema operacional; se a base crescer, índices analíticos devem ser criados apenas em uma camada derivada ou recomendados para uma migração aprovada, nunca adicionados ao banco original durante análise.

## 5. Correspondência com o modelo conceitual

| Conceito desejado | Implementação física | Avaliação |
|---|---|---|
| Fonte | Ausente; DF Imóveis é implícito nas URLs | Não permite múltiplas fontes com identidade segura |
| Execução de coleta | `crawl_runs` | Parcial; faltam fonte, configuração, versão e relação com itens |
| Anúncio | `listings` | Presente; estado corrente e identidade estão na mesma linha |
| Observação histórica | `listing_history` | Parcial; guarda somente conteúdo alterado, sem `run_id` |
| Imóvel físico candidato | Ausente | Nenhuma deduplicação física é persistida |
| Localização normalizada | Colunas em `listings` | Insuficiente e atualmente contaminada |
| Mídia | `photos` | Parcial; vinculada ao anúncio, não ao snapshot |
| Origem por consulta | `listing_searches` | Presente como relação anúncio–URL de busca |

## 6. Decisões de interpretação e ambiguidades

1. `listing_id` identifica um **anúncio no portal**, não um imóvel físico.
2. Uma linha de `listing_history` é um **estado de conteúdo distinto**, não prova de que o anúncio foi observado somente uma vez. Observações idênticas são condensadas em `last_seen_at`.
3. O banco ainda não contém histórico suficiente para liquidez: há quatro dias efetivos de observação e a maioria das transições é ruído de campos contaminados.
4. Anúncios diferentes com preço, área ou fotos semelhantes permanecem anúncios distintos. Não há chave de endereço/unidade nem tabela de candidatos físicos.
5. `area_m2` não deve ser usada para preço por m² até que o conceito de área seja validado por tipologia e fonte.
6. `bedrooms` é a quantidade anunciada. Ela não comprova a planta original de três quartos exigida para Jardins Mangueiral.
7. Datas com sufixo `+00:00` são tratadas como UTC. A cobertura observada vai de 13 a 21/07/2026.
8. Os campos textuais contaminados devem ser reextraídos do HTML bruto em uma camada derivada; os valores atuais não devem ser silenciosamente normalizados como se fossem corretos.

## 7. Problemas conhecidos do snapshot

- 150 de 161 endereços têm mais de 300 caracteres; 159 de 161 bairros têm mais de 100 caracteres.
- `city`, `state`, `latitude`, `longitude`, `published_at` e `advertiser_name` estão integralmente ausentes.
- 99 códigos de anunciante e 157 valores de CRECI são longos demais para o significado esperado, indicando extração contaminada.
- Há um preço de R$ 570.000.000 e uma área de 0,11 m², ambos candidatos fortes a erro de extração/escala.
- O JSON-LD reservado em `extra_json` é um array vazio em todos os 161 anúncios e não oferece uma fonte estruturada alternativa no snapshot.
- As 7.363 linhas de foto têm hash e caminho local preenchidos; isso não garante que toda imagem pertença ao imóvel.
- Hashes de foto idênticos aparecem em muitos anúncios; isso demonstra a presença de ativos genéricos e impede usar igualdade de hash como prova isolada de imóvel duplicado.
- Das 401 transições históricas, 398 alteram `creci`; somente três anúncios apresentam mudança real de preço. O histórico precisa de normalização antes de análises temporais.
- Não há como ligar formalmente anúncio/snapshot a `crawl_runs`, nem distinguir por chave a fonte se uma segunda fonte for incorporada.

---

## 12. Schema v2 — 22/07/2026

A migração foi autorizada explicitamente, executada após backup consistente e não removeu linhas ou colunas antigas.

Contagens preservadas na migração:

| Tabela legada | Linhas |
|---|---:|
| `listings` | 162 |
| `listing_searches` | 162 |
| `listing_history` | 637 |
| `photos` | 7.457 |
| `crawl_runs` | 21 |

Novas colunas:

- `listings`: `address_normalized`, `neighborhood_normalized`, `creci_normalized`, `raw_content_hash`, `stable_content_hash`;
- `photos`: `discovery_source`, `is_primary_gallery`, `review_status`;
- `crawl_runs`: `searches_json`, `config_json`, `scope_complete`.

Novas tabelas:

- `availability_observations`: evidência datada e sua fonte, sem converter selo visual em prova registral;
- `data_quality_issues`: quarentenas reversíveis, com severidade, evidência e estado;
- `listing_change_events`: eventos materiais produzidos pelo hash estável nas futuras coletas.

Novas visões:

- `v_primary_photos`;
- `v_open_data_quality_issues`;
- `v_listing_current_availability`.

Auditoria inicial:

- 3.521 fotos pertencem à galeria do próprio anúncio;
- 3.286 registros legados apontam para `/fotos/<outro_listing_id>/` e vieram de recomendações do portal;
- 650 registros restantes são ativos visuais do site ou URLs sem proprietário de anúncio;
- os 3.936 registros não primários foram preservados e marcados, não apagados;
- 15 anúncios foram normalizados para o CRECI `26903`;
- `PRAGMA quick_check` retornou `ok` após a migração.