system-docs/02_MODELO_DATOS/entidades.md

# Entidades Base TZZR

**Versión:** 5.0
**Fecha:** 2024-12-24

---

## Visión General

Las entidades base son los bloques fundamentales del sistema. Cada una tiene un hash único SHA-256 que la identifica de forma unívoca.

```
DEFINICIÓN ORIGINAL  →  SHA-256  →  h_{tipo} (64 chars)
```

---

## HST (Hash Semantic Tagging)

**Estado:** Implementado
**Servidor:** HST (72.62.2.84)
**Hash:** h_maestro

### Fórmula

```
h_maestro = SHA-256(grupo:ref)
```

### Grupos

| Grupo | Cantidad | Descripción |
|-------|----------|-------------|
| hst | 639 | Tags del sistema base |
| spe | 145 | Tags específicos |
| vsn | 84 | Visiones |
| flg | 65 | Banderas/países |
| vue | 21 | Vistas |

### Schema

```sql
CREATE TABLE hst_tags (
    id SERIAL PRIMARY KEY,
    ref VARCHAR(100) UNIQUE NOT NULL,
    h_maestro VARCHAR(64) UNIQUE NOT NULL,
    grupo VARCHAR(50) NOT NULL,
    nombre_es VARCHAR(255),
    nombre_en VARCHAR(255),
    descripcion TEXT,
    imagen_url TEXT,
    activo BOOLEAN DEFAULT true,
    version INTEGER DEFAULT 1,
    created_at TIMESTAMP DEFAULT NOW()
);
```

### Ejemplo

```json
{
  "ref": "person",
  "h_maestro": "a1b2c3d4e5f6...",
  "grupo": "hst",
  "nombre_es": "Persona",
  "nombre_en": "Person",
  "imagen_url": "https://tzrtech.org/a1b2c3d4e5f6...png"
}
```

---

## ITM (Items - Plano Ideal)

**Estado:** Planificado
**Servidor:** Por definir
**Hash:** h_item

### Concepto

Los ITM representan el estado ideal futuro. Son la "partitura" que guía las acciones.

### Schema Propuesto

```sql
CREATE TABLE items (
    id BIGSERIAL PRIMARY KEY,
    h_item VARCHAR(64) UNIQUE NOT NULL,
    h_instancia VARCHAR(64) NOT NULL,
    secuencia BIGINT NOT NULL,
    hash_previo VARCHAR(64),
    hash_contenido VARCHAR(64),
    tipo_item VARCHAR(50) NOT NULL, -- accion_ideal, objetivo, requerimiento
    titulo VARCHAR(255) NOT NULL,
    descripcion TEXT,
    criterios_aceptacion JSONB,
    metadata JSONB,
    proyecto_tag VARCHAR(64),
    etiquetas JSONB,
    estado VARCHAR(20) DEFAULT 'draft', -- draft, vigente, obsoleto
    created_at TIMESTAMPTZ DEFAULT NOW(),
    created_by VARCHAR(64),
    UNIQUE (h_instancia, secuencia)
);
```

---

## PLY (Players - Identidad)

**Estado:** Planificado
**Servidor:** Por definir
**Hash:** h_player

### Concepto

Los PLY representan la identidad de actores en el sistema (personas, empresas, agentes).

### Schema Propuesto

```sql
CREATE TABLE players (
    id BIGSERIAL PRIMARY KEY,
    h_player VARCHAR(64) UNIQUE NOT NULL,
    tipo VARCHAR(50) NOT NULL, -- persona, empresa, agente
    nombre VARCHAR(255) NOT NULL,
    email VARCHAR(255),
    metadata JSONB,
    activo BOOLEAN DEFAULT true,
    created_at TIMESTAMPTZ DEFAULT NOW()
);
```

---

## LOC (Locations - Ubicaciones)

**Estado:** Planificado
**Servidor:** Por definir
**Hash:** h_loc

### Concepto

Los LOC representan ubicaciones geográficas con precisión variable.

### Schema Propuesto

```sql
CREATE TABLE locations (
    id BIGSERIAL PRIMARY KEY,
    h_loc VARCHAR(64) UNIQUE NOT NULL,
    nombre VARCHAR(255),
    lat DECIMAL(10, 8),
    lon DECIMAL(11, 8),
    precision_metros INTEGER,
    tipo VARCHAR(50), -- punto, area, ruta
    metadata JSONB,
    created_at TIMESTAMPTZ DEFAULT NOW()
);
```

### Fórmula Hash

```
h_loc = SHA-256(lat:lon:precision)
```

---

## FLG (Flags - Marcos Jurídicos)

**Estado:** Planificado
**Servidor:** Por definir
**Hash:** h_flag

### Concepto

Los FLG representan marcos jurídicos, normativas, países.

### Notas

Actualmente existe un grupo `flg` en HST con 65 tags de países, pero no como entidad independiente.

---

## Tags de Usuario (Extensiones)

Los usuarios pueden crear sus propios tags como extensiones de HST.

| Tabla | Descripción |
|-------|-------------|
| hsu | HST Usuario |
| spu | SPE Usuario |
| vsu | VSN Usuario |
| vuu | VUE Usuario |
| pju | Proyectos Usuario |
| flu | FLG Usuario |

### Schema

```sql
CREATE TABLE hsu (
    id SERIAL PRIMARY KEY,
    ref VARCHAR(10) NOT NULL,
    h_usuario VARCHAR(64) NOT NULL,
    nombre VARCHAR(255) NOT NULL,
    user_id INTEGER REFERENCES users(id),
    metadata JSONB,
    activo BOOLEAN DEFAULT true,
    created_at TIMESTAMP DEFAULT NOW(),
    UNIQUE (user_id, ref)
);
```

---

## Relaciones Entre Entidades

```
ITM (ideal)
  │
  ├──► h_maestro (HST tags)
  ├──► h_player (PLY responsable)
  ├──► h_loc (LOC ubicación)
  └──► h_flag (FLG normativa)

MST (milestone)
  │
  ├──► item_asociado (ITM)
  └──► h_maestro (HST tags)

BCK (bloque)
  │
  ├──► item_asociado (ITM)
  ├──► milestone_asociado (MST)
  └──► h_maestro (HST tags)
```