system-docs/02_MODELO_DATOS/planos.md

# Planos de Datos TZZR

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

---

## Visión General

El sistema TZZR utiliza tres planos conceptuales para organizar la información:

```
┌─────────────────────────────────────────────────────────────────┐
│                      T0 - PLANO IDEAL                           │
│  ITM (Items): Objetivos, acciones ideales, requerimientos       │
│  Estado: PLANIFICADO - Sin implementación actual                │
└─────────────────────────────────────────────────────────────────┘
                           │
                           ▼ materializa
┌─────────────────────────────────────────────────────────────────┐
│                     MST - MILESTONES                            │
│  Compromisos futuros con fecha de vencimiento                   │
│  Estado: IMPLEMENTADO en CORP (tabla milestones)                │
└─────────────────────────────────────────────────────────────────┘
                           │
                           ▼ cumple/genera
┌─────────────────────────────────────────────────────────────────┐
│                       BCK - BLOQUES                             │
│  Hechos inmutables del pasado (blockchain-ready)                │
│  Estado: IMPLEMENTADO en CORP (tabla bloques)                   │
└─────────────────────────────────────────────────────────────────┘
```

---

## T0 - Plano Ideal (ITM)

### Concepto

El plano T0 contiene los Items (ITM) que representan el estado ideal futuro. Son la "partitura" que guía las acciones.

### Tipos de Items

| Tipo | Descripción |
|------|-------------|
| accion_ideal | Acción que debería ejecutarse |
| objetivo | Meta a alcanzar |
| requerimiento | Requisito a cumplir |

### Estado de Implementación

**PLANIFICADO** - Schema definido pero sin tablas creadas.

### 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,
    titulo VARCHAR(255) NOT NULL,
    descripcion TEXT,
    criterios_aceptacion JSONB,
    metadata JSONB,
    proyecto_tag VARCHAR(64),
    etiquetas JSONB,
    estado VARCHAR(20) DEFAULT 'draft',
    created_at TIMESTAMPTZ DEFAULT NOW(),
    created_by VARCHAR(64),
    UNIQUE (h_instancia, secuencia)
);
```

---

## MST - Milestones

### Concepto

Los milestones representan compromisos con fecha futura. Tienen un período flotante de 24 horas antes de consolidarse.

### Estado de Implementación

**IMPLEMENTADO** en CORP (database: corp).

### Schema Actual

```sql
-- Tabla: milestones (CORP)
CREATE TABLE milestones (
    id BIGSERIAL PRIMARY KEY,
    h_milestone VARCHAR(64) UNIQUE NOT NULL,
    h_instancia VARCHAR(64) NOT NULL,
    secuencia BIGINT NOT NULL,
    hash_previo VARCHAR(64),
    hash_contenido VARCHAR(64),
    tipo_milestone VARCHAR(50) NOT NULL,
    fecha_vencimiento DATE NOT NULL,
    descripcion TEXT,
    metadata JSONB,
    proyecto_tag VARCHAR(64),
    etiquetas JSONB,
    estado VARCHAR(20) DEFAULT 'draft',
    created_at TIMESTAMPTZ DEFAULT NOW(),
    modified_at TIMESTAMPTZ,
    created_by VARCHAR(64),
    UNIQUE (h_instancia, secuencia)
);
```

### Tipos de Milestones

| Tipo | Descripción |
|------|-------------|
| compromiso | Compromiso de entrega |
| deadline | Fecha límite |
| evento | Evento programado |
| recordatorio | Recordatorio futuro |

### Fórmula Hash

```
h_milestone = SHA-256(h_instancia:secuencia:tipo:contenido)
```

### Período Flotante

- **Duración:** 24 horas desde creación
- **Durante período:** Modificable vía MASON
- **Después:** Inmutable, solo lectura

**Nota:** Actualmente no hay scheduler que procese la expiración automáticamente.

---

## BCK - Bloques

### Concepto

Los bloques son registros inmutables de hechos pasados. Cada bloque está encadenado al anterior mediante hash, preparando la infraestructura para blockchain.

### Estado de Implementación

**IMPLEMENTADO** en CORP (database: corp).

### Schema Actual

```sql
-- Tabla: bloques (CORP)
CREATE TABLE bloques (
    id BIGSERIAL PRIMARY KEY,
    h_bloque VARCHAR(64) UNIQUE NOT NULL,
    h_instancia VARCHAR(64) NOT NULL,
    secuencia BIGINT NOT NULL,
    hash_previo VARCHAR(64),
    hash_contenido VARCHAR(64) NOT NULL,
    tipo_bloque VARCHAR(50) NOT NULL,
    contenido JSONB NOT NULL,
    metadata JSONB,
    item_asociado VARCHAR(64),
    milestone_asociado VARCHAR(64),
    h_maestro JSONB,
    h_player VARCHAR(64),
    h_loc VARCHAR(64),
    h_flag VARCHAR(64),
    estado VARCHAR(20) DEFAULT 'consolidado',
    created_at TIMESTAMPTZ DEFAULT NOW(),
    validated_at TIMESTAMPTZ,
    validated_by VARCHAR(64),
    UNIQUE (h_instancia, secuencia)
);
```

### Tipos de Bloques

| Tipo | Descripción |
|------|-------------|
| transaccion | Transacción económica |
| documento | Documento consolidado |
| evento | Evento registrado |
| milestone_cumplido | Milestone que se cumplió |

### Fórmula Hash

```
h_bloque = SHA-256(h_instancia:secuencia:hash_previo:hash_contenido)
hash_contenido = SHA-256(contenido_serializado)
```

### Encadenamiento

```
Bloque N-1                    Bloque N
┌──────────────────┐          ┌──────────────────┐
│ h_bloque: abc123 │ ──────►  │ hash_previo:     │
│ hash_contenido:  │          │   abc123         │
│   def456         │          │ h_bloque: ghi789 │
│ secuencia: 1     │          │ secuencia: 2     │
└──────────────────┘          └──────────────────┘
```

---

## Flujo Entre Planos

```
Usuario crea ITM
       │
       ▼
