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