inmobiliaria-analytics/docs/01-fase-alcance-inicial/IAI-007-webscraper/requerimientos/RF-SCR-003.md

id	title	type	epic	priority	status	project	created_date	updated_date
RF-SCR-003	Pipeline ETL y Normalizacion	Functional Requirement	IAI-007	Alta	Draft	inmobiliaria-analytics	2026-01-04	2026-01-04

RF-IA-007-003: Pipeline ETL y Normalizacion

---

Descripcion

El sistema debe procesar los datos raw extraidos de multiples fuentes, normalizarlos a un schema unificado, enriquecerlos con geocoding y cargarlos en la base de datos de propiedades.

---

Justificacion

Cada portal inmobiliario tiene su propia estructura de datos y nomenclatura. Para poder realizar analytics consistentes, los datos deben normalizarse a un schema comun con campos estandarizados.

---

Requisitos Funcionales

RF-003.1: Extraccion

ID	Requisito	Prioridad
RF-003.1.1	El sistema debe parsear HTML a JSON estructurado	Alta
RF-003.1.2	El sistema debe extraer todos los campos definidos en el schema	Alta
RF-003.1.3	El sistema debe manejar variaciones en estructura HTML	Alta
RF-003.1.4	El sistema debe almacenar raw data en storage persistente	Media

RF-003.2: Transformacion

ID	Requisito	Prioridad
RF-003.2.1	El sistema debe normalizar tipos de propiedad a enum unificado	Alta
RF-003.2.2	El sistema debe convertir precios a formato numerico estandar	Alta
RF-003.2.3	El sistema debe normalizar unidades de superficie (m2)	Alta
RF-003.2.4	El sistema debe extraer caracteristicas de texto libre	Media
RF-003.2.5	El sistema debe limpiar y estandarizar direcciones	Alta

RF-003.3: Enriquecimiento

ID	Requisito	Prioridad
RF-003.3.1	El sistema debe geocodificar direcciones a lat/lon	Alta
RF-003.3.2	El sistema debe calcular precio por m2	Alta
RF-003.3.3	El sistema debe asignar zona/colonia normalizada	Alta
RF-003.3.4	El sistema debe detectar duplicados cross-source	Media

RF-003.4: Carga

ID	Requisito	Prioridad
RF-003.4.1	El sistema debe hacer upsert en tabla de propiedades	Alta
RF-003.4.2	El sistema debe mantener historial de cambios de precio	Alta
RF-003.4.3	El sistema debe marcar propiedades inactivas	Alta
RF-003.4.4	El sistema debe emitir eventos de nuevas propiedades	Media

---

Schema Normalizado

Property:
  # Identificacion
  id: UUID
  source: string  # inmuebles24, vivanuncios, etc
  source_id: string  # ID original del portal
  source_url: string

  # Tipo
  property_type: enum
    - house
    - apartment
    - land
    - commercial
    - office
    - warehouse
  transaction_type: enum [sale, rent]

  # Ubicacion
  address: string
  neighborhood: string
  city: string
  state: string
  postal_code: string
  latitude: decimal
  longitude: decimal
  zone_id: UUID (FK)

  # Caracteristicas
  bedrooms: integer
  bathrooms: decimal
  parking_spaces: integer
  construction_m2: decimal
  land_m2: decimal
  age_years: integer
  floors: integer

  # Precio
  price: decimal
  currency: string  # MXN, USD
  price_per_m2: decimal (calculado)

  # Descripcion
  title: string
  description: text
  amenities: string[]
  images: string[]

  # Metadata
  is_active: boolean
  first_seen_at: timestamp
  last_seen_at: timestamp
  price_history: JSONB
  created_at: timestamp
  updated_at: timestamp

---

Mappings por Fuente

Inmuebles24

mappings:
  property_type:
    "Casa": house
    "Departamento": apartment
    "Terreno": land
    "Local comercial": commercial
    "Oficina": office
    "Bodega": warehouse

  transaction_type:
    "Venta": sale
    "Renta": rent
    "Venta o Renta": sale  # priorizar venta

  precio:
    selector: ".price-value"
    transform: "remove_currency_symbols | to_number"

  superficie:
    selector: ".surface-value"
    transform: "extract_number | assume_m2"

---

Reglas de Validacion

validations:
  precio:
    min: 10000  # MXN
    max: 500000000
    required: true

  superficie:
    min: 10  # m2
    max: 100000
    required: false

  coordenadas:
    latitude_range: [14.5, 32.7]  # Mexico
    longitude_range: [-118.5, -86.7]

  deduplicacion:
    strategy: "source_id + source"
    fallback: "address_normalized + price + type"

---

Criterios de Aceptacion

• Pipeline procesa 1000 propiedades/hora minimo
• Todos los campos requeridos se mapean correctamente
• Precios se convierten a formato numerico sin errores
• Geocoding tiene 95%+ success rate
• Duplicados se detectan con 98%+ precision
• Historial de precios se mantiene correctamente
• Raw data se almacena para debugging

---

Dependencias

• Cheerio o similar para parsing HTML
• Google Maps API para geocoding
• PostgreSQL para persistencia
• S3/MinIO para raw data storage

---

Historias de Usuario Relacionadas

• US-SCR-003: Normalizacion de datos

---

Autor: Tech Lead Fecha: 2026-01-04