ITM (T0) "Objetivo: Completar proyecto X"
       │
       │ materializa
       ▼
MST "Milestone: Entrega módulo 1 - 2024-01-15"
       │
       │ [período flotante 24h]
       │
       ▼
MASON (enriquecimiento)
       │
       ▼
FELDMAN (validación)
       │
       │ cumple/genera
       ▼
BCK "Bloque: Módulo 1 entregado - 2024-01-14"
       │
       ▼
Inmutable ✓
```

---

## Tablas de Procesamiento

### FELDMAN Cola

```sql
-- feldman_cola: Elementos pendientes de validación
CREATE TABLE feldman_cola (
    id BIGSERIAL PRIMARY KEY,
    tipo VARCHAR(50) NOT NULL,  -- 'milestone' o 'bloque'
    h_entrada VARCHAR(64) NOT NULL,
    contenido JSONB NOT NULL,
    prioridad INTEGER DEFAULT 0,
    estado VARCHAR(20) DEFAULT 'pendiente',
    created_at TIMESTAMPTZ DEFAULT NOW(),
    processed_at TIMESTAMPTZ
);
```

### FELDMAN Validaciones

```sql
-- feldman_validaciones: Auditoría de validaciones
CREATE TABLE feldman_validaciones (
    id BIGSERIAL PRIMARY KEY,
    h_entrada VARCHAR(64) NOT NULL,
    regla VARCHAR(50) NOT NULL,  -- M-001, M-002, M-003
    resultado BOOLEAN NOT NULL,
    mensaje TEXT,
    validated_at TIMESTAMPTZ DEFAULT NOW()
);
```

---

## Reglas de Validación FELDMAN

| Regla | Nombre | Descripción |
|-------|--------|-------------|
| M-001 | Hash único | h_bloque/h_milestone no existe previamente |
| M-002 | Encadenamiento | hash_previo apunta a bloque existente |
| M-003 | Integridad | hash_contenido = SHA-256(contenido) |

---

## Decisiones de Diseño

### D-004: Eliminar columnas duplicadas

**Problema:** Milestones tienen columnas + JSONB duplicados.

**Decisión:** Mantener metadatos solo en JSONB `metadata`.

### D-007: Timestamps UTC

**Problema:** Inconsistencia en zonas horarias.

**Decisión:** Usar `TIMESTAMPTZ` y almacenar en UTC.

---

## Roadmap

### Implementado
- [x] Tabla milestones en CORP
- [x] Tabla bloques en CORP
- [x] Fórmulas hash definidas

### Pendiente
- [ ] Tabla items (T0)
- [ ] Scheduler para período flotante
- [ ] Merkle tree para verificación
- [ ] Smart contract blockchain (futuro)