erp-construccion-database-v2/docs/ESTANDAR-CAMPOS-UBICACION.md

Estándar de Campos de Ubicación - ERP Construcción

Versión: 1.0.0 Fecha: 2026-02-03 Subtarea: ST-P3-001

---

Resumen

Este documento define el estándar para campos de ubicación geográfica en la base de datos de ERP Construcción.

---

Tipos de Campos de Ubicación

1. Ubicación Geográfica Precisa (RECOMENDADO)

Tipo: GEOMETRY(POINT, 4326)

Uso: Cuando se requiere almacenar coordenadas GPS para queries espaciales.

location GEOMETRY(POINT, 4326),

Ventajas:

• Soporte nativo de PostGIS para queries espaciales
• Índices GiST eficientes
• Funciones ST_* para cálculos de distancia, área, etc.
• SRID 4326 = WGS84 (estándar GPS mundial)

Ejemplo de inserción:

INSERT INTO tabla (location)
VALUES (ST_SetSRID(ST_MakePoint(-99.1332, 19.4326), 4326));

Ejemplo de query:

SELECT * FROM tabla
WHERE ST_DWithin(
    location,
    ST_SetSRID(ST_MakePoint(-99.1332, 19.4326), 4326),
    1000  -- metros
);

---

2. Polígonos (Áreas)

Tipo: GEOMETRY(POLYGON, 4326)

Uso: Para delimitar áreas como fraccionamientos, etapas, manzanas.

polygon GEOMETRY(POLYGON, 4326),

Schemas que lo usan:

• construction.fraccionamientos
• construction.etapas
• construction.manzanas

---

3. Coordenadas Decimales (LEGACY)

Tipo: DECIMAL(10,8) para latitud, DECIMAL(11,8) para longitud

Uso: Compatibilidad con sistemas externos, APIs, tracking GPS simple.

latitude DECIMAL(10,8),
longitude DECIMAL(11,8),

Cuándo usar:

• Integración con APIs externas que esperan lat/long separados
• Tracking de activos con alta frecuencia de escritura
• Cuando NO se requieren queries espaciales complejas

Schema actual: assets (asset_locations, equipment, etc.)

Nota: Considerar migración a GEOMETRY en futuras versiones.

---

4. Descripción Textual

Tipo: VARCHAR(255) o TEXT

Uso: Ubicación descriptiva para humanos.

location_description VARCHAR(255),
delivery_location VARCHAR(255),

Ejemplos:

• "Bodega principal, Rack A-3"
• "Frente 2, Nivel 1"
• "Entrada norte del fraccionamiento"

---

Convención de Nomenclatura

Tipo	Nombre de Campo	Ejemplo
GEOMETRY Point	location o ubicacion_geo	location GEOMETRY(POINT, 4326)
GEOMETRY Polygon	polygon o area_geo	polygon GEOMETRY(POLYGON, 4326)
DECIMAL latitud	latitude o latitud	latitude DECIMAL(10,8)
DECIMAL longitud	longitude o longitud	longitude DECIMAL(11,8)
Texto descriptivo	location_description o ubicacion_desc	location_description VARCHAR(255)

---

Índices Recomendados

Para GEOMETRY

CREATE INDEX idx_tabla_location_geo ON schema.tabla
USING GIST (location);

Para DECIMAL (cuando se usa con PostGIS)

CREATE INDEX idx_tabla_location_geo ON schema.tabla
USING GIST (ST_SetSRID(ST_MakePoint(longitude, latitude), 4326))
WHERE longitude IS NOT NULL AND latitude IS NOT NULL;

---

Estado Actual por Schema

Schema	Tipo Usado	Campos	Estado
construction	GEOMETRY	location, polygon	✅ Estándar
hse	GEOMETRY	ubicacion_geo	✅ Estándar
inventory	GEOMETRY	location	✅ Estándar
estimates	VARCHAR	location_description	✅ OK (solo texto)
assets	DECIMAL	latitude, longitude	⚠️ Legacy
purchase	VARCHAR	delivery_location	✅ OK (solo texto)

---

Recomendaciones

1. Nuevas tablas: Usar GEOMETRY(POINT, 4326) para coordenadas
2. Assets schema: Considerar migración gradual a GEOMETRY
3. Siempre incluir: Campo location_description para contexto humano
4. Índices: Crear índice GiST para queries frecuentes

---

Migración Futura (Assets)

Para migrar assets.asset_locations de DECIMAL a GEOMETRY:

-- Agregar columna GEOMETRY
ALTER TABLE assets.asset_locations
ADD COLUMN location_geo GEOMETRY(POINT, 4326);

-- Poblar desde lat/long
UPDATE assets.asset_locations
SET location_geo = ST_SetSRID(ST_MakePoint(longitude, latitude), 4326)
WHERE latitude IS NOT NULL AND longitude IS NOT NULL;

-- Crear índice
CREATE INDEX idx_asset_locations_geo ON assets.asset_locations
USING GIST (location_geo);

---

Documentado: 2026-02-03 - ST-P3-001