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

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

{
  "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

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

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

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

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)