docs(v5): Complete system documentation
Comprehensive documentation for TZZR system v5 including: - 00_VISION: Glossary and foundational philosophy - 01_ARQUITECTURA: System overview and server specs - 02_MODELO_DATOS: Entity definitions and data planes (T0, MST, BCK) - 03_COMPONENTES: Agent docs (CLARA, MARGARET, FELDMAN, GRACE) - 04_SEGURIDAD: Threat model and secrets management - 05_OPERACIONES: Infrastructure and backup/recovery - 06_INTEGRACIONES: GPU services (RunPod status: blocked) - 99_ANEXOS: Repository inventory (24 repos) Key findings documented: - CRITICAL: UFW inactive on CORP/HST - CRITICAL: PostgreSQL 5432 exposed - CRITICAL: .env files with 644 permissions - RunPod workers not starting (code ready in R2) - Infisical designated as single source of secrets (D-001) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
ARCHITECT
237
02_MODELO_DATOS/entidades.md
Normal file
237
02_MODELO_DATOS/entidades.md
Normal file
@@ -0,0 +1,237 @@
|
||||
# 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)
|
||||
```
|
||||
309
02_MODELO_DATOS/planos.md
Normal file
309
02_MODELO_DATOS/planos.md
Normal file
@@ -0,0 +1,309 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user