# 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.

```sql
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:**
```sql
INSERT INTO tabla (location)
VALUES (ST_SetSRID(ST_MakePoint(-99.1332, 19.4326), 4326));
```

**Ejemplo de query:**
```sql
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.

```sql
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.

```sql
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.

```sql
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

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

### Para DECIMAL (cuando se usa con PostGIS)

```sql
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:

```sql
-- 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*