Add status field and data cleaning for location normalization

[Copilot]

O que esse PR faz?

Implementa base canônica para normalização de dados de localização (Country, State, City) com rastreamento explícito de status de processamento e limpeza de dados brutos.

Status field com 5 valores:

• RAW - dado bruto, sem processamento (default)
• CLEANED - pré-limpo
• MATCHED - associado a registro canônico
• VERIFIED - validado oficialmente
• REJECTED - inválido ou irresolvível

Data cleaning via clean_data() methods:

• Remove HTML tags (Django strip_tags)
• Normaliza whitespace
• Retorna None para valores None

# Uso básico
cleaned = City.clean_data("<p>São Paulo</p>")  # Returns: "São Paulo"

city = City.create(user, name="São Paulo", status="CLEANED")
state = State.create_or_update(user, name="SP", acronym="SP", status="VERIFIED")

API consistente em todos os modelos: create(), get_or_create(), create_or_update() aceitam parâmetro status.

Onde a revisão poderia começar?

1. location/models.py - função utility clean_text_data() (linhas ~20-38)
2. location/models.py - status field nos modelos City, State, Country
3. location/tests.py - test classes CityStatusTest, StateStatusTest, CountryStatusTest
4. location/migrations/0004_add_status_field.py - migração

Como este poderia ser testado manualmente?

from django.contrib.auth import get_user_model
from location.models import City, State, Country

user = get_user_model().objects.first()

# Teste 1: HTML cleaning
dirty = "<p>Test City</p>"
clean = City.clean_data(dirty)  # Retorna "Test City"

# Teste 2: Status field
city = City.create(user=user, name="Test", status="CLEANED")
assert city.status == "CLEANED"

# Teste 3: Status update
state = State.create_or_update(user=user, name="Test", status="RAW")
state = State.create_or_update(user=user, name="Test", status="VERIFIED")
assert state.status == "VERIFIED"

Algum cenário de contexto que queira dar?

Backward compatible: campo nullable com default "RAW" - registros existentes recebem o default na migração.

Shared utility: clean_text_data() elimina duplicação de código entre City, State e Country.

Migration safety: hardcoded choices na migração previnem quebra se LOCATION_STATUS mudar no futuro.

21 novos testes adicionados. CodeQL scan: 0 alertas.

Quais são tickets relevantes?

Issue sobre normalização de dados de localização (Country, State, City).

Referências

• Django strip_tags: https://docs.djangoproject.com/en/stable/ref/utils/#django.utils.html.strip_tags
• GeoNames: https://www.geonames.org/
• Countries States Cities Database: https://github.com/dr5hn/countries-states-cities-database

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Normalização dos dados de Localização</issue_title>
<issue_description>## 🎯 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?</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Normalização dos dados de Localização #1250

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.