Normalização dos dados de Localização

[samuelveigarangel]

🎯 Nova funcionalidade: Base Canônica de Localidades (Country, State, City)

Objetivo

Criar uma base canônica, verificada e referenciável de localidades (Country, State, City), garantindo consistência, deduplicação e confiabilidade dos dados usados pelos modelos de negócio.

---

🏗️ Arquitetura de Dados (Ajuste fino)

1. Dados Canônicos (Reference Data)

Dados oficiais e confiáveis.

• Country
• State
• City

Fontes:

• Countries States Cities Database
  https://github.com/dr5hn/countries-states-cities-database
• GeoNames
  https://www.geonames.org/

---

2. Dados Sujos (Raw)

Exemplos:

• nomes incorretos
• HTML embutido
• dados incompletos

---

3. Dados de Negócio

Entidades como:

• Instituições
• Organizações
• Autores
• Outros modelos correlacionados

📌 Regra:
Esses dados só podem apontar para localidades verificadas (canônicas).

---

🔖 Usar Status explícito de processamento nos modelos de localidade

RAW       -> dado bruto, sem tratamento
CLEANED   -> dado pré-limpo
MATCHED   -> associado a um registro canônico
VERIFIED  -> validado oficialmente
REJECTED  -> inválido ou impossível de resolver

🌍 Country

Etapa 1 - Pré-limpeza

Antes de qualquer matching:

• remover HTML (<i>, <b>, etc)
• remover e-mails
• remover strings numéricas

normalizar: lower trim unaccent

Etapa 2 – Deduplicação interna

Objetivo: eliminar variações semânticas e erros comuns antes do matching externo.

Exemplo de entradas:

Brazil
Brasil
Brazi1
Brazil.

Resultado normalizado:
brazil

Etapa 3 - matching com GeoNames

• match por nome
• match por iso
• fuzzy como fallback
  ```cleaned_country -> country_iso2``

Etapa 4 - Tradução

1. Armazene apenas inglês
2. Traduza apenas na camada de apresentação
3. Autocomplete: traduz input -> inglês -> busca -> exibe -> idioma do usuário.

🗺️ State

❗ Um estado nunca pode ser resolvido sem país

Etapa 1- Pré-limpeza

Antes de qualquer matching:

• remover HTML (<'i>, <'b>, etc)
• remover emails
• remover strings númericas
• normalizar: lower + trim + unaccent?

Etapa 2 - Agrupamento por nome limpo

<i>Córdoba<
Cordoba
CÓRDOBA

vira:

cordoba

Etapa 3 - Seleção do registro "vencedor"

• Durante a limpeza do nome, optar pelo dado mais completo (País resolvido + acronimo válido)
  4.1 NÃO confie só no nome do estado
  Ex:
  Córdoba (Argentina)
  Córdoba (Espanha)
  San José (vários países)
• Nunca criar estado sem país

City

Etapa 1- Pré-limpeza

Antes de qualquer matching:

• remover HTML (<'i>, <'b>, etc)
• remover emails
• remover strings númericas
• normalizar: lower + trim + unaccent?

Criação de novos dados (prevenção definitiva)

Regra na criação de organização ou outro modelo que correlaciona locations:

• Atribuir apenas localização completa.
• Autocomplete só com verified
• Não permitir criação de localidades manualmente. Solicitar?