Sync from R2 skynet v8: manuales, operación, glosario v3
Añadido: - MANUAL_USUARIO_ARCHITECT.md - MANUAL_USUARIO_CORP.md - MANUAL_USUARIO_DECK.md - MANUAL_USUARIO_HST.md - 07_OPERACION/ (monitoring, runbooks, incident_response) - glosario_she_enterprise_v3.md Eliminado: - glosario_she_enterprise_v2.md (reemplazado por v3) 🤖 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
97
07_OPERACION/INDEX.md
Normal file
97
07_OPERACION/INDEX.md
Normal file
@@ -0,0 +1,97 @@
|
||||
# Skynet v8 - Sección 07: OPERACIÓN
|
||||
|
||||
## Documentos de Operación
|
||||
|
||||
### 1. Runbooks (runbooks.md)
|
||||
Procedimientos estandarizados para operaciones comunes:
|
||||
- **Reinicio de servicios**: Procedimiento seguro para reiniciar servicios sin downtime
|
||||
- **Failover de base de datos**: Cambio automático a réplica en caso de fallo
|
||||
- **Restauración de backups**: Opciones de restauración (completa, PITR, tabla)
|
||||
- **Escalado de recursos**: CPU, RAM, almacenamiento
|
||||
|
||||
**Ubicación**: `/system/skynet v8/07_OPERACION/runbooks.md`
|
||||
|
||||
### 2. Respuesta ante Incidentes (incident_response.md)
|
||||
Procedimientos de respuesta para situaciones de crisis:
|
||||
- **Caída de servidor**: Detección, escalación, mitigación, recovery
|
||||
- **Ataque DDoS**: Identificación, rate limiting, activación de servicios de protección
|
||||
- **Breach de seguridad**: Aislamiento, investigación forense, recovery, notificación
|
||||
|
||||
Incluye:
|
||||
- Fases de respuesta (detección, confirmación, escalación, investigación, mitigación, resolución)
|
||||
- Escaleras de escalación por severidad (P1-P4)
|
||||
- Contactos de emergencia
|
||||
- Tiempos de respuesta objetivo (SLA)
|
||||
|
||||
**Ubicación**: `/system/skynet v8/07_OPERACION/incident_response.md`
|
||||
|
||||
### 3. Monitoreo y Observabilidad (monitoring.md)
|
||||
Arquitectura y configuración de monitoreo:
|
||||
- **Métricas a monitorear**: Aplicación, BD, sistema, seguridad
|
||||
- **Alertas configuradas**: P1 (críticas), P2 (altas), P3 (medias)
|
||||
- **Dashboards**: Sistema, aplicación, BD, infraestructura, seguridad
|
||||
- **Logs**: Ubicaciones, análisis, comandos útiles
|
||||
- **Exporters**: Prometheus, custom, PostgreSQL
|
||||
|
||||
**Ubicación**: `/system/skynet v8/07_OPERACION/monitoring.md`
|
||||
|
||||
---
|
||||
|
||||
## Estructura de Carpetas R2
|
||||
|
||||
```
|
||||
s3://architect/system/skynet v8/07_OPERACION/
|
||||
├── runbooks.md (6.6 KB)
|
||||
├── incident_response.md (10.9 KB)
|
||||
├── monitoring.md (17.0 KB)
|
||||
└── INDEX_07_OPERACION.md (este archivo)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Acceso Rápido
|
||||
|
||||
### Para operadores
|
||||
1. Problema con servicio → Consultar `runbooks.md`
|
||||
2. Incidente crítico → Consultar `incident_response.md`
|
||||
3. Verificar estado del sistema → Consultar `monitoring.md`
|
||||
|
||||
### Para automatización
|
||||
- Scripts de backup: Referir a `runbooks.md` - Restauración de backups
|
||||
- Alertas automáticas: Referir a `monitoring.md` - Alertas Configuradas
|
||||
- Escalación automática: Referir a `incident_response.md` - Escaleras de escalación
|
||||
|
||||
---
|
||||
|
||||
## Integración con otras secciones
|
||||
|
||||
| Sección | Relación |
|
||||
|---------|----------|
|
||||
| 01_ARCHITECTURE | Define componentes monitorear |
|
||||
| 02_SECURITY | Colabora en incident response |
|
||||
| 03_INFRASTRUCTURE | Detalles técnicos para runbooks |
|
||||
| 04_DEPLOYMENT | Coordina con reinicio de servicios |
|
||||
| 05_TESTING | Valida runbooks en staging |
|
||||
| 06_TROUBLESHOOTING | Diagnostico previo a incidentes |
|
||||
|
||||
---
|
||||
|
||||
## Mejoras Futuras
|
||||
|
||||
1. Automatización adicional:
|
||||
- Scripts Python para ejecutar runbooks
|
||||
- Integración con orchestration tools (Kubernetes, etc.)
|
||||
|
||||
2. Aprendizaje automático:
|
||||
- Análisis predictivo de fallos
|
||||
- Detección anomalías avanzada
|
||||
|
||||
3. Documentación mejorada:
|
||||
- Videos de procedimientos críticos
|
||||
- Simulacros periódicos
|
||||
|
||||
---
|
||||
|
||||
**Última actualización**: 2025-12-30
|
||||
**Versión**: Skynet v8.0
|
||||
**Estado**: Operacional
|
||||
424
07_OPERACION/incident_response.md
Normal file
424
07_OPERACION/incident_response.md
Normal file
@@ -0,0 +1,424 @@
|
||||
# Procedimientos de Respuesta ante Incidentes - Skynet v8
|
||||
|
||||
## Procedimiento General ante Incidentes
|
||||
|
||||
### Fases de respuesta
|
||||
1. **Detección**: Sistema de alertas detecta anomalía
|
||||
2. **Confirmación**: Validar que es incidente real
|
||||
3. **Escalación**: Notificar al equipo
|
||||
4. **Investigación**: Determinar causa
|
||||
5. **Mitigación**: Aplicar solución temporal
|
||||
6. **Resolución**: Fix permanente
|
||||
7. **Post-mortem**: Análisis y mejora
|
||||
|
||||
---
|
||||
|
||||
## Incidente: Caída de Servidor
|
||||
|
||||
### Severidad
|
||||
**CRÍTICA** - Impacto: 100% del servicio indisponible
|
||||
|
||||
### Detección
|
||||
- Sistema de monitoreo no recibe heartbeat
|
||||
- Usuarios reportan servicio inaccesible
|
||||
- Alertas en Grafana: `node_up == 0`
|
||||
|
||||
### Confirmación (2 minutos máximo)
|
||||
```bash
|
||||
# Verificar conectividad básica
|
||||
ping 69.62.126.110
|
||||
|
||||
# Intentar conexión SSH
|
||||
ssh -i ~/.ssh/tzzr architect@69.62.126.110
|
||||
|
||||
# Si SSH no responde, es caída real
|
||||
```
|
||||
|
||||
### Escalación INMEDIATA
|
||||
1. **Notificar a**:
|
||||
- On-call engineer (5 min de respuesta)
|
||||
- Engineering lead
|
||||
- Operations manager
|
||||
|
||||
2. **Crear incident**
|
||||
- Abrir INC ticket
|
||||
- Timestamp inicio
|
||||
- Severidad: P1-CRITICAL
|
||||
|
||||
3. **Canales de comunicación**
|
||||
- Slack #incidents-critical
|
||||
- Email a escalation-list@skynet.tzzr
|
||||
- SMS a on-call (si disponible)
|
||||
|
||||
### Investigación inicial (5 minutos)
|
||||
```bash
|
||||
# Desde backup server
|
||||
ssh -i ~/.ssh/tzzr root@72.62.1.113 # deck
|
||||
|
||||
# Verificar recursos
|
||||
ping -c 3 69.62.126.110
|
||||
ssh -o ConnectTimeout=5 root@69.62.126.110 "uptime"
|
||||
|
||||
# Verificar logs en firewall/router
|
||||
ssh monitoring "tail -f /var/log/firewall.log | grep 69.62.126.110"
|
||||
|
||||
# Contactar proveedor datacenter
|
||||
# Verificar alertas de potencia/red
|
||||
```
|
||||
|
||||
### Mitigación Temporal (Si fallo de hardware)
|
||||
|
||||
#### Opción 1: Reinicio remoto
|
||||
```bash
|
||||
# Si acceso IPMI disponible
|
||||
ipmitool -I lanplus -H ipmi.datacenter.com -U admin -P pass power reset
|
||||
|
||||
# Esperar 3 minutos
|
||||
sleep 180
|
||||
|
||||
# Verificar si responde
|
||||
ping -c 3 69.62.126.110
|
||||
```
|
||||
|
||||
#### Opción 2: Failover a servidor backup
|
||||
```bash
|
||||
# Redirigir tráfico a deck (72.62.1.113)
|
||||
# Actualizar DNS
|
||||
# change A record: skynet.ttzr 300 IN A 72.62.1.113
|
||||
|
||||
# Sincronizar estado si posible
|
||||
rsync -avz --delete /var/lib/postgresql/ deck:/var/lib/postgresql/
|
||||
|
||||
# Iniciar servicios en backup
|
||||
ssh deck "systemctl start skynet-database skynet-api skynet-core"
|
||||
```
|
||||
|
||||
### Resolución
|
||||
- **Si hardware**: Contactar con datacenter para reemplazo
|
||||
- **Si red**: Contactar ISP para restaurar conectividad
|
||||
- **Si aplicación**: Debugging post-restauración
|
||||
|
||||
### Post-mortem (24 horas)
|
||||
- Documentar timeline
|
||||
- Identificar root cause
|
||||
- Implementar prevención
|
||||
- Actualizar runbooks
|
||||
|
||||
---
|
||||
|
||||
## Incidente: Ataque DDoS
|
||||
|
||||
### Severidad
|
||||
**ALTA** - Impacto: Servicio degradado o inaccesible
|
||||
|
||||
### Detección
|
||||
- Spike repentino de tráfico (>10x normal)
|
||||
- Alertas: `request_rate > 50k/sec`
|
||||
- Origen: Múltiples IPs no reconocidas
|
||||
- Network utilization > 80% inbound
|
||||
|
||||
### Confirmación (1 minuto)
|
||||
```bash
|
||||
# Verificar tráfico
|
||||
iftop -n -s 10
|
||||
|
||||
# Análisis de IPs origen
|
||||
tcpdump -i eth0 -nnn 'tcp.port == 80 or tcp.port == 443' | \
|
||||
awk '{print $3}' | cut -d. -f1-4 | sort | uniq -c | sort -rn | head -20
|
||||
|
||||
# Patrones de ataque
|
||||
# - SYN flood: conexiones incompletas
|
||||
ss -antp | grep SYN_RECV | wc -l
|
||||
# - HTTP flood: requests normales pero masivos
|
||||
# - DNS amplification: puerto 53
|
||||
|
||||
# Verificar logs de aplicación
|
||||
tail -f /var/log/skynet/access.log | head -100
|
||||
```
|
||||
|
||||
### Escalación INMEDIATA
|
||||
1. **Notificar**:
|
||||
- Security team
|
||||
- Network operations
|
||||
- Incident commander
|
||||
|
||||
2. **Crear incident**
|
||||
- INC ticket con "DDoS" en título
|
||||
- Severidad: P2-HIGH (puede ser P1 si impacto crítico)
|
||||
|
||||
3. **Activar plan DDoS**
|
||||
```bash
|
||||
# Alertas automáticas envían:
|
||||
# - Notificación a CDN provider
|
||||
# - Activación de rate limiting
|
||||
# - Análisis automático de patrones
|
||||
```
|
||||
|
||||
### Mitigación Temporal (Primeros 5-10 minutos)
|
||||
|
||||
#### Paso 1: Rate limiting automático
|
||||
```bash
|
||||
# Activar rate limiting por IP
|
||||
iptables -A INPUT -p tcp --dport 80 -m limit --limit 25/minute --limit-burst 100 -j ACCEPT
|
||||
iptables -A INPUT -p tcp --dport 80 -j DROP
|
||||
|
||||
# Alternativa: WAF rules
|
||||
# modsecurity rule: SecAction phase:1,nolog,pass,setvar:ip.suspicious=1
|
||||
```
|
||||
|
||||
#### Paso 2: Blacklist de IPs ofensoras
|
||||
```bash
|
||||
# Script para extraer top atacantes
|
||||
tcpdump -i eth0 -nnn -c 10000 'tcp.port == 80 or tcp.port == 443' | \
|
||||
awk '{print $3}' | cut -d. -f1-4 | \
|
||||
sort | uniq -c | sort -rn | head -100 | \
|
||||
awk '{print "iptables -A INPUT -s " $3 " -j DROP"}'
|
||||
|
||||
# O usar geo-blocking
|
||||
geoiplookup <IP> | grep -E "CN|RU|KP" && echo "DROP"
|
||||
```
|
||||
|
||||
#### Paso 3: Activar protección DNS
|
||||
```bash
|
||||
# Cambiar nameservers a proveedor con DDoS mitigation
|
||||
# (e.g., CloudFlare, Akamai)
|
||||
|
||||
# Actualizar DNS:
|
||||
# skynet.ttzr NS dns1.cloudflare.com
|
||||
# skynet.ttzr NS dns2.cloudflare.com
|
||||
|
||||
# O activar Cloudflare proxy:
|
||||
# change A record a IP de Cloudflare
|
||||
# Cloudflare mitiga el ataque antes de llegar a nuestro servidor
|
||||
```
|
||||
|
||||
### Escalación a DDoS Mitigation Service
|
||||
```bash
|
||||
# Si ataque persiste > 30 minutos
|
||||
# Activar contrato con DDoS mitigation provider
|
||||
|
||||
# Ejemplo: Cloudflare
|
||||
# 1. Cambiar nameservers
|
||||
# 2. Enable "I'm under attack mode"
|
||||
# 3. Cloudflare absorbe el tráfico malicioso
|
||||
|
||||
# Ejemplo: AWS Shield Advanced
|
||||
# 1. Redirigir tráfico a AWS CloudFront
|
||||
# 2. AWS absorbe y filtra ataque
|
||||
# 3. Tráfico legítimo llega a servidor
|
||||
```
|
||||
|
||||
### Investigación paralela
|
||||
```bash
|
||||
# Mientras se mitiga:
|
||||
# 1. Analizar patrones de ataque
|
||||
# 2. Identificar botnet o atacante
|
||||
# 3. Reportar a ISP del atacante
|
||||
# 4. Notificar law enforcement si necesario
|
||||
|
||||
# Comando: detectar patrón de User-Agent
|
||||
tail -f /var/log/skynet/access.log | grep -o 'User-Agent: [^"]*' | sort | uniq -c | sort -rn | head -5
|
||||
```
|
||||
|
||||
### Resolución
|
||||
- Dejar mitigación activa mientras persista ataque
|
||||
- Bloqueo permanente de IPs confirmadas maliciosas
|
||||
- Mantener WAF rules
|
||||
- Monitoreo intensivo por 24 horas
|
||||
|
||||
### Post-mortem
|
||||
- Análisis de logs del ataque
|
||||
- Identificación de patrones para prevención futura
|
||||
- Actualización de WAF rules
|
||||
- Prueba de carga para validar capacidad
|
||||
|
||||
---
|
||||
|
||||
## Incidente: Breach de Seguridad
|
||||
|
||||
### Severidad
|
||||
**CRÍTICA** - Impacto: Acceso no autorizado a datos sensibles
|
||||
|
||||
### Detección
|
||||
- Alertas de IDS/IPS
|
||||
- Comportamiento anómalo de usuario
|
||||
- Cambios no autorizados en archivos críticos
|
||||
- Alertas de WAF: SQLi, RFI, etc.
|
||||
|
||||
### Confirmación (Inmediato)
|
||||
```bash
|
||||
# Verificar logs de seguridad
|
||||
grep "ALERT\|ERROR\|FAILED" /var/log/auth.log | tail -50
|
||||
|
||||
# Revisar cambios recientes
|
||||
find /var/www /etc /root -mtime -1 -ls
|
||||
|
||||
# Búsqueda de shells web
|
||||
find / -name "*.php" -o -name "*.jsp" -o -name "*.asp" | \
|
||||
xargs grep -l "exec\|system\|shell_exec" 2>/dev/null
|
||||
|
||||
# Revisar procesos anómalos
|
||||
ps auxf | grep -E "bash|nc|perl|python" | grep -v grep
|
||||
```
|
||||
|
||||
### Escalación CRÍTICA + Aislamiento (1 minuto)
|
||||
1. **AISLAR SERVIDOR INMEDIATAMENTE**
|
||||
- Desconectar del firewall si es posible
|
||||
- O bloquear tráfico no autorizado
|
||||
```bash
|
||||
# Bloquear acceso excepto admin
|
||||
iptables -F INPUT
|
||||
iptables -A INPUT -i lo -j ACCEPT
|
||||
iptables -A INPUT -s <ADMIN_IP> -j ACCEPT
|
||||
iptables -A INPUT -j DROP
|
||||
```
|
||||
|
||||
2. **Notificar a**:
|
||||
- CTO / Security lead (inmediato)
|
||||
- Incident commander
|
||||
- Legal team
|
||||
- HR (si credenciales de empleado usadas)
|
||||
|
||||
3. **Crear incident**
|
||||
- INC ticket: "SECURITY BREACH"
|
||||
- Severidad: P1-CRITICAL
|
||||
- Activar crisis management
|
||||
|
||||
4. **Notificar stakeholders**
|
||||
- CEO
|
||||
- Directores de área afectada
|
||||
- Equipo legal
|
||||
|
||||
### Investigación (En paralelo con aislamiento)
|
||||
```bash
|
||||
# NO modificar nada en el servidor comprometido aún
|
||||
# Preservar evidencia
|
||||
|
||||
# 1. Identificar punto de entrada
|
||||
grep "FAILED\|UNAUTHORIZED" /var/log/auth.log | tail -100
|
||||
|
||||
# 2. Buscar malware/backdoors
|
||||
find /tmp /home /var/tmp -mtime -1 -type f | xargs file
|
||||
strings /var/log/syslog | grep -E "curl|wget|chmod" | tail -20
|
||||
|
||||
# 3. Revisar cambios en usuarios/permisos
|
||||
grep "sudo\|usermod\|chmod 777" /var/log/auth.log
|
||||
|
||||
# 4. Revisar conexiones de red
|
||||
netstat -pantu | grep ESTABLISHED | head -20
|
||||
lsof -i -P -n | grep -v LISTEN
|
||||
|
||||
# 5. Examinar sistema de archivos en disco
|
||||
# (hacer copia forense primero)
|
||||
ddrescue /dev/sda /mnt/forensic/sda.img
|
||||
mount -o ro /mnt/forensic/sda.img /mnt/forensic_mount
|
||||
|
||||
# 6. Buscar cambios en archivos críticos
|
||||
find /etc /root /var/www -mtime -3 ! -path "*/.*" -type f -ls
|
||||
```
|
||||
|
||||
### Contención
|
||||
```bash
|
||||
# 1. Si credenciales comprometidas
|
||||
# - Resetear contraseñas de todos los usuarios
|
||||
# - Cambiar API keys
|
||||
# - Revocar OAuth tokens
|
||||
|
||||
# 2. Si datos expuestos
|
||||
# - Inventariar datos expuestos
|
||||
# - Notificar a usuarios afectados (según GDPR/CCPA)
|
||||
# - Contactar a asegurador
|
||||
|
||||
# 3. Parches de seguridad
|
||||
# Aplicar patches a vulnerabilidad explotada
|
||||
# Actualizar software vulnerable
|
||||
```
|
||||
|
||||
### Recovery
|
||||
```bash
|
||||
# Opción 1: Restore desde backup limpio pre-breach
|
||||
systemctl stop skynet-*
|
||||
pg_restore -d postgres /backups/skynet_2025-12-25.sql # Anterior al breach
|
||||
systemctl start skynet-*
|
||||
|
||||
# Opción 2: Rebuild desde source control
|
||||
git clone https://gitea.ttzr/skynet/core.git
|
||||
cd core && git checkout commit_seguro
|
||||
./install.sh
|
||||
```
|
||||
|
||||
### Post-mortem (CRÍTICO)
|
||||
- Análisis forense completo
|
||||
- Publicar breach disclosure si requerido por ley
|
||||
- Auditoría de seguridad completa
|
||||
- Implementar controles preventivos
|
||||
- Revisión de políticas de seguridad
|
||||
|
||||
---
|
||||
|
||||
## Contactos de Emergencia
|
||||
|
||||
### Equipo de On-Call
|
||||
| Rol | Nombre | Teléfono | Email | Backup |
|
||||
|-----|--------|----------|-------|--------|
|
||||
| Principal | [ON-CALL] | +X XXXXXXXXX | oncall@skynet.ttzr | [BACKUP] |
|
||||
| Security | CISO | +X XXXXXXXXX | ciso@skynet.ttzr | Security Lead |
|
||||
| Operations | Ops Manager | +X XXXXXXXXX | ops@skynet.ttzr | DevOps Lead |
|
||||
| Database | DBA Lead | +X XXXXXXXXX | dba@skynet.ttzr | DBA Senior |
|
||||
|
||||
### Escalación Automática
|
||||
```
|
||||
Incidente detectado
|
||||
↓
|
||||
Alertas a Slack #incidents
|
||||
↓
|
||||
Si no confirmado en 5 min → Email a on-call
|
||||
↓
|
||||
Si no responde en 10 min → SMS + teléfono
|
||||
↓
|
||||
Si no responde en 15 min → Escalar a manager
|
||||
↓
|
||||
Si Severidad P1 → Activar crisis team
|
||||
```
|
||||
|
||||
### Proveedores Externos
|
||||
|
||||
#### Datacenter
|
||||
- **Proveedor**: [DATACENTER_NAME]
|
||||
- **Contacto NOC**: +X XXXXXXXXX
|
||||
- **Tickets**: https://support.datacenter.com
|
||||
- **Emergencia 24/7**: [NÚMERO]
|
||||
|
||||
#### ISP
|
||||
- **Proveedor**: [ISP_NAME]
|
||||
- **Contacto**: +X XXXXXXXXX
|
||||
- **Status page**: https://status.isp.com
|
||||
- **Emergencia**: [NÚMERO]
|
||||
|
||||
#### Banco de datos
|
||||
- **Proveedor**: [DB_PROVIDER]
|
||||
- **Support**: [EMAIL/TELÉFONO]
|
||||
- **Documentation**: [URL]
|
||||
|
||||
### Escaleras de escalación según severidad
|
||||
|
||||
#### P1-CRITICAL (Todos afectados)
|
||||
1. On-call engineer (inmediato)
|
||||
2. Tech lead (1 min)
|
||||
3. Engineering manager (2 min)
|
||||
4. CTO (3 min)
|
||||
5. CEO (5 min si no resolviendo)
|
||||
|
||||
#### P2-HIGH (Servicio degradado)
|
||||
1. On-call engineer
|
||||
2. Tech lead (si no resolviendo en 10 min)
|
||||
3. Engineering manager (si no resolviendo en 30 min)
|
||||
|
||||
#### P3-MEDIUM (Funcionalidad limitada)
|
||||
1. On-call engineer
|
||||
2. Tech lead (próximo turno si no urgente)
|
||||
|
||||
#### P4-LOW (Feature requests, problemas menores)
|
||||
1. Queue para próximo sprint
|
||||
2. No escalación urgente
|
||||
|
||||
557
07_OPERACION/monitoring.md
Normal file
557
07_OPERACION/monitoring.md
Normal file
@@ -0,0 +1,557 @@
|
||||
# Monitoreo y Observabilidad - Skynet v8
|
||||
|
||||
## Arquitectura de Monitoreo
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Skynet v8 Services │
|
||||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ skynet-core │ │ skynet-api │ │ skynet-db │ │
|
||||
│ └──────────────┘ └──────────────┘ └──────────────┘ │
|
||||
│ │ │ │ │
|
||||
│ └──────────────────┼───────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────────────────┴──────────────────┐ │
|
||||
│ ▼ ▼ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────┐ │
|
||||
│ │ Exporters / Collectors │ │
|
||||
│ │ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │ │
|
||||
│ │ │ Prometheus │ │ Node Expt │ │ Filebeat │ │ │
|
||||
│ │ │ Exporter │ │ (system) │ │ (logs) │ │ │
|
||||
│ │ └──────────────┘ └──────────────┘ └────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────┘ │
|
||||
└──────────────────────┬──────────────────────────────────────┘
|
||||
│
|
||||
┌──────────────┼──────────────┐
|
||||
▼ ▼ ▼
|
||||
┌─────────┐ ┌──────────┐ ┌──────────────┐
|
||||
│ Grafana │ │ ELK │ │ Alert Mgr │
|
||||
│ (Viz) │ │ (Logs) │ │ (Alerts) │
|
||||
└─────────┘ └──────────┘ └──────────────┘
|
||||
│ │ │
|
||||
└──────────────┼───────────────┘
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Notification │
|
||||
│ Channels │
|
||||
│ (Slack/Email) │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Métricas a Monitorear
|
||||
|
||||
### 1. Métricas de Aplicación (skynet-core)
|
||||
|
||||
#### Procesamiento y Throughput
|
||||
```
|
||||
Métrica | Umbral Normal | Alerta Warn | Alerta Critical
|
||||
---------------------------|---------------|-------------|----------------
|
||||
requests_per_second | 100-500 | > 750 | > 1000
|
||||
response_time_p50 | < 100ms | > 200ms | > 500ms
|
||||
response_time_p95 | < 500ms | > 1000ms | > 2000ms
|
||||
response_time_p99 | < 1000ms | > 2000ms | > 5000ms
|
||||
error_rate | < 0.1% | > 0.5% | > 1%
|
||||
success_rate | > 99.9% | < 99.5% | < 99%
|
||||
```
|
||||
|
||||
#### Ejemplos Prometheus
|
||||
```
|
||||
# Request rate (requests/sec)
|
||||
rate(http_requests_total[5m])
|
||||
|
||||
# Response time percentiles
|
||||
histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))
|
||||
histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m]))
|
||||
|
||||
# Error rate
|
||||
rate(http_requests_total{status=~"5.."}[5m]) /
|
||||
rate(http_requests_total[5m])
|
||||
|
||||
# Active connections
|
||||
skynet_active_connections
|
||||
```
|
||||
|
||||
### 2. Métricas de Base de Datos (skynet-database)
|
||||
|
||||
#### Performance
|
||||
```
|
||||
Métrica | Umbral Normal | Alerta | Critical
|
||||
-----------------------------|---------------|---------|----------
|
||||
query_execution_time_p95 | < 100ms | > 500ms | > 2000ms
|
||||
transactions_per_second | 100-1000 | > 2000 | > 5000
|
||||
active_connections | 10-50 | > 100 | > 150
|
||||
connection_utilization_pct | < 50% | > 80% | > 95%
|
||||
replication_lag_bytes | < 1MB | > 100MB | > 1GB
|
||||
```
|
||||
|
||||
#### Ejemplo Prometheus
|
||||
```
|
||||
# Query latency
|
||||
histogram_quantile(0.95, rate(pg_slow_queries_duration_seconds_bucket[5m]))
|
||||
|
||||
# Transactions/sec
|
||||
rate(pg_transactions_total[1m])
|
||||
|
||||
# Active connections
|
||||
pg_stat_activity_count{state="active"}
|
||||
|
||||
# Replication lag
|
||||
pg_replication_lag_bytes / 1024 / 1024 # MB
|
||||
|
||||
# Connection ratio
|
||||
pg_stat_activity_count / pg_settings_max_connections * 100
|
||||
```
|
||||
|
||||
### 3. Métricas de Sistema (Node Exporter)
|
||||
|
||||
#### CPU y Memoria
|
||||
```
|
||||
Métrica | Umbral Normal | Alerta Warn | Critical
|
||||
---------------------------|---------------|-------------|----------
|
||||
cpu_usage_percent | < 70% | > 80% | > 95%
|
||||
load_average_1min | < cores | > cores*1.5 | > cores*2
|
||||
memory_usage_percent | < 80% | > 85% | > 95%
|
||||
swap_usage_percent | < 10% | > 30% | > 50%
|
||||
```
|
||||
|
||||
#### Disco e I/O
|
||||
```
|
||||
Métrica | Umbral Normal | Alerta Warn | Critical
|
||||
---------------------------|---------------|-------------|----------
|
||||
disk_usage_percent | < 70% | > 80% | > 95%
|
||||
disk_io_read_mb_sec | variable | > 500MB/s | > 1GB/s
|
||||
disk_io_write_mb_sec | variable | > 500MB/s | > 1GB/s
|
||||
inode_usage_percent | < 70% | > 80% | > 95%
|
||||
```
|
||||
|
||||
#### Red
|
||||
```
|
||||
Métrica | Umbral Normal | Alerta Warn | Critical
|
||||
---------------------------|---------------|-------------|----------
|
||||
network_in_mbps | variable | > 900Mbps | > 980Mbps
|
||||
network_out_mbps | variable | > 900Mbps | > 980Mbps
|
||||
packet_loss_percent | < 0.1% | > 0.5% | > 1%
|
||||
tcp_connections | < 10000 | > 20000 | > 30000
|
||||
tcp_time_wait | < 5000 | > 10000 | > 20000
|
||||
```
|
||||
|
||||
#### Ejemplos Prometheus
|
||||
```
|
||||
# CPU usage
|
||||
100 - (avg by (instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)
|
||||
|
||||
# Memory usage
|
||||
(1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) * 100
|
||||
|
||||
# Disk usage
|
||||
(node_filesystem_size_bytes{fstype!="tmpfs"} - node_filesystem_avail_bytes) /
|
||||
node_filesystem_size_bytes * 100
|
||||
|
||||
# Network throughput
|
||||
rate(node_network_transmit_bytes_total{device="eth0"}[5m]) / 1024 / 1024 # MB/s
|
||||
```
|
||||
|
||||
### 4. Métricas de Seguridad
|
||||
|
||||
#### Acceso y Autenticación
|
||||
```
|
||||
Métrica | Umbral Normal | Alerta
|
||||
-----------------------------|---------------|--------
|
||||
failed_login_attempts_per_min | < 5 | > 20
|
||||
ssh_login_failures | < 3/10min | > 10/10min
|
||||
sudo_usage_anomaly | histórico | +50% desviación
|
||||
unauthorized_api_calls | < 1/min | > 10/min
|
||||
```
|
||||
|
||||
#### Integridad de datos
|
||||
```
|
||||
Métrica | Acción
|
||||
-----------------------------|------
|
||||
database_checksum_errors | Alerta + Investigar inmediatamente
|
||||
file_integrity_changes | Log + Review semanal
|
||||
unauthorized_user_creation | Alerta crítica
|
||||
privilege_escalation_attempt | Alerta crítica + Log forense
|
||||
```
|
||||
|
||||
#### Ejemplo: Detección de anomalías
|
||||
```bash
|
||||
# Buscar cambios no autorizados en archivos críticos
|
||||
aide --check --config=/etc/aide/aide.conf
|
||||
|
||||
# Auditar cambios de permisos
|
||||
auditctl -l
|
||||
ausearch -k privileged | tail -100
|
||||
|
||||
# Monitorear login attempts
|
||||
faillog -a # Summary de todos los usuarios
|
||||
lastb # Últimas 10 sesiones fallidas
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Alertas Configuradas
|
||||
|
||||
### Sistema de Alertas
|
||||
|
||||
Archivo: `/etc/prometheus/alert_rules.yml`
|
||||
|
||||
#### Alertas P1 (CRÍTICAS - 1 minuto)
|
||||
```yaml
|
||||
- alert: ServiceDown
|
||||
expr: up == 0
|
||||
for: 1m
|
||||
labels:
|
||||
severity: critical
|
||||
annotations:
|
||||
summary: "{{ $labels.instance }} DOWN"
|
||||
action: "Verificar immediately, ejecutar runbook de reinicio"
|
||||
|
||||
- alert: DiskFull
|
||||
expr: (node_filesystem_avail_bytes / node_filesystem_size_bytes) < 0.05
|
||||
for: 5m
|
||||
labels:
|
||||
severity: critical
|
||||
annotations:
|
||||
summary: "Disco al 95% en {{ $labels.instance }}"
|
||||
action: "Ejecutar escalado de almacenamiento"
|
||||
|
||||
- alert: HighErrorRate
|
||||
expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.05
|
||||
for: 2m
|
||||
labels:
|
||||
severity: critical
|
||||
annotations:
|
||||
summary: "Error rate > 5% en {{ $labels.job }}"
|
||||
action: "Investigar logs, posible DDoS o fallo de aplicación"
|
||||
|
||||
- alert: DatabaseDown
|
||||
expr: pg_up == 0
|
||||
for: 1m
|
||||
labels:
|
||||
severity: critical
|
||||
annotations:
|
||||
summary: "PostgreSQL DOWN en {{ $labels.instance }}"
|
||||
action: "Ejecutar runbook de failover o reinicio"
|
||||
|
||||
- alert: ReplicationLagCritical
|
||||
expr: (pg_replication_lag_bytes / 1024 / 1024) > 1000 # 1GB
|
||||
for: 5m
|
||||
labels:
|
||||
severity: critical
|
||||
annotations:
|
||||
summary: "Replication lag {{ $value }}MB"
|
||||
action: "Verificar red, aumentar bandwidth, o promover replica"
|
||||
```
|
||||
|
||||
#### Alertas P2 (ALTAS - 5 minutos)
|
||||
```yaml
|
||||
- alert: HighCPU
|
||||
expr: (100 - (avg(rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)) > 80
|
||||
for: 5m
|
||||
labels:
|
||||
severity: high
|
||||
annotations:
|
||||
summary: "CPU > 80% en {{ $labels.instance }}"
|
||||
action: "Investigar procesos, considerar escalado"
|
||||
|
||||
- alert: HighMemory
|
||||
expr: (1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) > 0.85
|
||||
for: 5m
|
||||
labels:
|
||||
severity: high
|
||||
annotations:
|
||||
summary: "Memoria > 85% en {{ $labels.instance }}"
|
||||
action: "Investigar memory leaks, escalar RAM"
|
||||
|
||||
- alert: SlowQueries
|
||||
expr: histogram_quantile(0.95, rate(pg_slow_queries_duration_seconds_bucket[5m])) > 1
|
||||
for: 5m
|
||||
labels:
|
||||
severity: high
|
||||
annotations:
|
||||
summary: "Queries lentas p95 {{ $value }}s"
|
||||
action: "Analizar EXPLAIN PLAN, optimizar índices"
|
||||
|
||||
- alert: HighConnectionCount
|
||||
expr: (pg_stat_activity_count / pg_settings_max_connections) > 0.8
|
||||
for: 10m
|
||||
labels:
|
||||
severity: high
|
||||
annotations:
|
||||
summary: "Conexiones DB {{ $value }}%"
|
||||
action: "Investigar connection leaks, escalar max_connections"
|
||||
|
||||
- alert: DDoSDetected
|
||||
expr: rate(http_requests_total[5m]) > 10000
|
||||
for: 2m
|
||||
labels:
|
||||
severity: high
|
||||
annotations:
|
||||
summary: "Posible DDoS: {{ $value }} req/sec"
|
||||
action: "Activar rate limiting, contactar ISP"
|
||||
```
|
||||
|
||||
#### Alertas P3 (MEDIAS - 15 minutos)
|
||||
```yaml
|
||||
- alert: DiskSpaceLow
|
||||
expr: (node_filesystem_avail_bytes / node_filesystem_size_bytes) < 0.15
|
||||
for: 15m
|
||||
labels:
|
||||
severity: medium
|
||||
annotations:
|
||||
summary: "Disco < 15% en {{ $labels.instance }}"
|
||||
action: "Agendar escalado de almacenamiento"
|
||||
|
||||
- alert: BackupFailed
|
||||
expr: time() - backup_last_successful_timestamp > 86400 # 24h
|
||||
for: 1h
|
||||
labels:
|
||||
severity: medium
|
||||
annotations:
|
||||
summary: "Backup no completado en > 24h"
|
||||
action: "Verificar proceso de backup, logs"
|
||||
|
||||
- alert: CertificateExpiring
|
||||
expr: (ssl_cert_expire_timestamp - time()) / 86400 < 30
|
||||
labels:
|
||||
severity: medium
|
||||
annotations:
|
||||
summary: "SSL cert vence en {{ $value }} días"
|
||||
action: "Renovar certificado"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dashboards Disponibles
|
||||
|
||||
### Dashboard 1: Visión General (System Overview)
|
||||
|
||||
**URL**: `http://grafana.skynet.ttzr/d/overview`
|
||||
|
||||
**Paneles**:
|
||||
- Estado de servicios (verde/rojo)
|
||||
- Request rate (últimas 24h)
|
||||
- Error rate (trending)
|
||||
- CPU/Memoria (gauges)
|
||||
- Disk space (stacked)
|
||||
- Network I/O (dual axis)
|
||||
- Database connections
|
||||
- Top errors (tabla)
|
||||
|
||||
### Dashboard 2: Rendimiento de Aplicación (Application Performance)
|
||||
|
||||
**URL**: `http://grafana.skynet.ttzr/d/app-performance`
|
||||
|
||||
**Paneles**:
|
||||
- Response time p50/p95/p99
|
||||
- Throughput (requests/sec)
|
||||
- Error rate by endpoint
|
||||
- Hot endpoints (top 10)
|
||||
- Request distribution (by method)
|
||||
- Slowest endpoints
|
||||
- Error distribution by type
|
||||
- Request size distribution
|
||||
|
||||
### Dashboard 3: Rendimiento de Base de Datos (Database Performance)
|
||||
|
||||
**URL**: `http://grafana.skynet.ttzr/d/db-performance`
|
||||
|
||||
**Paneles**:
|
||||
- Transactions/sec
|
||||
- Query execution time percentiles
|
||||
- Slow queries (top 10)
|
||||
- Table sizes
|
||||
- Index usage
|
||||
- Cache hit ratio
|
||||
- Replication lag
|
||||
- Active connections
|
||||
- Lock contention
|
||||
- Autovacuum status
|
||||
|
||||
### Dashboard 4: Infraestructura y Hardware (Infrastructure)
|
||||
|
||||
**URL**: `http://grafana.skynet.ttzr/d/infrastructure`
|
||||
|
||||
**Paneles**:
|
||||
- CPU utilization (por core)
|
||||
- Memory breakdown (used/buffers/cache)
|
||||
- Load average
|
||||
- Disk I/O (read/write MB/s)
|
||||
- Disk space by mount point
|
||||
- Network throughput (in/out)
|
||||
- Network errors/dropped packets
|
||||
- TCP connection states
|
||||
- Inode usage
|
||||
|
||||
### Dashboard 5: Seguridad y Logs (Security)
|
||||
|
||||
**URL**: `http://grafana.skynet.ttzr/d/security`
|
||||
|
||||
**Paneles**:
|
||||
- Failed login attempts
|
||||
- SSH connection attempts
|
||||
- Firewall blocks (top IPs)
|
||||
- Privilege escalation attempts
|
||||
- API calls unauthorized
|
||||
- File integrity changes
|
||||
- Process anomalies
|
||||
- Network connections unusual
|
||||
|
||||
---
|
||||
|
||||
## Logs Importantes
|
||||
|
||||
### Ubicaciones de logs
|
||||
|
||||
```
|
||||
/var/log/skynet/
|
||||
├── core.log # Logs de aplicación principal
|
||||
├── api.log # Logs de API server
|
||||
├── database.log # Logs de conexiones DB
|
||||
└── error.log # Errores consolidados
|
||||
|
||||
/var/log/
|
||||
├── auth.log # Logins, sudo
|
||||
├── syslog # Mensajes del kernel
|
||||
├── fail2ban.log # Intentos de acceso fallidos
|
||||
└── postgresql/
|
||||
└── postgresql.log # Logs de PostgreSQL
|
||||
|
||||
/var/lib/postgresql/
|
||||
└── pg_log/ # Logs detallados de DB
|
||||
```
|
||||
|
||||
### Log Analysis Queries
|
||||
|
||||
#### ELK / Kibana
|
||||
|
||||
```json
|
||||
# Top 10 endpoints por error
|
||||
{
|
||||
"aggs": {
|
||||
"endpoints": {
|
||||
"terms": {
|
||||
"field": "endpoint.keyword",
|
||||
"size": 10,
|
||||
"order": {"errors": "desc"}
|
||||
},
|
||||
"aggs": {
|
||||
"errors": {
|
||||
"filter": {"range": {"status": {"gte": 500}}}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# Response time trend
|
||||
{
|
||||
"aggs": {
|
||||
"time_trend": {
|
||||
"date_histogram": {
|
||||
"field": "@timestamp",
|
||||
"interval": "1m"
|
||||
},
|
||||
"aggs": {
|
||||
"p95_latency": {
|
||||
"percentiles": {
|
||||
"field": "response_time_ms",
|
||||
"percents": [95]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# Failed logins por IP
|
||||
{
|
||||
"query": {
|
||||
"term": {"event": "failed_login"}
|
||||
},
|
||||
"aggs": {
|
||||
"by_ip": {
|
||||
"terms": {"field": "source_ip", "size": 20}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Comandos útiles de análisis
|
||||
|
||||
```bash
|
||||
# Top errores en última hora
|
||||
grep ERROR /var/log/skynet/error.log | grep -o "ERROR [^:]]*" | \
|
||||
sort | uniq -c | sort -rn | head -10
|
||||
|
||||
# Endpoints lentos
|
||||
grep "response_time" /var/log/skynet/api.log | \
|
||||
awk '{print $5, $1}' | sort -n | tail -10
|
||||
|
||||
# Intentos de acceso fallidos
|
||||
grep "Failed" /var/log/auth.log | \
|
||||
grep -o "from [0-9.]*" | sort | uniq -c | sort -rn
|
||||
|
||||
# Errors por hora
|
||||
grep ERROR /var/log/skynet/error.log | \
|
||||
cut -d' ' -f1 | cut -d: -f1-2 | uniq -c
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Instrumentación y Exporters
|
||||
|
||||
### Prometheus Node Exporter
|
||||
```bash
|
||||
# Verificar que está corriendo
|
||||
systemctl status prometheus-node-exporter
|
||||
|
||||
# Metrics disponibles
|
||||
curl http://localhost:9100/metrics | head -50
|
||||
|
||||
# Configuración
|
||||
cat /etc/prometheus/node_exporter_args
|
||||
# Típicamente: --collector.textfile.directory=/var/lib/node_exporter/textfile_collector
|
||||
```
|
||||
|
||||
### Custom Exporter (skynet-exporter)
|
||||
```bash
|
||||
# Métricas customizadas de Skynet
|
||||
curl http://localhost:9200/metrics | grep skynet_
|
||||
|
||||
# Ejemplos:
|
||||
# skynet_requests_total{endpoint="/api/v1/data"}
|
||||
# skynet_response_time_seconds_bucket{endpoint="/api/v1/data", le="0.1"}
|
||||
# skynet_database_connections{state="active"}
|
||||
# skynet_cache_hit_ratio
|
||||
```
|
||||
|
||||
### PostgreSQL Exporter
|
||||
```bash
|
||||
# Verificar exporter de PostgreSQL
|
||||
curl http://localhost:9187/metrics | grep pg_
|
||||
|
||||
# Métricas principales:
|
||||
# pg_stat_database_tup_fetched
|
||||
# pg_stat_database_tup_inserted
|
||||
# pg_stat_database_tup_updated
|
||||
# pg_stat_database_tup_deleted
|
||||
# pg_up (1 si DB está up, 0 si down)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Checklist de Monitoreo Diario
|
||||
|
||||
- [ ] Revisar estado de todos los dashboards
|
||||
- [ ] Verificar que no hay alertas P1 sin resolver
|
||||
- [ ] Analizar tendencias de performance (¿empeorando?)
|
||||
- [ ] Verificar backup completó exitosamente
|
||||
- [ ] Revisar log de acceso para anomalías
|
||||
- [ ] Confirmar que replicación está al día
|
||||
- [ ] Verificar espacio en disco (< 85%)
|
||||
- [ ] Revisar certificados SSL (> 30 días para expirar)
|
||||
- [ ] Documentar incident report si hubo P1/P2
|
||||
|
||||
294
07_OPERACION/runbooks.md
Normal file
294
07_OPERACION/runbooks.md
Normal file
@@ -0,0 +1,294 @@
|
||||
# Runbooks - Operación Skynet v8
|
||||
|
||||
## Runbook: Reinicio de servicios
|
||||
|
||||
### Objetivo
|
||||
Reiniciar servicios del sistema sin afectar operaciones críticas.
|
||||
|
||||
### Procedimiento
|
||||
1. **Verificar estado actual**
|
||||
```bash
|
||||
systemctl status skynet-core
|
||||
systemctl status skynet-database
|
||||
systemctl status skynet-api
|
||||
```
|
||||
|
||||
2. **Notificar a usuarios (si aplica)**
|
||||
- Enviar notificación de mantenimiento planeado
|
||||
- Esperar confirmación de ventana de mantenimiento
|
||||
|
||||
3. **Reiniciar servicios en orden**
|
||||
```bash
|
||||
# Primero servicios auxiliares
|
||||
systemctl restart skynet-cache
|
||||
systemctl restart skynet-broker
|
||||
|
||||
# Luego servicios principales
|
||||
systemctl restart skynet-database
|
||||
sleep 30
|
||||
systemctl restart skynet-api
|
||||
sleep 20
|
||||
systemctl restart skynet-core
|
||||
```
|
||||
|
||||
4. **Verificar estado post-reinicio**
|
||||
```bash
|
||||
systemctl status skynet-core
|
||||
systemctl status skynet-database
|
||||
systemctl status skynet-api
|
||||
|
||||
# Verificar conectividad
|
||||
curl -s http://localhost:8080/health
|
||||
curl -s http://localhost:5432/ping
|
||||
```
|
||||
|
||||
5. **Validar operación normal**
|
||||
- Verificar logs sin errores críticos
|
||||
- Ejecutar health checks
|
||||
- Monitorear métricas durante 5 minutos
|
||||
|
||||
### Rollback
|
||||
Si hay fallos:
|
||||
```bash
|
||||
systemctl stop skynet-core
|
||||
systemctl stop skynet-api
|
||||
systemctl stop skynet-database
|
||||
|
||||
# Restaurar desde último snapshot conocido
|
||||
pg_restore -d skynet /backups/skynet_latest.sql
|
||||
systemctl start skynet-database
|
||||
systemctl start skynet-api
|
||||
systemctl start skynet-core
|
||||
```
|
||||
|
||||
### Tiempo estimado
|
||||
20-30 minutos con validación
|
||||
|
||||
---
|
||||
|
||||
## Runbook: Failover de base de datos
|
||||
|
||||
### Objetivo
|
||||
Cambiar a base de datos secundaria en caso de fallo de primaria.
|
||||
|
||||
### Prerrequisitos
|
||||
- Replicación configurada y activa
|
||||
- Sistema de monitoreo detectó fallo de primaria
|
||||
- Base de datos secundaria disponible
|
||||
|
||||
### Procedimiento
|
||||
|
||||
1. **Confirmar fallo de primaria**
|
||||
```bash
|
||||
# Intentar conectarse a primaria
|
||||
psql -h skynet-primary -U postgres -d skynet -c "SELECT 1"
|
||||
|
||||
# Verificar lag de replicación
|
||||
psql -h skynet-primary -U postgres -c "SELECT slot_name, restart_lsn FROM pg_replication_slots"
|
||||
```
|
||||
|
||||
2. **Promover secundaria**
|
||||
```bash
|
||||
# En servidor secundario
|
||||
pg_ctl promote -D /var/lib/postgresql/14/main
|
||||
|
||||
# Esperar 30 segundos para que complete
|
||||
sleep 30
|
||||
|
||||
# Verificar estado
|
||||
psql -U postgres -c "SELECT pg_is_wal_replay_paused()"
|
||||
```
|
||||
|
||||
3. **Redirigir aplicaciones**
|
||||
```bash
|
||||
# Actualizar DNS o connection string
|
||||
# En skynet-api.conf:
|
||||
# database_host = skynet-secondary
|
||||
|
||||
systemctl restart skynet-api
|
||||
```
|
||||
|
||||
4. **Verificar operación normal**
|
||||
```bash
|
||||
# Validar escrituras en nueva primaria
|
||||
psql -h skynet-secondary -U postgres -d skynet -c "INSERT INTO test VALUES (NOW())"
|
||||
|
||||
# Monitorear performance
|
||||
watch -n 2 'psql -h skynet-secondary -U postgres -c "SELECT count(*) FROM skynet_logs"'
|
||||
```
|
||||
|
||||
5. **Informar del failover**
|
||||
- Registrar en incident log
|
||||
- Notificar al equipo
|
||||
- Agendar recuperación de primaria
|
||||
|
||||
### Recovery de primaria
|
||||
```bash
|
||||
# Una vez primaria se recupere:
|
||||
pg_basebackup -h skynet-primary -D /var/lib/postgresql/14/main -U replication
|
||||
systemctl start postgresql
|
||||
```
|
||||
|
||||
### Tiempo estimado
|
||||
5-10 minutos
|
||||
|
||||
---
|
||||
|
||||
## Runbook: Restauración de backups
|
||||
|
||||
### Objetivo
|
||||
Restaurar datos desde backups en caso de corrupción o pérdida de datos.
|
||||
|
||||
### Tipos de restauración
|
||||
|
||||
#### 1. Restauración completa
|
||||
```bash
|
||||
# Detener servicios
|
||||
systemctl stop skynet-core
|
||||
systemctl stop skynet-api
|
||||
systemctl stop skynet-database
|
||||
|
||||
# Restaurar backup completo
|
||||
pg_restore -C -d postgres /backups/skynet_full_2025-12-30.sql
|
||||
|
||||
# Reiniciar servicios
|
||||
systemctl start skynet-database
|
||||
sleep 30
|
||||
systemctl start skynet-api
|
||||
systemctl start skynet-core
|
||||
```
|
||||
|
||||
#### 2. Restauración point-in-time (PITR)
|
||||
```bash
|
||||
# Restaurar hasta timestamp específico
|
||||
psql -U postgres -d skynet -c "
|
||||
SELECT pg_wal_replay_pause();
|
||||
SELECT pg_xact_xmin(xid) FROM pg_xact;
|
||||
"
|
||||
|
||||
# Restaurar WAL archive hasta timestamp
|
||||
pg_restore -U postgres -d skynet \
|
||||
-e -t tabla_critica /backups/skynet_full.sql
|
||||
|
||||
# Aplicar WAL hasta punto
|
||||
pg_wal_replay_start()
|
||||
```
|
||||
|
||||
#### 3. Restauración de tabla específica
|
||||
```bash
|
||||
# Restaurar solo tabla corrupta
|
||||
pg_restore -d skynet -t tabla_corrupta /backups/skynet_full.sql
|
||||
|
||||
# Validar integridad
|
||||
ANALYZE tabla_corrupta;
|
||||
```
|
||||
|
||||
### Validación post-restauración
|
||||
```bash
|
||||
# Verificar integridad
|
||||
psql -U postgres -d skynet -c "SELECT COUNT(*) FROM pg_stat_user_tables"
|
||||
|
||||
# Comparar checksums
|
||||
pg_basebackup --wal-method=fetch -l "restore_$(date +%s)"
|
||||
|
||||
# Validar índices
|
||||
REINDEX DATABASE skynet;
|
||||
```
|
||||
|
||||
### Tiempo estimado
|
||||
- Completa: 30-60 minutos (depende tamaño)
|
||||
- PITR: 15-45 minutos
|
||||
- Tabla: 5-15 minutos
|
||||
|
||||
---
|
||||
|
||||
## Runbook: Escalado de recursos
|
||||
|
||||
### Objetivo
|
||||
Aumentar capacidad de computo o almacenamiento sin downtime.
|
||||
|
||||
### Escalado de CPU/RAM
|
||||
|
||||
1. **Evaluar necesidad**
|
||||
```bash
|
||||
# Monitorear uso actual
|
||||
top -n 1 | head -20
|
||||
free -h
|
||||
|
||||
# Proyectar crecimiento
|
||||
# Si uso > 80%, escalar inmediatamente
|
||||
# Si proyectado > 80% en 7 días, escalar
|
||||
```
|
||||
|
||||
2. **Escalar infraestructura**
|
||||
```bash
|
||||
# En cloud provider o hypervisor
|
||||
# Aumentar CPU cores
|
||||
# Aumentar memoria RAM
|
||||
# Aplicar cambios sin reinicio (si soportado)
|
||||
```
|
||||
|
||||
3. **Verificar en SO**
|
||||
```bash
|
||||
lscpu
|
||||
free -h
|
||||
```
|
||||
|
||||
4. **Rebalancear servicios**
|
||||
```bash
|
||||
# Aumentar workers/threads en config
|
||||
systemctl restart skynet-api
|
||||
|
||||
# Aumentar shared_buffers en PostgreSQL
|
||||
# postgresql.conf: shared_buffers = 16GB (en lugar de 8GB)
|
||||
systemctl restart skynet-database
|
||||
```
|
||||
|
||||
### Escalado de almacenamiento
|
||||
|
||||
1. **Monitorear uso**
|
||||
```bash
|
||||
df -h /var/lib/postgresql
|
||||
du -sh /backups
|
||||
|
||||
# Alerta si > 80% utilizado
|
||||
```
|
||||
|
||||
2. **Agregar espacio**
|
||||
```bash
|
||||
# Opción 1: Aumentar volumen existente
|
||||
lvextend -l +50G /dev/vg0/lv_data
|
||||
resize2fs /dev/vg0/lv_data
|
||||
|
||||
# Opción 2: Agregar nuevo volumen
|
||||
# Montar en /data2
|
||||
# Configurar replicación a nuevo volumen
|
||||
```
|
||||
|
||||
3. **Validar cambios**
|
||||
```bash
|
||||
df -h /var/lib/postgresql
|
||||
# Debe mostrar nuevo tamaño
|
||||
```
|
||||
|
||||
4. **Monitorear performance**
|
||||
- Velocidad I/O
|
||||
- Latencia de queries
|
||||
- Crecimiento de espacios
|
||||
|
||||
### Tiempo estimado
|
||||
- CPU/RAM: 30 minutos - 2 horas (depende downtime)
|
||||
- Almacenamiento: 1-4 horas (sin downtime posible)
|
||||
|
||||
---
|
||||
|
||||
## Escalabilidad Matriz
|
||||
|
||||
| Recurso | Umbral Acción | Aumento | Tiempo |
|
||||
|---------|---|---|---|
|
||||
| CPU | >85% x 5min | +2 cores | 30min-2h |
|
||||
| RAM | >80% x 10min | +8GB | 30min-2h |
|
||||
| Disco | >85% utilizado | +50% capacidad | 1-4h |
|
||||
| Conexiones DB | >80% max_connections | +50 conexiones | 15min |
|
||||
| Replication lag | >10GB | Increase bandwidth | Immediate |
|
||||
|
||||
412
MANUAL_USUARIO_ARCHITECT.md
Normal file
412
MANUAL_USUARIO_ARCHITECT.md
Normal file
@@ -0,0 +1,412 @@
|
||||
# MANUAL DE USUARIO - ARCHITECT (Servidor Central TZZR)
|
||||
|
||||
## Introducción
|
||||
|
||||
ARCHITECT es el coordinador central del sistema TZZR alojado en el servidor 69.62.126.110. Este manual describe los servicios, herramientas y procedimientos para trabajar en el servidor central.
|
||||
|
||||
## Información del Servidor
|
||||
|
||||
| Aspecto | Detalles |
|
||||
|--------|----------|
|
||||
| **IP** | 69.62.126.110 |
|
||||
| **Usuario** | architect |
|
||||
| **Ubicación** | Servidor Central TZZR |
|
||||
| **Rol** | Coordinador multiagente, gestión de servicios |
|
||||
|
||||
## Servicios Disponibles
|
||||
|
||||
### 1. Gitea (Control de Versiones)
|
||||
|
||||
**Puerto**: 3000
|
||||
**URL**: http://69.62.126.110:3000
|
||||
**Uso**: Repositorio central de código para todos los proyectos
|
||||
|
||||
#### Características:
|
||||
- Hospedaje de repositorios Git
|
||||
- Interfaz web para gestión de código
|
||||
- Integración con pipelines de CI/CD
|
||||
- Backup automático en R2
|
||||
|
||||
#### Acceso:
|
||||
```bash
|
||||
# Clonar repositorio
|
||||
git clone http://69.62.126.110:3000/architect/[repo-name].git
|
||||
|
||||
# Ver estado de repositorio
|
||||
cd /home/architect/[repo-name]
|
||||
git status
|
||||
git log --oneline
|
||||
```
|
||||
|
||||
### 2. PostgreSQL (Base de Datos)
|
||||
|
||||
**Puerto**: 5432
|
||||
**Usuario**: architect
|
||||
**Base de datos**: TTZR (por defecto)
|
||||
**Uso**: Almacenamiento central de datos persistentes
|
||||
|
||||
#### Características:
|
||||
- Base de datos relacional centralizada
|
||||
- Backups automáticos en R2
|
||||
- Esquemas versionados
|
||||
- Logs de auditoría
|
||||
|
||||
#### Conexión:
|
||||
```bash
|
||||
# Conectar a PostgreSQL
|
||||
psql -h localhost -U architect -d TTZR
|
||||
|
||||
# Comandos básicos en psql:
|
||||
\dt # Listar tablas
|
||||
\d [tabla] # Ver estructura de tabla
|
||||
SELECT * FROM [tabla] LIMIT 10; # Consultar datos
|
||||
```
|
||||
|
||||
## Acceso a Servidores Remotos
|
||||
|
||||
Tienes acceso SSH a tres servidores remotos via la clave `~/.ssh/tzzr`:
|
||||
|
||||
### Servidores Disponibles
|
||||
|
||||
| Servidor | IP | Acceso | Rol |
|
||||
|----------|-----|--------|-----|
|
||||
| **deck** | 72.62.1.113 | root@72.62.1.113 | GPU/Computación |
|
||||
| **corp** | 92.112.181.188 | root@92.112.181.188 | Servicios corporativos |
|
||||
| **hst** | 72.62.2.84 | root@72.62.2.84 | HST-API + Directus |
|
||||
|
||||
#### Conectar a servidor remoto:
|
||||
```bash
|
||||
# Conexión general
|
||||
ssh root@[IP] -i ~/.ssh/tzzr
|
||||
|
||||
# Ejemplos:
|
||||
ssh root@72.62.1.113 -i ~/.ssh/tzzr # Conectar a deck
|
||||
ssh root@92.112.181.188 -i ~/.ssh/tzzr # Conectar a corp
|
||||
ssh root@72.62.2.84 -i ~/.ssh/tzzr # Conectar a hst
|
||||
```
|
||||
|
||||
## Almacenamiento R2 (Cloudflare)
|
||||
|
||||
### Configuración
|
||||
|
||||
**Endpoint**: https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
||||
**Bucket**: architect
|
||||
**Acceso**: via AWS CLI
|
||||
|
||||
### Estructura de Carpetas R2
|
||||
|
||||
```
|
||||
s3://architect/
|
||||
├── documentos adjuntos/ # Documentos para compartir con usuario
|
||||
├── documentos adjuntos/architect/ # Reportes y documentación generada
|
||||
├── system/ # Configs, backups internos, manuales
|
||||
├── gpu-services/ # Servicios GRACE/PENNY/FACTORY
|
||||
├── backups/ # Backups automáticos de Gitea/PostgreSQL
|
||||
└── auditorias/ # Logs de auditoría y eventos
|
||||
```
|
||||
|
||||
### Comandos R2 Básicos
|
||||
|
||||
#### Listar contenido:
|
||||
```bash
|
||||
# Listar raíz de bucket
|
||||
aws s3 ls s3://architect/ --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
||||
|
||||
# Listar carpeta específica
|
||||
aws s3 ls s3://architect/system/ --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
||||
|
||||
# Listar recursivamente
|
||||
aws s3 ls s3://architect/system/ --recursive --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
||||
```
|
||||
|
||||
#### Subir archivos:
|
||||
```bash
|
||||
# Subir documento para usuario
|
||||
aws s3 cp archivo.md "s3://architect/documentos adjuntos/archivo.md" \
|
||||
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
||||
|
||||
# Subir a system (configs, manuales, backups internos)
|
||||
aws s3 cp archivo "s3://architect/system/archivo" \
|
||||
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
||||
|
||||
# Subir carpeta completa
|
||||
aws s3 cp carpeta/ "s3://architect/system/carpeta/" --recursive \
|
||||
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
||||
```
|
||||
|
||||
#### Descargar archivos:
|
||||
```bash
|
||||
# Descargar archivo individual
|
||||
aws s3 cp "s3://architect/system/archivo" ./archivo \
|
||||
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
||||
|
||||
# Descargar carpeta recursivamente
|
||||
aws s3 cp "s3://architect/system/carpeta/" ./ --recursive \
|
||||
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
||||
```
|
||||
|
||||
## Gestión de Backups
|
||||
|
||||
### Backups Automáticos
|
||||
|
||||
El sistema realiza backups automáticos de:
|
||||
- **Gitea**: Repositorios y base de datos Gitea
|
||||
- **PostgreSQL**: Base de datos TTZR
|
||||
- Almacenados en: `s3://architect/backups/`
|
||||
|
||||
### Restaurar desde Backup
|
||||
|
||||
```bash
|
||||
# Listar backups disponibles
|
||||
aws s3 ls s3://architect/backups/ --recursive \
|
||||
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
||||
|
||||
# Descargar backup
|
||||
aws s3 cp "s3://architect/backups/[backup-name]" ./ \
|
||||
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
||||
|
||||
# Restaurar PostgreSQL desde dump
|
||||
psql -h localhost -U architect -d TTZR < backup.sql
|
||||
```
|
||||
|
||||
## Uso de context-manager Local
|
||||
|
||||
context-manager es una herramienta local para gestionar contexto de aplicaciones y bases de datos.
|
||||
|
||||
### Ubicación
|
||||
```
|
||||
/home/architect/captain-claude/context-manager/
|
||||
```
|
||||
|
||||
### Estructura
|
||||
|
||||
```
|
||||
context-manager/
|
||||
├── schemas/ # Esquemas SQL versionados
|
||||
│ ├── 00_base.sql
|
||||
│ ├── 01_immutable_log.sql
|
||||
│ ├── 02_context_manager.sql
|
||||
│ └── 03_algorithm_engine.sql
|
||||
├── src/ # Código Python
|
||||
│ ├── database.py # Conexión y operaciones BD
|
||||
│ ├── models.py # Modelos de datos
|
||||
│ ├── context_selector.py
|
||||
│ └── providers/ # Proveedores de IA
|
||||
│ ├── base.py
|
||||
│ ├── anthropic.py
|
||||
│ └── openai.py
|
||||
└── tests/ # Tests
|
||||
```
|
||||
|
||||
### Uso Básico
|
||||
|
||||
#### 1. Inicializar base de datos
|
||||
```bash
|
||||
cd /home/architect/captain-claude/context-manager
|
||||
python -m src.database init
|
||||
|
||||
# Ver estado de BD
|
||||
python -m src.database status
|
||||
```
|
||||
|
||||
#### 2. Guardar contexto
|
||||
```python
|
||||
from src.database import ContextManager
|
||||
|
||||
cm = ContextManager()
|
||||
|
||||
# Guardar contexto
|
||||
cm.save_context(
|
||||
context_id="task-123",
|
||||
content="Descripción de la tarea",
|
||||
metadata={"project": "skynet", "version": 8}
|
||||
)
|
||||
```
|
||||
|
||||
#### 3. Recuperar contexto
|
||||
```python
|
||||
# Recuperar contexto
|
||||
context = cm.get_context("task-123")
|
||||
print(context.content)
|
||||
print(context.metadata)
|
||||
|
||||
# Listar contextos
|
||||
contexts = cm.list_contexts(project="skynet")
|
||||
```
|
||||
|
||||
#### 4. Seleccionar contexto (IA)
|
||||
```python
|
||||
# Seleccionar contexto óptimo con IA
|
||||
selected = cm.select_context_ai(
|
||||
query="Necesito información sobre arquitectura",
|
||||
provider="anthropic" # o "openai"
|
||||
)
|
||||
```
|
||||
|
||||
### Variables de Entorno Requeridas
|
||||
|
||||
```bash
|
||||
# En ~/.bashrc o ~/.env
|
||||
export ANTHROPIC_API_KEY="sk-ant-..."
|
||||
export OPENAI_API_KEY="sk-..."
|
||||
export DATABASE_URL="postgresql://architect@localhost/TTZR"
|
||||
```
|
||||
|
||||
## Flujo de Trabajo Diario
|
||||
|
||||
### 1. Verificar Estado del Sistema
|
||||
```bash
|
||||
# Ver servicios activos
|
||||
systemctl status
|
||||
|
||||
# Ver logs de Gitea
|
||||
tail -f /var/log/gitea/gitea.log
|
||||
|
||||
# Ver conexión a PostgreSQL
|
||||
psql -h localhost -U architect -d TTZR -c "SELECT version();"
|
||||
```
|
||||
|
||||
### 2. Gestionar Repositorios
|
||||
```bash
|
||||
# Clonar nuevo repo desde Gitea
|
||||
git clone http://69.62.126.110:3000/architect/[proyecto].git
|
||||
|
||||
# Trabajar localmente
|
||||
cd [proyecto]
|
||||
git checkout -b feature/[nombre]
|
||||
# ... realizar cambios ...
|
||||
git add .
|
||||
git commit -m "Descripción de cambios"
|
||||
git push origin feature/[nombre]
|
||||
|
||||
# En Gitea: crear Pull Request y revisar
|
||||
```
|
||||
|
||||
### 3. Manejar Datos
|
||||
```bash
|
||||
# Backup de BD antes de cambios importantes
|
||||
pg_dump -h localhost -U architect TTZR > backup-$(date +%Y%m%d).sql
|
||||
|
||||
# Exportar desde R2
|
||||
aws s3 cp "s3://architect/backups/" ./backups/ --recursive \
|
||||
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
||||
```
|
||||
|
||||
### 4. Documentar y Archivar
|
||||
```bash
|
||||
# Generar documentación
|
||||
# ... crear archivos .md ...
|
||||
|
||||
# Subir a R2
|
||||
aws s3 cp reporte.md "s3://architect/documentos adjuntos/architect/reporte.md" \
|
||||
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
||||
|
||||
# Verificar subida
|
||||
aws s3 ls "s3://architect/documentos adjuntos/architect/" \
|
||||
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
||||
|
||||
# Limpiar local
|
||||
rm reporte.md
|
||||
```
|
||||
|
||||
## Seguridad y Mejores Prácticas
|
||||
|
||||
### SSH
|
||||
- Usa siempre la clave `~/.ssh/tzzr` para conectar a servidores remotos
|
||||
- Nunca compartas las claves SSH
|
||||
- Mantén permisos restrictivos: `chmod 600 ~/.ssh/tzzr`
|
||||
|
||||
### Credenciales
|
||||
- Nunca commits credenciales en Gitea
|
||||
- Usa variables de entorno para API keys
|
||||
- Rota credenciales regularmente
|
||||
|
||||
### R2
|
||||
- Verifica siempre que archivos se suban correctamente
|
||||
- No guardes documentos en el filesystem local
|
||||
- Limpia archivos locales después de subirlos a R2
|
||||
|
||||
### Base de Datos
|
||||
- Realiza backups antes de cambios estructurales
|
||||
- Usa transacciones para operaciones críticas
|
||||
- Revisa logs de auditoría regularmente
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### No puedo conectar a PostgreSQL
|
||||
```bash
|
||||
# Verificar que PostgreSQL está activo
|
||||
systemctl status postgresql
|
||||
|
||||
# Verificar permisos
|
||||
sudo -u postgres psql -c "SELECT * FROM pg_user WHERE usename = 'architect';"
|
||||
|
||||
# Reiniciar si es necesario
|
||||
sudo systemctl restart postgresql
|
||||
```
|
||||
|
||||
### Error al subir a R2
|
||||
```bash
|
||||
# Verificar credenciales AWS configuradas
|
||||
aws configure
|
||||
|
||||
# Verificar conectividad
|
||||
aws s3 ls s3://architect/ --endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
||||
|
||||
# Reintentar con --no-progress para más info
|
||||
aws s3 cp archivo s3://architect/system/archivo --no-progress \
|
||||
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
||||
```
|
||||
|
||||
### Gitea no responde
|
||||
```bash
|
||||
# Ver logs
|
||||
tail -f /var/log/gitea/gitea.log
|
||||
|
||||
# Reiniciar servicio
|
||||
sudo systemctl restart gitea
|
||||
|
||||
# Verificar puerto
|
||||
netstat -tlnp | grep 3000
|
||||
```
|
||||
|
||||
## Contacto y Soporte
|
||||
|
||||
Para problemas con los servicios o el servidor:
|
||||
1. Revisa los logs relevantes
|
||||
2. Verifica el estado del servicio
|
||||
3. Consulta la documentación en `s3://architect/system/`
|
||||
4. Contacta al administrador del sistema
|
||||
|
||||
## Referencias Rápidas
|
||||
|
||||
### Puertos Importantes
|
||||
- **Gitea**: 3000
|
||||
- **PostgreSQL**: 5432
|
||||
- **SSH**: 22
|
||||
|
||||
### Directorios Importantes
|
||||
- Proyectos: `/home/architect/captain-claude/`
|
||||
- Backups locales: `/home/architect/backups/`
|
||||
- Logs: `/var/log/`
|
||||
|
||||
### Comandos Frecuentes
|
||||
```bash
|
||||
# Actualizar repositorio
|
||||
cd /home/architect/[proyecto] && git pull
|
||||
|
||||
# Ver últimos cambios
|
||||
git log --oneline -10
|
||||
|
||||
# Conectar a BD
|
||||
psql -h localhost -U architect -d TTZR
|
||||
|
||||
# Listar en R2
|
||||
aws s3 ls s3://architect/system/ --recursive \
|
||||
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Última actualización**: Diciembre 2025
|
||||
**Versión**: 1.0
|
||||
1396
MANUAL_USUARIO_CORP.md
Normal file
1396
MANUAL_USUARIO_CORP.md
Normal file
File diff suppressed because it is too large
Load Diff
1439
MANUAL_USUARIO_DECK.md
Normal file
1439
MANUAL_USUARIO_DECK.md
Normal file
File diff suppressed because it is too large
Load Diff
608
MANUAL_USUARIO_HST.md
Normal file
608
MANUAL_USUARIO_HST.md
Normal file
@@ -0,0 +1,608 @@
|
||||
# MANUAL DE USUARIO - HST (Servidor 72.62.2.84)
|
||||
|
||||
## Introducción
|
||||
|
||||
HST es un servidor especializado en gestión de activos digitales y API de datos. Aloja la API principal (HST-API), tres instancias de Directus para gestión de contenidos, y un sistema de grafos con capacidades avanzadas de indexación.
|
||||
|
||||
## Información del Servidor
|
||||
|
||||
| Aspecto | Detalles |
|
||||
|--------|----------|
|
||||
| **IP** | 72.62.2.84 |
|
||||
| **Usuario** | root |
|
||||
| **Acceso SSH** | ssh root@72.62.2.84 -i ~/.ssh/tzzr |
|
||||
| **Ubicación** | Servidor HST |
|
||||
| **Rol** | API, gestión de contenidos, sistema de grafos |
|
||||
|
||||
## Servicios Disponibles
|
||||
|
||||
### 1. HST-API (API Principal)
|
||||
|
||||
**Puerto**: 5001
|
||||
**URL**: http://72.62.2.84:5001
|
||||
**Documentación**: http://72.62.2.84:5001/docs (OpenAPI/Swagger)
|
||||
**Base de datos**: PostgreSQL integrada
|
||||
|
||||
#### Características:
|
||||
- API REST para gestión de activos
|
||||
- Autenticación con tokens JWT
|
||||
- Documentación interactiva Swagger
|
||||
- Rate limiting y logging automático
|
||||
|
||||
#### Endpoints Principales:
|
||||
|
||||
```bash
|
||||
# Listar activos
|
||||
curl http://72.62.2.84:5001/api/v1/assets -H "Authorization: Bearer [token]"
|
||||
|
||||
# Obtener activo por ID
|
||||
curl http://72.62.2.84:5001/api/v1/assets/[id] -H "Authorization: Bearer [token]"
|
||||
|
||||
# Crear nuevo activo
|
||||
curl -X POST http://72.62.2.84:5001/api/v1/assets \
|
||||
-H "Authorization: Bearer [token]" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "Mi activo",
|
||||
"description": "Descripción",
|
||||
"tags": ["tag1", "tag2"],
|
||||
"metadata": {}
|
||||
}'
|
||||
|
||||
# Actualizar activo
|
||||
curl -X PUT http://72.62.2.84:5001/api/v1/assets/[id] \
|
||||
-H "Authorization: Bearer [token]" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name": "Nuevo nombre"}'
|
||||
|
||||
# Eliminar activo
|
||||
curl -X DELETE http://72.62.2.84:5001/api/v1/assets/[id] \
|
||||
-H "Authorization: Bearer [token]"
|
||||
```
|
||||
|
||||
#### Obtener Token de Autenticación:
|
||||
|
||||
```bash
|
||||
# Login
|
||||
curl -X POST http://72.62.2.84:5001/api/v1/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"username": "[usuario]",
|
||||
"password": "[contraseña]"
|
||||
}'
|
||||
|
||||
# Respuesta incluye token JWT
|
||||
# Usar en headers: Authorization: Bearer [token]
|
||||
```
|
||||
|
||||
#### Ver Documentación:
|
||||
Visita http://72.62.2.84:5001/docs en el navegador para documentación interactiva Swagger.
|
||||
|
||||
### 2. Directus CMS (3 Instancias)
|
||||
|
||||
**Instancias**: 8055, 8056, 8057
|
||||
**URLs**:
|
||||
- Instancia 1: http://72.62.2.84:8055
|
||||
- Instancia 2: http://72.62.2.84:8056
|
||||
- Instancia 3: http://72.62.2.84:8057
|
||||
|
||||
**Uso**: Gestión de contenidos, colecciones de datos, interfaz administrativa
|
||||
|
||||
#### Características Directus:
|
||||
- Interfaz web intuitiva para CRUD
|
||||
- Gestión de usuarios y permisos
|
||||
- API REST para acceso programático
|
||||
- Webhooks para automatización
|
||||
- Auditoría de cambios
|
||||
|
||||
#### Acceder a Directus:
|
||||
|
||||
```bash
|
||||
# Abrir en navegador
|
||||
# http://72.62.2.84:8055 (u 8056/8057)
|
||||
|
||||
# Usar SSH forward si accedes remotamente
|
||||
ssh root@72.62.2.84 -i ~/.ssh/tzzr -L 8055:localhost:8055
|
||||
|
||||
# Luego visitar http://localhost:8055 localmente
|
||||
```
|
||||
|
||||
#### Operaciones en Directus:
|
||||
|
||||
```bash
|
||||
# Obtener token de acceso
|
||||
curl -X POST http://72.62.2.84:8055/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"email": "[email]",
|
||||
"password": "[contraseña]"
|
||||
}'
|
||||
|
||||
# Listar colecciones
|
||||
curl http://72.62.2.84:8055/collections \
|
||||
-H "Authorization: Bearer [token]"
|
||||
|
||||
# Obtener items de colección
|
||||
curl http://72.62.2.84:8055/items/[colección] \
|
||||
-H "Authorization: Bearer [token]"
|
||||
|
||||
# Crear item
|
||||
curl -X POST http://72.62.2.84:8055/items/[colección] \
|
||||
-H "Authorization: Bearer [token]" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"campo1": "valor1",
|
||||
"campo2": "valor2"
|
||||
}'
|
||||
```
|
||||
|
||||
### 3. Graph System (Sistema de Grafos)
|
||||
|
||||
**Componente**: Sistema de indexación y consulta de grafos
|
||||
**Nodos**: 709
|
||||
**Edges**: 1134
|
||||
**Propósito**: Análisis relacional, búsqueda semántica, navegación de conectividades
|
||||
|
||||
#### Estadísticas del Grafo:
|
||||
|
||||
```
|
||||
┌─────────────────────┐
|
||||
│ GRAPH STATISTICS │
|
||||
├─────────────────────┤
|
||||
│ Total Nodes: 709 │
|
||||
│ Total Edges: 1134 │
|
||||
│ Density: 0.0044 │
|
||||
│ Avg Degree: 3.20 │
|
||||
└─────────────────────┘
|
||||
```
|
||||
|
||||
#### Consultas al Sistema de Grafos:
|
||||
|
||||
```bash
|
||||
# Obtener nodo por ID
|
||||
curl http://72.62.2.84:5001/api/v1/graph/nodes/[node-id] \
|
||||
-H "Authorization: Bearer [token]"
|
||||
|
||||
# Obtener nodos por tipo
|
||||
curl "http://72.62.2.84:5001/api/v1/graph/nodes?type=[tipo]" \
|
||||
-H "Authorization: Bearer [token]"
|
||||
|
||||
# Obtener vecinos de un nodo
|
||||
curl http://72.62.2.84:5001/api/v1/graph/nodes/[node-id]/neighbors \
|
||||
-H "Authorization: Bearer [token]"
|
||||
|
||||
# Obtener caminos más cortos entre dos nodos
|
||||
curl "http://72.62.2.84:5001/api/v1/graph/shortest-path?from=[id1]&to=[id2]" \
|
||||
-H "Authorization: Bearer [token]"
|
||||
|
||||
# Búsqueda por propiedades
|
||||
curl "http://72.62.2.84:5001/api/v1/graph/search?query=[término]&type=[tipo]" \
|
||||
-H "Authorization: Bearer [token]"
|
||||
|
||||
# Estadísticas del grafo
|
||||
curl http://72.62.2.84:5001/api/v1/graph/stats \
|
||||
-H "Authorization: Bearer [token]"
|
||||
```
|
||||
|
||||
#### Estructura de Nodos
|
||||
|
||||
Tipos principales de nodos:
|
||||
|
||||
```
|
||||
- entity: Entidades principales
|
||||
- document: Documentos y archivos
|
||||
- concept: Conceptos abstractos
|
||||
- organization: Organizaciones
|
||||
- person: Personas
|
||||
- asset: Activos digitales
|
||||
- tag: Etiquetas y clasificadores
|
||||
```
|
||||
|
||||
#### Tipos de Edges
|
||||
|
||||
Relaciones entre nodos:
|
||||
|
||||
```
|
||||
- HAS: Relación de pertenencia
|
||||
- REFERENCES: Referencia
|
||||
- RELATED_TO: Relacionado con
|
||||
- DEPENDS_ON: Depende de
|
||||
- CREATED_BY: Creado por
|
||||
- MODIFIED_BY: Modificado por
|
||||
- TAGGED_WITH: Etiquetado con
|
||||
```
|
||||
|
||||
## Gestión de Tags
|
||||
|
||||
El sistema de tags permite clasificar y filtrar activos dinámicamente.
|
||||
|
||||
### Tags Disponibles
|
||||
|
||||
```bash
|
||||
# Listar todos los tags
|
||||
curl http://72.62.2.84:5001/api/v1/tags \
|
||||
-H "Authorization: Bearer [token]"
|
||||
|
||||
# Obtener tag específico
|
||||
curl http://72.62.2.84:5001/api/v1/tags/[tag-name] \
|
||||
-H "Authorization: Bearer [token]"
|
||||
|
||||
# Crear nuevo tag
|
||||
curl -X POST http://72.62.2.84:5001/api/v1/tags \
|
||||
-H "Authorization: Bearer [token]" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "nuevo-tag",
|
||||
"description": "Descripción del tag",
|
||||
"color": "#FF5733"
|
||||
}'
|
||||
|
||||
# Actualizar tag
|
||||
curl -X PUT http://72.62.2.84:5001/api/v1/tags/[tag-name] \
|
||||
-H "Authorization: Bearer [token]" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"description": "Nueva descripción"}'
|
||||
|
||||
# Eliminar tag
|
||||
curl -X DELETE http://72.62.2.84:5001/api/v1/tags/[tag-name] \
|
||||
-H "Authorization: Bearer [token]"
|
||||
```
|
||||
|
||||
### Aplicar Tags a Activos
|
||||
|
||||
```bash
|
||||
# Agregar tag a activo
|
||||
curl -X POST http://72.62.2.84:5001/api/v1/assets/[asset-id]/tags \
|
||||
-H "Authorization: Bearer [token]" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"tag": "[tag-name]"}'
|
||||
|
||||
# Quitar tag de activo
|
||||
curl -X DELETE http://72.62.2.84:5001/api/v1/assets/[asset-id]/tags/[tag-name] \
|
||||
-H "Authorization: Bearer [token]"
|
||||
|
||||
# Filtrar activos por tag
|
||||
curl "http://72.62.2.84:5001/api/v1/assets?tags=[tag-name]" \
|
||||
-H "Authorization: Bearer [token]"
|
||||
|
||||
# Filtrar activos por múltiples tags
|
||||
curl "http://72.62.2.84:5001/api/v1/assets?tags=[tag1],[tag2]" \
|
||||
-H "Authorization: Bearer [token]"
|
||||
```
|
||||
|
||||
### Jerarquía de Tags
|
||||
|
||||
```bash
|
||||
# Crear tag secundario
|
||||
curl -X POST http://72.62.2.84:5001/api/v1/tags \
|
||||
-H "Authorization: Bearer [token]" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "subcategoría",
|
||||
"parent": "categoría-principal",
|
||||
"description": "Subtag"
|
||||
}'
|
||||
|
||||
# Obtener tags por categoría
|
||||
curl "http://72.62.2.84:5001/api/v1/tags?parent=[parent-tag]" \
|
||||
-H "Authorization: Bearer [token]"
|
||||
```
|
||||
|
||||
## API Endpoints Principales
|
||||
|
||||
### Activos
|
||||
|
||||
| Método | Endpoint | Descripción |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/v1/assets` | Listar activos |
|
||||
| GET | `/api/v1/assets/[id]` | Obtener activo |
|
||||
| POST | `/api/v1/assets` | Crear activo |
|
||||
| PUT | `/api/v1/assets/[id]` | Actualizar activo |
|
||||
| DELETE | `/api/v1/assets/[id]` | Eliminar activo |
|
||||
|
||||
### Tags
|
||||
|
||||
| Método | Endpoint | Descripción |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/v1/tags` | Listar tags |
|
||||
| POST | `/api/v1/tags` | Crear tag |
|
||||
| PUT | `/api/v1/tags/[name]` | Actualizar tag |
|
||||
| DELETE | `/api/v1/tags/[name]` | Eliminar tag |
|
||||
|
||||
### Sistema de Grafos
|
||||
|
||||
| Método | Endpoint | Descripción |
|
||||
|--------|----------|-------------|
|
||||
| GET | `/api/v1/graph/nodes` | Listar nodos |
|
||||
| GET | `/api/v1/graph/nodes/[id]` | Obtener nodo |
|
||||
| GET | `/api/v1/graph/nodes/[id]/neighbors` | Vecinos de nodo |
|
||||
| GET | `/api/v1/graph/edges` | Listar edges |
|
||||
| GET | `/api/v1/graph/shortest-path` | Camino más corto |
|
||||
| GET | `/api/v1/graph/search` | Búsqueda |
|
||||
| GET | `/api/v1/graph/stats` | Estadísticas |
|
||||
|
||||
### Directus
|
||||
|
||||
| Método | Endpoint (instancia 8055) | Descripción |
|
||||
|--------|----------|-------------|
|
||||
| POST | `/auth/login` | Autenticación |
|
||||
| GET | `/collections` | Listar colecciones |
|
||||
| GET | `/items/[collection]` | Listar items |
|
||||
| POST | `/items/[collection]` | Crear item |
|
||||
| PATCH | `/items/[collection]/[id]` | Actualizar item |
|
||||
| DELETE | `/items/[collection]/[id]` | Eliminar item |
|
||||
|
||||
## Ejemplos de Uso Comunes
|
||||
|
||||
### Flujo: Crear Activo con Tags en el Grafo
|
||||
|
||||
```bash
|
||||
# 1. Obtener token
|
||||
TOKEN=$(curl -s -X POST http://72.62.2.84:5001/api/v1/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"username": "usuario",
|
||||
"password": "contraseña"
|
||||
}' | jq -r '.token')
|
||||
|
||||
# 2. Crear activo
|
||||
ASSET=$(curl -s -X POST http://72.62.2.84:5001/api/v1/assets \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "Nuevo Activo",
|
||||
"description": "Descripción",
|
||||
"tags": []
|
||||
}' | jq -r '.id')
|
||||
|
||||
echo "Activo creado: $ASSET"
|
||||
|
||||
# 3. Crear tag si no existe
|
||||
curl -s -X POST http://72.62.2.84:5001/api/v1/tags \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"name": "mi-tag",
|
||||
"description": "Mi etiqueta"
|
||||
}'
|
||||
|
||||
# 4. Asociar tag al activo
|
||||
curl -s -X POST http://72.62.2.84:5001/api/v1/assets/$ASSET/tags \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"tag": "mi-tag"}'
|
||||
|
||||
echo "Tag asociado al activo"
|
||||
|
||||
# 5. Crear nodo en el grafo
|
||||
curl -s -X POST http://72.62.2.84:5001/api/v1/graph/nodes \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"type": "asset",
|
||||
"properties": {
|
||||
"asset_id": "'$ASSET'",
|
||||
"name": "Nuevo Activo"
|
||||
}
|
||||
}'
|
||||
|
||||
echo "Nodo del grafo creado"
|
||||
```
|
||||
|
||||
### Flujo: Buscar Activos por Tag y Explorar Relaciones
|
||||
|
||||
```bash
|
||||
# 1. Buscar activos por tag
|
||||
curl "http://72.62.2.84:5001/api/v1/assets?tags=importante" \
|
||||
-H "Authorization: Bearer $TOKEN" | jq '.'
|
||||
|
||||
# 2. Para cada activo, obtener su nodo en el grafo
|
||||
ASSET_ID="[obtenido del paso anterior]"
|
||||
GRAPH_NODE=$(curl -s "http://72.62.2.84:5001/api/v1/graph/nodes?asset_id=$ASSET_ID" \
|
||||
-H "Authorization: Bearer $TOKEN" | jq -r '.nodes[0].id')
|
||||
|
||||
# 3. Explorar vecinos del nodo
|
||||
curl "http://72.62.2.84:5001/api/v1/graph/nodes/$GRAPH_NODE/neighbors" \
|
||||
-H "Authorization: Bearer $TOKEN" | jq '.'
|
||||
|
||||
# 4. Encontrar caminos a otros nodos
|
||||
curl "http://72.62.2.84:5001/api/v1/graph/shortest-path?from=$GRAPH_NODE&to=[otro-nodo]" \
|
||||
-H "Authorization: Bearer $TOKEN" | jq '.'
|
||||
```
|
||||
|
||||
## Mantenimiento y Operaciones
|
||||
|
||||
### Verificar Estado de Servicios
|
||||
|
||||
```bash
|
||||
# Conectar al servidor
|
||||
ssh root@72.62.2.84 -i ~/.ssh/tzzr
|
||||
|
||||
# Verificar servicios activos
|
||||
systemctl status
|
||||
|
||||
# Ver logs de HST-API
|
||||
journalctl -u hst-api -f
|
||||
|
||||
# Ver logs de Directus
|
||||
journalctl -u directus -f
|
||||
```
|
||||
|
||||
### Backup de Datos
|
||||
|
||||
```bash
|
||||
# Descargar datos de Directus (instancia 8055)
|
||||
curl "http://72.62.2.84:8055/items/[colección]?export=json" \
|
||||
-H "Authorization: Bearer $TOKEN" > backup.json
|
||||
|
||||
# Backup de grafo
|
||||
curl "http://72.62.2.84:5001/api/v1/graph/export" \
|
||||
-H "Authorization: Bearer $TOKEN" > grafo-backup.json
|
||||
|
||||
# Guardar en R2
|
||||
aws s3 cp backup.json "s3://architect/backups/hst-backup-$(date +%Y%m%d).json" \
|
||||
--endpoint-url https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com
|
||||
```
|
||||
|
||||
### Monitoreo
|
||||
|
||||
```bash
|
||||
# Estadísticas del grafo
|
||||
curl http://72.62.2.84:5001/api/v1/graph/stats \
|
||||
-H "Authorization: Bearer $TOKEN" | jq '.'
|
||||
|
||||
# Contador de activos
|
||||
curl "http://72.62.2.84:5001/api/v1/assets?limit=1" \
|
||||
-H "Authorization: Bearer $TOKEN" | jq '.total'
|
||||
|
||||
# Usar en script de monitoreo
|
||||
while true; do
|
||||
echo "[$(date)] Estado del sistema HST:"
|
||||
curl -s http://72.62.2.84:5001/api/v1/graph/stats \
|
||||
-H "Authorization: Bearer $TOKEN" | jq '.node_count, .edge_count'
|
||||
sleep 300 # Cada 5 minutos
|
||||
done
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### HST-API no responde
|
||||
|
||||
```bash
|
||||
# Verificar si está corriendo
|
||||
ps aux | grep hst-api
|
||||
|
||||
# Ver logs
|
||||
journalctl -u hst-api -n 50
|
||||
|
||||
# Reiniciar servicio
|
||||
systemctl restart hst-api
|
||||
|
||||
# Verificar puerto
|
||||
netstat -tlnp | grep 5001
|
||||
```
|
||||
|
||||
### Error de autenticación
|
||||
|
||||
```bash
|
||||
# Verificar credenciales válidas
|
||||
curl -X POST http://72.62.2.84:5001/api/v1/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"usuario","password":"contraseña"}'
|
||||
|
||||
# Si error 401, credenciales incorrectas
|
||||
# Si error 500, problema de servidor
|
||||
```
|
||||
|
||||
### Directus (8055/8056/8057) no accesible
|
||||
|
||||
```bash
|
||||
# SSH forwarding si accedes remotamente
|
||||
ssh root@72.62.2.84 -i ~/.ssh/tzzr -L 8055:localhost:8055
|
||||
|
||||
# Verificar que Directus está corriendo
|
||||
ps aux | grep directus
|
||||
|
||||
# Ver logs de Directus
|
||||
journalctl -u directus -n 50
|
||||
```
|
||||
|
||||
### Grafo bloqueado o lento
|
||||
|
||||
```bash
|
||||
# Estadísticas actuales
|
||||
curl http://72.62.2.84:5001/api/v1/graph/stats \
|
||||
-H "Authorization: Bearer $TOKEN" | jq '.'
|
||||
|
||||
# Si hay muchos nodos/edges, considerar:
|
||||
# - Archiving de datos viejos
|
||||
# - Índices de base de datos
|
||||
# - Optimización de consultas
|
||||
```
|
||||
|
||||
## Configuración Importante
|
||||
|
||||
### Variables de Entorno (en servidor HST)
|
||||
|
||||
```bash
|
||||
# HST-API
|
||||
export HST_API_PORT=5001
|
||||
export HST_DATABASE_URL="postgresql://hst_user:password@localhost/hst_db"
|
||||
export HST_JWT_SECRET="[tu-secret-jwt]"
|
||||
|
||||
# Directus (múltiples instancias)
|
||||
export DIRECTUS_HOST=0.0.0.0
|
||||
export DIRECTUS_PORT=8055 # Varía por instancia
|
||||
export DIRECTUS_ADMIN_EMAIL="admin@example.com"
|
||||
export DIRECTUS_ADMIN_PASSWORD="[contraseña]"
|
||||
```
|
||||
|
||||
### Puertos en Firewall
|
||||
|
||||
Asegúrate de que estos puertos estén abiertos:
|
||||
- 5001: HST-API
|
||||
- 8055, 8056, 8057: Directus (3 instancias)
|
||||
- 5432: PostgreSQL (si es accesible)
|
||||
|
||||
```bash
|
||||
# Verificar firewall
|
||||
ufw status
|
||||
|
||||
# Si es necesario, abrir puertos
|
||||
ufw allow 5001/tcp
|
||||
ufw allow 8055/tcp
|
||||
ufw allow 8056/tcp
|
||||
ufw allow 8057/tcp
|
||||
```
|
||||
|
||||
## Referencias Rápidas
|
||||
|
||||
### Puertos Importantes
|
||||
- **HST-API**: 5001
|
||||
- **Directus 1**: 8055
|
||||
- **Directus 2**: 8056
|
||||
- **Directus 3**: 8057
|
||||
|
||||
### URLs Frecuentes
|
||||
```
|
||||
API Docs: http://72.62.2.84:5001/docs
|
||||
HST-API: http://72.62.2.84:5001
|
||||
Directus 1: http://72.62.2.84:8055
|
||||
Directus 2: http://72.62.2.84:8056
|
||||
Directus 3: http://72.62.2.84:8057
|
||||
```
|
||||
|
||||
### Comandos Frecuentes
|
||||
|
||||
```bash
|
||||
# Conectar al servidor
|
||||
ssh root@72.62.2.84 -i ~/.ssh/tzzr
|
||||
|
||||
# Forward Directus localmente
|
||||
ssh root@72.62.2.84 -i ~/.ssh/tzzr -L 8055:localhost:8055
|
||||
|
||||
# Obtener token
|
||||
curl -X POST http://72.62.2.84:5001/api/v1/auth/login \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"username":"usuario","password":"contraseña"}'
|
||||
|
||||
# Listar activos
|
||||
curl http://72.62.2.84:5001/api/v1/assets \
|
||||
-H "Authorization: Bearer [token]"
|
||||
|
||||
# Stats del grafo
|
||||
curl http://72.62.2.84:5001/api/v1/graph/stats \
|
||||
-H "Authorization: Bearer [token]"
|
||||
```
|
||||
|
||||
## Documentación Completa
|
||||
|
||||
Para documentación completa de cada servicio:
|
||||
- **HST-API**: http://72.62.2.84:5001/docs (OpenAPI/Swagger)
|
||||
- **Directus**: Documentación en cada instancia o https://docs.directus.io
|
||||
- **Sistema de Grafos**: Consulta documentación interna en `s3://architect/system/`
|
||||
|
||||
---
|
||||
|
||||
**Última actualización**: Diciembre 2025
|
||||
**Versión**: 1.0
|
||||
@@ -1,400 +0,0 @@
|
||||
# Glosario Consolidado — Sistema SHE Enterprise v5.0
|
||||
|
||||
**Versión:** 1.0
|
||||
**Fecha:** Diciembre 2025
|
||||
**Fuentes:** Documentación técnica SHE, Sistema de Registro Inmutable v1.2, Análisis de Paradigmas
|
||||
|
||||
---
|
||||
|
||||
## 1. ARQUITECTURA CENTRAL
|
||||
|
||||
### 1.1 Sistema Principal
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **SHE** | **S**emantic **H**ashtag **E**ngine. Motor narrativo-relacional que gestiona el flujo de estados y transiciones entre entidades. Es la caja fuerte de custodia (Milestones + Bloques). |
|
||||
| **HST** | **H**ash **S**emantic **T**agging. Sistema de etiquetado semántico mediante etiquetas de 3 caracteres que proporciona clasificación visual e inmutable. |
|
||||
|
||||
### 1.2 Componentes del Sistema de Registro Inmutable
|
||||
|
||||
| Término | Versión Personal | Versión Corporativa | Definición |
|
||||
|---------|------------------|---------------------|------------|
|
||||
| **Producción** | Alfred | Jared | Almacena árboles de procesos y flujos predefinidos. Implementado con Windmill/n8n. |
|
||||
| **Secretaría** | Clara | Margaret | Punto de entrada inmutable. Todo dato ingresa exactamente como llegó. Registro permanente. |
|
||||
| **Administración** | Mason | Mason | Tabla de trabajo temporal para enriquecer y consolidar información antes de registro definitivo. |
|
||||
| **Libros contables** | Feldman | Feldman | Registro final definitivo e inmutable. Contiene cola de validación + registro final. |
|
||||
| **Gestoría** | Grace | Grace | Capa cognitiva con 18 módulos de IA para transformación de datos. Intercambiable. |
|
||||
|
||||
---
|
||||
|
||||
## 2. LA TRÍADA DE PLANOS
|
||||
|
||||
| Plano | Tabla Principal | Naturaleza | Descripción |
|
||||
|-------|-----------------|------------|-------------|
|
||||
| **Cannon** | Ítems | Definición perfecta | Especificaciones, planos, recetas. No consume energía. |
|
||||
| **Burocrático** | Milestones | Estado legal/contable | Documentos, contratos, estados en vigor. Consume energía jurídica. |
|
||||
| **Físico** | Bloques | Evidencia material | Fotos, registros, pruebas físicas. Consume energía real. |
|
||||
|
||||
> **Regla de Oro**: Una burocracia sin evidencia física es ficción. Un ítem sin milestone es solo una idea. Un bloque sin contexto es ruido.
|
||||
|
||||
---
|
||||
|
||||
## 3. ENTIDADES PRINCIPALES
|
||||
|
||||
### 3.1 Milestones (Plano Burocrático)
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **Milestone** | Registro en el plano burocrático que representa estados legales, contables o hitos documentales. |
|
||||
| **tipo_item** | Clasificación del milestone: `documento`, `estado`, `hito`, `evento`, `version`. |
|
||||
| **roothash** | Cadena de IDs ancestrales que permite reconstruir la jerarquía completa. Formato: `/id_raiz/id_padre/.../id_actual` |
|
||||
|
||||
#### Estados de Milestone
|
||||
|
||||
| Estado | Descripción |
|
||||
|--------|-------------|
|
||||
| `draft` | Borrador inicial |
|
||||
| `active` | En ejecución |
|
||||
| `on_hold` | Pausado |
|
||||
| `completed` | Finalizado |
|
||||
| `cancelled` | Cancelado (terminal) |
|
||||
| `archived` | Archivado (terminal) |
|
||||
|
||||
### 3.2 Bloques (Plano Físico)
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **Bloque** | Unidad de evidencia física vinculada a un Milestone. Fotografía energética del intervalo T0 → T+1. |
|
||||
| **tipo_accion** | Clasificación del bloque: `punto`, `secuencia`, `esfuerzo_maximo`. |
|
||||
| **evidencia_url** | URL obligatoria de la evidencia física (foto, archivo, registro). |
|
||||
| **evidencia_hash** | SHA-256 del archivo de evidencia para verificación de integridad. |
|
||||
|
||||
#### Tipos de Acción en Bloques
|
||||
|
||||
| Tipo | Descripción | Energía |
|
||||
|------|-------------|---------|
|
||||
| **Generadora** | Crea nuevo valor (diseño, producción) | Alta |
|
||||
| **Preservadora** | Mantiene estado (almacenamiento, backup) | Media |
|
||||
| **Transformadora** | Modifica existente (ensamblaje, edición) | Alta |
|
||||
| **Verificadora** | Confirma calidad (inspección, testing) | Baja |
|
||||
|
||||
### 3.3 Ítems (Plano Cannon)
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **Ítem** | Definición ideal de producto, proceso o servicio. Especificación perfecta que no consume energía. |
|
||||
| **tipo** | Clasificación: `producto`, `servicio`, `proceso`, `componente`, `protocolo`. |
|
||||
| **specs_estandar** | JSONB con especificaciones técnicas estructuradas. |
|
||||
|
||||
---
|
||||
|
||||
## 4. ENTIDADES AUXILIARES
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **Player** | Actor del sistema: `persona`, `empresa`, `departamento`, `sistema_ia`, `sensor_iot`. Entidad que puede actuar. |
|
||||
| **Bandera** | Marco jurídico/jurisdicción que gobierna operaciones. Define IVA, moneda, idioma, timezone. |
|
||||
| **Localización** | Ubicación física o lógica: `pais`, `region`, `ciudad`, `direccion`, `edificio`, `planta`, `sala`, `almacen`, `virtual`. |
|
||||
|
||||
---
|
||||
|
||||
## 5. SISTEMA HST — ETIQUETADO SEMÁNTICO
|
||||
|
||||
### 5.1 Conceptos Clave
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **H_maestro** | SHA-256 de la imagen primigenia. 64 caracteres hexadecimales. Clave primaria inmutable. |
|
||||
| **Imagen primigenia** | Conjunto mínimo de atributos que definen inequívocamente una entidad. Inmutable. |
|
||||
| **ref** | Etiqueta semántica de 3 caracteres que clasifica registros (ej: `inv`, `pjt`, `ord`). |
|
||||
| **Skin** | Capa de presentación que modifica visualización sin alterar datos subyacentes. |
|
||||
| **hash_visible** | H_left(30) + estilo(4) + H_right(30). Identifica skin específico. |
|
||||
|
||||
### 5.2 Grupos de Etiquetas
|
||||
|
||||
| Grupo | Propiedad | Memorizable | Descripción |
|
||||
|-------|-----------|-------------|-------------|
|
||||
| **hst** | Sistema | ✅ Sí | Vocabulario semántico universal, inmutable |
|
||||
| **spe** | Sistema | ❌ No | Especificaciones técnicas |
|
||||
| **hsu** | Usuario | ✅ Sí | Etiquetas personales del usuario |
|
||||
| **msu** | Usuario | ❌ No | Metodologías personales |
|
||||
|
||||
### 5.3 Catálogo de Etiquetas (ref)
|
||||
|
||||
| ref | Nombre | Grupo | Descripción |
|
||||
|-----|--------|-------|-------------|
|
||||
| **inc** | Incidencia | Origen | Punto de entrada inicial |
|
||||
| **pjt** | Proyecto | Origen | Contenedor principal de trabajo |
|
||||
| **prp** | Propuesta | Origen | Oferta comercial |
|
||||
| **ord** | Pedido | Transacción | Orden de compra/venta |
|
||||
| **inv** | Factura recibida | Transacción | Documento fiscal de proveedor |
|
||||
| **siv** | Factura emitida | Transacción | Documento fiscal propio |
|
||||
| **pay** | Pago | Transacción | Transacción monetaria |
|
||||
| **exl** | Gasto | Transacción | Salida de dinero |
|
||||
| **whs** | Almacén | Logístico | Ubicación de stock |
|
||||
| **inn** | Entrada | Logístico | Recepción de material |
|
||||
| **out** | Salida | Logístico | Expedición de material |
|
||||
| **pct** | Producción | Productivo | Proceso productivo |
|
||||
| **sod** | Albarán | Logístico | Documento de entrega |
|
||||
| **doc** | Documento | Documental | Archivo genérico |
|
||||
| **ctr** | Contrato | Documental | Acuerdo legal |
|
||||
| **lic** | Licencia | Documental | Permiso/autorización |
|
||||
|
||||
---
|
||||
|
||||
## 6. ORQUESTACIÓN Y FLUJOS
|
||||
|
||||
### 6.1 Alfred (Producción)
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **Alfred** | Orquestador determinista (n8n/Windmill). NO es IA. Ejecuta Métodos de forma determinista. |
|
||||
| **Jared** | Versión corporativa de Alfred para gestionar múltiples usuarios. |
|
||||
|
||||
### 6.2 Métodos
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **Método** | Receta JSON pública que define procedimiento operativo. Secuencia de pasos atómicos. |
|
||||
| **h_metodo** | SHA-256 del JSON del Método. Identificador único e inmutable. |
|
||||
| **step_id** | Identificador del paso dentro del Método. |
|
||||
|
||||
### 6.3 Tipos de Paso en Métodos
|
||||
|
||||
| Tipo | Descripción | Ejemplo |
|
||||
|------|-------------|---------|
|
||||
| **module** | Invoca módulo Grace | `grace.parser` |
|
||||
| **action** | Operación CRUD | `create_relation` |
|
||||
| **condition** | Bifurcación lógica | `if amount > 1000` |
|
||||
| **wait** | Espera evento externo | `approval_received` |
|
||||
| **notify** | Envía notificación | `email`, `webhook` |
|
||||
|
||||
---
|
||||
|
||||
## 7. GRACE (GESTORÍA) — MÓDULOS IA
|
||||
|
||||
### 7.1 Conceptos
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **Grace (gestoría)** | Capa cognitiva. Colección de 18 microservicios de IA especializados. Transforma datos, no decide flujos. |
|
||||
| **Contrato Común v1.2** | Interfaz universal para comunicación entre módulos Grace. Define estructura de Request/Response. |
|
||||
|
||||
### 7.2 Catálogo de Módulos (18)
|
||||
|
||||
| # | Módulo | Función |
|
||||
|---|--------|---------|
|
||||
| 1 | **PARSER** | Extracción de datos de documentos |
|
||||
| 2 | **CLASSIFIER** | Categorización, asigna etiquetas ref |
|
||||
| 3 | **VALIDATOR** | Verificación de datos contra reglas |
|
||||
| 4 | **SUGGESTER** | Recomendaciones rankeadas |
|
||||
| 5 | **NARRATOR** | Generación de texto natural |
|
||||
| 6 | **AUDITOR** | Detección de anomalías |
|
||||
| 7 | **MATCHER** | Conciliación de conjuntos |
|
||||
| 8 | **SUMMARIZER** | Resumen de documentos |
|
||||
| 9 | **TRANSLATOR** | Traducción de texto |
|
||||
| 10 | **EXTRACTOR** | OCR avanzado |
|
||||
| 11 | **PREDICTOR** | Pronóstico de series temporales |
|
||||
| 12 | **CLUSTERER** | Agrupación de datos |
|
||||
| 13 | **LINKER** | Detección de relaciones |
|
||||
| 14 | **SCORER** | Puntuación según criterios |
|
||||
| 15 | **ROUTER** | Enrutamiento de mensajes |
|
||||
| 16 | **RESPONDER** | Respuesta automática |
|
||||
| 17 | **MONITOR** | Vigilancia de métricas |
|
||||
| 18 | **LEARNER** | Mejora continua de modelos |
|
||||
|
||||
---
|
||||
|
||||
## 8. FLUJOS OPERATIVOS
|
||||
|
||||
### 8.1 Flujos del Sistema de Registro Inmutable
|
||||
|
||||
| Flujo | Condición | Ruta |
|
||||
|-------|-----------|------|
|
||||
| **Estándar** | Entrada manual, requiere enriquecimiento | Clara → Mason → Feldman |
|
||||
| **Producción** | Proceso predefinido completo | Alfred → Clara → Feldman |
|
||||
| **Incidencia** | Improvisación durante flujo | Clara → Mason → Feldman |
|
||||
|
||||
### 8.2 Flujos HST Estándar
|
||||
|
||||
| Flujo | Secuencia | Descripción |
|
||||
|-------|-----------|-------------|
|
||||
| **Compra completa** | `inc → pjt → prp → ord → exl → sod → inv → pay` | Ciclo completo de compra |
|
||||
| **Compra directa** | `inc → exl → sod → inv` | Gastos menores sin proyecto |
|
||||
| **Producción** | `inc → whs → inn → pct → out` | Transformación interna |
|
||||
|
||||
---
|
||||
|
||||
## 9. PARADIGMA TEMPORAL
|
||||
|
||||
### 9.1 Línea Temporal
|
||||
|
||||
```
|
||||
T-N ────→ T-1 ────→ T0 ────→ T+1 ────→ T+N
|
||||
│ │ │ │ │
|
||||
Origen Pre- Inicio Cierre Futuro/
|
||||
Difuso consoli- Real Eviden- Histórico
|
||||
dación cia
|
||||
```
|
||||
|
||||
| Punto | Significado | Características |
|
||||
|-------|-------------|-----------------|
|
||||
| **T−N** | Origen difuso | Exploración, ideas no consolidadas |
|
||||
| **T−1** | Referencia previa | Punto desde el cual planificar |
|
||||
| **T0** | Inicio ejecución | Arranque formal, recursos comprometidos |
|
||||
| **T+1** | Hito burocrático | Registro formal de cierre operativo |
|
||||
| **T+N** | Resultado consolidado | Materialización real en el mundo |
|
||||
|
||||
### 9.2 Naturaleza Temporal de Entidades
|
||||
|
||||
| Entidad | Intervalo | Naturaleza |
|
||||
|---------|-----------|------------|
|
||||
| **Ítem** | T-N → T-1 → T0 | Definición ideal, proceso, producto conceptual |
|
||||
| **Milestone** | T0 → T+1 | Estado contable/legal en vigor |
|
||||
| **Bloque** | T+1 | Evidencia física de la ejecución |
|
||||
|
||||
---
|
||||
|
||||
## 10. SEGURIDAD Y TRAZABILIDAD
|
||||
|
||||
### 10.1 Sistemas de Protección
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **SENTINEL** | Sistema dual de auditoría y protección (LIGHT + DEEP). Nivel perimetral + interno. |
|
||||
| **NOTARIO** | Sistema de sellado blockchain con Merkle Tree para inmutabilidad temporal. |
|
||||
| **Key Vault** | Gestor centralizado de secretos y claves de cifrado. |
|
||||
|
||||
### 10.2 Cifrado
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **DEK** | Data Encryption Key. Llave efímera que cifra datos directamente. |
|
||||
| **KEK** | Key Encryption Key. Llave maestra que cifra otras llaves. |
|
||||
| **PII** | Personally Identifiable Information. Datos personales que requieren cifrado estricto. |
|
||||
|
||||
### 10.3 Perfiles de Cifrado
|
||||
|
||||
| Perfil | Uso | Rotación |
|
||||
|--------|-----|----------|
|
||||
| **ALTO** | Datos sensibles (PII, financieros) | 30 días |
|
||||
| **MEDIO** | Datos operativos | 90 días |
|
||||
| **BAJO** | Datos públicos | N/A |
|
||||
| **TRANSIT** | Datos en tránsito (TLS 1.3) | Por sesión |
|
||||
|
||||
---
|
||||
|
||||
## 11. ALMACENAMIENTO
|
||||
|
||||
### 11.1 Modelo de Temperaturas
|
||||
|
||||
| Temperatura | Ubicación | Latencia | Uso |
|
||||
|-------------|-----------|----------|-----|
|
||||
| **Hot** | Local + Redis | <100ms | Trabajo activo |
|
||||
| **Warm** | Storj DCS | <5s | Histórico < 1 año |
|
||||
| **Cold** | Arweave | <60s | Archivo permanente, inmutable |
|
||||
|
||||
### 11.2 Términos de Almacenamiento
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **Storj DCS** | Almacenamiento distribuido con erasure coding 80/29. Cifrado client-side. |
|
||||
| **Arweave** | Blockchain de almacenamiento permanente. Pago único, inmutable. |
|
||||
| **WORM** | Write Once Read Many. Política de almacenamiento inmutable. |
|
||||
|
||||
---
|
||||
|
||||
## 12. PARADIGMAS DE PROPIEDAD
|
||||
|
||||
| Paradigma | Propietario | Alcance | Mutabilidad | Prefijo |
|
||||
|-----------|-------------|---------|-------------|---------|
|
||||
| **Sistema** | Plataforma SHE | Universal | Ninguna | `sys_` |
|
||||
| **Organización** | Empresa | Multi-usuario interno | Controlada | `org_` |
|
||||
| **Usuario** | Individual | Personal | Total | `usr_` |
|
||||
|
||||
---
|
||||
|
||||
## 13. LOGGING Y AUDITORÍA
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **trace_id** | UUID v4 que identifica una ejecución completa de Método. |
|
||||
| **idempotency_key** | Clave SHA-256 para detección de duplicados en 24h. |
|
||||
| **audit_status** | Estado de auditoría: `PENDING`, `PASS`, `WARN`, `FAIL`. |
|
||||
|
||||
---
|
||||
|
||||
## 14. MÓDULOS COMPLEMENTARIOS
|
||||
|
||||
| Módulo | Función |
|
||||
|--------|---------|
|
||||
| **Vision Builder** | Herramienta de diseño visual de vida. Conecta objetivos con acciones. |
|
||||
| **Cloudville** | Simulador de estructuras organizativas con agentes IA. |
|
||||
| **Sistema de Voz** | Flujo autoalojado: VAD (Silero) → STT (Whisper) → NLU (LLM) → TTS (Coqui). |
|
||||
| **Bloques de Información** | Sistema de 6 elementos para trabajo con IAs: Contexto, Instrucción, Ejemplo, Restricción, Datos, Formato. |
|
||||
|
||||
---
|
||||
|
||||
## 15. PRINCIPIOS FUNDACIONALES
|
||||
|
||||
| Principio | Descripción |
|
||||
|-----------|-------------|
|
||||
| **Paradigma de Resultados** | El sistema registra resultados, no incidencias ni justificaciones. |
|
||||
| **Ocultación Legítima** | Si hay resultado válido, las incidencias del proceso no se documentan. |
|
||||
| **Acuerdo Bilateral** | Empresa ofrece herramientas; trabajador ofrece resultados evidenciados. |
|
||||
| **Trazabilidad como Movilidad** | La trazabilidad es portfolio verificable, no arma de control. |
|
||||
| **Flujo Energético** | Ante duda, analizar dónde se consume la energía clarifica la clasificación. |
|
||||
| **Tres Planos de Verdad** | Cannon, burocrático y físico deben estar interconectados. |
|
||||
| **Project Cannon** | Los tres documentos inseparables: Listado de Costes (qué), Árbol de Procesos (cómo), Gantt (cuándo). |
|
||||
|
||||
---
|
||||
|
||||
## 16. REGLAS DE VALIDACIÓN (Resumen)
|
||||
|
||||
### Reglas SHE (Estructurales)
|
||||
|
||||
| Código | Regla |
|
||||
|--------|-------|
|
||||
| SHE-E1 | Padre único (0..1 en propia tabla) |
|
||||
| SHE-E2 | Cruce único (0..1 con tabla opuesta) |
|
||||
| SHE-E3 | Anti-loop interno |
|
||||
| SHE-E4 | Anti-loop cruzado |
|
||||
| SHE-E5 | Proyecto único obligatorio |
|
||||
|
||||
### Reglas HST
|
||||
|
||||
| Código | Regla |
|
||||
|--------|-------|
|
||||
| HST-1 | Hash maestro inmutable |
|
||||
| HST-2 | Imagen primigenia inmutable |
|
||||
| HST-3 | Skins no alteran concepto |
|
||||
| HST-4 | Jerarquía coherente |
|
||||
|
||||
---
|
||||
|
||||
## 17. PROJECT CANNON
|
||||
|
||||
Los tres documentos fundamentales e inseparables para gestionar cualquier producción o proyecto.
|
||||
|
||||
| Documento | Pregunta | Contenido |
|
||||
|-----------|----------|-----------|
|
||||
| **Listado de Costes** | ¿Qué? | Materiales + Procesos (BOM expandido) |
|
||||
| **Árbol de Procesos** | ¿Cómo? | Secuencia y dependencias |
|
||||
| **Gráfica de Gantt** | ¿Cuándo? | Distribución temporal |
|
||||
|
||||
---
|
||||
|
||||
## 18. NOMENCLATURA OBSOLETA (Pendiente de revisión)
|
||||
|
||||
Términos heredados que deben sustituirse en la documentación.
|
||||
|
||||
| Término Obsoleto | Sustituto | Origen | Notas |
|
||||
|------------------|-----------|--------|-------|
|
||||
| SFE (System Flow Engine) | *Eliminado* | Concepto obsoleto | Ya sustituido por SHE donde aplicaba |
|
||||
| Pipeline | *Eliminar* | Jerga n8n | Concepto innecesario |
|
||||
| Santísima Trinidad Documental | **Project Cannon** | PARTE_I | Ya renombrado |
|
||||
| Ideal (plano) | **Cannon** | Tríada de Planos | Ya renombrado |
|
||||
|
||||
---
|
||||
|
||||
*— Fin del Glosario —*
|
||||
467
glosario_she_enterprise_v3.md
Normal file
467
glosario_she_enterprise_v3.md
Normal file
@@ -0,0 +1,467 @@
|
||||
# Glosario Consolidado — Sistema SHE Enterprise v5.1
|
||||
|
||||
**Versión:** 3.0
|
||||
**Fecha:** Diciembre 2025
|
||||
**Fuentes:** Documentación técnica SHE, Sistema de Registro Inmutable v1.2, Análisis de Paradigmas, CAPTAIN CLAUDE Coordinator
|
||||
**Actualización:** Incorporación de orquestación multi-agente y paradigma TZZR
|
||||
|
||||
---
|
||||
|
||||
## 1. ARQUITECTURA CENTRAL
|
||||
|
||||
### 1.1 Sistema Principal
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **SHE** | **S**emantic **H**ashtag **E**ngine. Motor narrativo-relacional que gestiona el flujo de estados y transiciones entre entidades. Es la caja fuerte de custodia (Milestones + Bloques). |
|
||||
| **HST** | **H**ash **S**emantic **T**agging. Sistema de etiquetado semántico mediante etiquetas de 3 caracteres que proporciona clasificación visual e inmutable. |
|
||||
| **TZZR** | **T**echnical **Z**ero-Trust **Z**oned **R**epository. Sistema centralizado de gobernanza, Gitea, PostgreSQL e Infisical en servidor 69.62.126.110. |
|
||||
|
||||
### 1.2 Componentes del Sistema de Registro Inmutable
|
||||
|
||||
| Término | Versión Personal | Versión Corporativa | Definición |
|
||||
|---------|------------------|---------------------|------------|
|
||||
| **Producción** | Alfred | Jared | Almacena árboles de procesos y flujos predefinidos. Implementado con Windmill/n8n. Determinista. |
|
||||
| **Secretaría** | Clara | Margaret | Punto de entrada inmutable. Todo dato ingresa exactamente como llegó. Registro permanente sin modificación. |
|
||||
| **Administración** | Mason | Mason | Tabla de trabajo temporal para enriquecer y consolidar información antes de registro definitivo. |
|
||||
| **Libros contables** | Feldman | Feldman | Registro final definitivo e inmutable. Contiene cola de validación + registro final. WORM. |
|
||||
| **Gestoría** | Grace | Grace | Capa cognitiva con 18 módulos de IA para transformación de datos. Intercambiable, agnóstica. |
|
||||
| **Orquestador** | CAPTAIN CLAUDE | CAPTAIN CLAUDE | Sistema multi-agente LLM que coordina flujos complejos. Supervisor central de TZZR. |
|
||||
|
||||
---
|
||||
|
||||
## 2. LA TRÍADA DE PLANOS
|
||||
|
||||
| Plano | Tabla Principal | Naturaleza | Descripción |
|
||||
|-------|-----------------|------------|-------------|
|
||||
| **Cannon** | Ítems | Definición perfecta | Especificaciones, planos, recetas. No consume energía. Inmutable por definición. |
|
||||
| **Burocrático** | Milestones | Estado legal/contable | Documentos, contratos, estados en vigor. Consume energía jurídica. Estados definidos. |
|
||||
| **Físico** | Bloques | Evidencia material | Fotos, registros, pruebas físicas. Consume energía real. Fotografía energética. |
|
||||
|
||||
> **Regla de Oro**: Una burocracia sin evidencia física es ficción. Un ítem sin milestone es solo una idea. Un bloque sin contexto es ruido.
|
||||
|
||||
### 2.1 Paradigma Temporal (T0 Framework)
|
||||
|
||||
```
|
||||
T-N ────→ T-1 ────→ T0 ────→ T+1 ────→ T+N
|
||||
│ │ │ │ │
|
||||
Origen Referencia Inicio Cierre Futuro/
|
||||
Difuso Previa Real Eviden- Histórico
|
||||
cia
|
||||
```
|
||||
|
||||
| Punto | Significado | Plano Asociado | Características |
|
||||
|-------|-------------|----------------|-----------------|
|
||||
| **T−N** | Origen difuso | Pre-Cannon | Exploración, ideas no consolidadas |
|
||||
| **T−1** | Referencia previa | Cannon | Punto desde el cual planificar, especificación |
|
||||
| **T0** | Inicio ejecución | Milestone (draft) | Arranque formal, recursos comprometidos |
|
||||
| **T+1** | Hito burocrático | Milestone (active/completed) | Registro formal de cierre operativo |
|
||||
| **T+N** | Resultado consolidado | Bloque | Materialización real en el mundo |
|
||||
|
||||
---
|
||||
|
||||
## 3. ENTIDADES PRINCIPALES
|
||||
|
||||
### 3.1 Milestones (Plano Burocrático)
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **Milestone** | Registro en el plano burocrático que representa estados legales, contables o hitos documentales. Ciclo de vida desde draft a archived. |
|
||||
| **tipo_item** | Clasificación del milestone: `documento`, `estado`, `hito`, `evento`, `version`. |
|
||||
| **roothash** | Cadena de IDs ancestrales que permite reconstruir la jerarquía completa. Formato: `/id_raiz/id_padre/.../id_actual` |
|
||||
|
||||
#### Estados de Milestone (Máquina de Estados)
|
||||
|
||||
| Estado | Descripción | Transiciones |
|
||||
|--------|-------------|--------------|
|
||||
| `draft` | Borrador inicial | → active, cancelled |
|
||||
| `active` | En ejecución | → on_hold, completed, cancelled |
|
||||
| `on_hold` | Pausado | → active, cancelled |
|
||||
| `completed` | Finalizado | → archived |
|
||||
| `cancelled` | Cancelado (terminal) | (ninguna) |
|
||||
| `archived` | Archivado (terminal) | (ninguna) |
|
||||
|
||||
### 3.2 Bloques (Plano Físico)
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **Bloque** | Unidad de evidencia física vinculada a un Milestone. Fotografía energética del intervalo T0 → T+1. Hash verificable. |
|
||||
| **tipo_accion** | Clasificación del bloque: `punto`, `secuencia`, `esfuerzo_maximo`. |
|
||||
| **evidencia_url** | URL obligatoria de la evidencia física (foto, archivo, registro). Almacenada en R2 o Arweave. |
|
||||
| **evidencia_hash** | SHA-256 del archivo de evidencia para verificación de integridad. Inmutable. |
|
||||
|
||||
#### Tipos de Acción en Bloques
|
||||
|
||||
| Tipo | Descripción | Energía | Frecuencia |
|
||||
|------|-------------|---------|-----------|
|
||||
| **Generadora** | Crea nuevo valor (diseño, producción) | Alta | Inicio de ciclo |
|
||||
| **Preservadora** | Mantiene estado (almacenamiento, backup) | Media | Continua |
|
||||
| **Transformadora** | Modifica existente (ensamblaje, edición) | Alta | Iterativa |
|
||||
| **Verificadora** | Confirma calidad (inspección, testing) | Baja | Hitos |
|
||||
|
||||
### 3.3 Ítems (Plano Cannon)
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **Ítem** | Definición ideal de producto, proceso o servicio. Especificación perfecta que no consume energía. Inmutable una vez definida. |
|
||||
| **tipo** | Clasificación: `producto`, `servicio`, `proceso`, `componente`, `protocolo`. |
|
||||
| **specs_estandar** | JSONB con especificaciones técnicas estructuradas. Schema validado. |
|
||||
| **version_canon** | Versión de especificación. Incrementa solo con cambios significativos. |
|
||||
|
||||
---
|
||||
|
||||
## 4. ENTIDADES AUXILIARES
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **Player** | Actor del sistema: `persona`, `empresa`, `departamento`, `sistema_ia`, `sensor_iot`. Entidad que puede actuar e iniciar flujos. |
|
||||
| **Bandera** | Marco jurídico/jurisdicción que gobierna operaciones. Define IVA, moneda, idioma, timezone, leyes aplicables. |
|
||||
| **Localización** | Ubicación física o lógica: `pais`, `region`, `ciudad`, `direccion`, `edificio`, `planta`, `sala`, `almacen`, `virtual`. |
|
||||
|
||||
---
|
||||
|
||||
## 5. SISTEMA HST — ETIQUETADO SEMÁNTICO
|
||||
|
||||
### 5.1 Conceptos Clave
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **H_maestro** | SHA-256 de la imagen primigenia. 64 caracteres hexadecimales. Clave primaria inmutable. Definitoria. |
|
||||
| **Imagen primigenia** | Conjunto mínimo de atributos que definen inequívocamente una entidad. Inmutable. Alma de la identidad. |
|
||||
| **ref** | Etiqueta semántica de 3 caracteres que clasifica registros (ej: `inv`, `pjt`, `ord`). Memorizable. |
|
||||
| **Skin** | Capa de presentación que modifica visualización sin alterar datos subyacentes. Intercambiable. |
|
||||
| **hash_visible** | H_left(30) + estilo(4) + H_right(30). Identifica skin específico. Cosmético pero determinista. |
|
||||
|
||||
### 5.2 Grupos de Etiquetas
|
||||
|
||||
| Grupo | Propiedad | Memorizable | Descripción |
|
||||
|-------|-----------|-------------|-------------|
|
||||
| **hst** | Sistema | ✅ Sí | Vocabulario semántico universal, inmutable, oficial |
|
||||
| **spe** | Sistema | ❌ No | Especificaciones técnicas, JSONB |
|
||||
| **hsu** | Usuario | ✅ Sí | Etiquetas personales del usuario, custom refs |
|
||||
| **msu** | Usuario | ❌ No | Metodologías personales, flujos privados |
|
||||
|
||||
### 5.3 Catálogo de Etiquetas (ref) - v3.1
|
||||
|
||||
| ref | Nombre | Grupo | Descripción |
|
||||
|-----|--------|-------|-------------|
|
||||
| **inc** | Incidencia | Origen | Punto de entrada inicial, disparador de flujo |
|
||||
| **pjt** | Proyecto | Origen | Contenedor principal de trabajo, epicentro |
|
||||
| **prp** | Propuesta | Origen | Oferta comercial, valuación preliminar |
|
||||
| **ord** | Pedido | Transacción | Orden de compra/venta, compromiso |
|
||||
| **inv** | Factura recibida | Transacción | Documento fiscal de proveedor, pasivo |
|
||||
| **siv** | Factura emitida | Transacción | Documento fiscal propio, activo |
|
||||
| **pay** | Pago | Transacción | Transacción monetaria, liquidación |
|
||||
| **exl** | Gasto | Transacción | Salida de dinero, erogación |
|
||||
| **whs** | Almacén | Logístico | Ubicación de stock, depósito |
|
||||
| **inn** | Entrada | Logístico | Recepción de material, ingreso |
|
||||
| **out** | Salida | Logístico | Expedición de material, egreso |
|
||||
| **pct** | Producción | Productivo | Proceso productivo, transformación |
|
||||
| **sod** | Albarán | Logístico | Documento de entrega, remisión |
|
||||
| **doc** | Documento | Documental | Archivo genérico, no clasificado |
|
||||
| **ctr** | Contrato | Documental | Acuerdo legal, vinculante |
|
||||
| **lic** | Licencia | Documental | Permiso/autorización, regulatorio |
|
||||
| **aud** | Auditoría | Compliance | Registro de inspección, verificación |
|
||||
| **ntf** | Notificación | Sistema | Alerta/evento, comunicación |
|
||||
|
||||
---
|
||||
|
||||
## 6. ORQUESTACIÓN Y FLUJOS
|
||||
|
||||
### 6.1 Alfred y Jared (Producción Determinista)
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **Alfred** | Orquestador determinista personal (n8n/Windmill). NO es IA. Ejecuta Métodos de forma determinista. |
|
||||
| **Jared** | Versión corporativa de Alfred para gestionar múltiples usuarios simultáneamente. Escalado. |
|
||||
|
||||
### 6.2 CAPTAIN CLAUDE (Orquestación Multi-Agente)
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **CAPTAIN CLAUDE** | Sistema multi-agente LLM que coordina flujos complejos, decisiones ramificadas y gestión de excepciones. Supervisor central de TZZR. Interpreta intención, no solo ejecuta. |
|
||||
| **Agente Especializado** | LLM con rol definido (vendedor, ingeniero, analista, etc.). Opera dentro de boundaries TZZR. |
|
||||
| **Contexto Compartido** | Estado distribuido que permite que agentes se comuniquen sin acoplamiento. Via Redis + Context Manager. |
|
||||
|
||||
### 6.3 Métodos
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **Método** | Receta JSON pública que define procedimiento operativo. Secuencia de pasos atómicos. Schema validado. |
|
||||
| **h_metodo** | SHA-256 del JSON del Método. Identificador único e inmutable. Auditable. |
|
||||
| **step_id** | Identificador del paso dentro del Método. Numerado secuencialmente o por UUID. |
|
||||
|
||||
### 6.4 Tipos de Paso en Métodos
|
||||
|
||||
| Tipo | Descripción | Ejemplo | Agente |
|
||||
|------|-------------|---------|--------|
|
||||
| **module** | Invoca módulo Grace | `grace.parser` | Grace |
|
||||
| **action** | Operación CRUD | `create_relation` | Feldman/Mason |
|
||||
| **condition** | Bifurcación lógica | `if amount > 1000` | CAPTAIN CLAUDE |
|
||||
| **wait** | Espera evento externo | `approval_received` | Sistema |
|
||||
| **notify** | Envía notificación | `email`, `webhook` | Penny (voz) |
|
||||
| **agent** | Delega a LLM especializado | `agente_vendedor.analiza_oferta` | LLM custom |
|
||||
|
||||
### 6.5 Flujos HST Estándar
|
||||
|
||||
| Flujo | Secuencia | Descripción |
|
||||
|-------|-----------|-------------|
|
||||
| **Compra completa** | `inc → pjt → prp → ord → exl → sod → inv → pay` | Ciclo completo de compra con auditoría |
|
||||
| **Compra directa** | `inc → exl → sod → inv` | Gastos menores sin proyecto |
|
||||
| **Producción** | `inc → whs → inn → pct → out` | Transformación interna de materia |
|
||||
| **Resolución de incidencia** | `inc → pjt → [Grace análisis] → sod → ctr` | Incidencia → Proyecto → Solución → Documentación |
|
||||
|
||||
---
|
||||
|
||||
## 7. GRACE (GESTORÍA) — MÓDULOS IA
|
||||
|
||||
### 7.1 Conceptos
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **Grace (gestoría)** | Capa cognitiva. Colección de 18 microservicios de IA especializados. Transforma datos, no decide flujos. Agnóstica de proveedor. |
|
||||
| **Contrato Común v2.1** | Interfaz universal para comunicación entre módulos Grace. Define estructura de Request/Response. JSON schema. |
|
||||
| **Módulo Grace** | Microservicio IA que implementa Contrato Común. Input → Procesa → Output. Documentado. |
|
||||
|
||||
### 7.2 Catálogo de Módulos Grace (18)
|
||||
|
||||
| # | Módulo | Función | Entrada | Salida |
|
||||
|---|--------|---------|---------|--------|
|
||||
| 1 | **PARSER** | Extracción de datos de documentos | Documento (PDF/IMG) | Entidades JSON |
|
||||
| 2 | **CLASSIFIER** | Categorización, asigna etiquetas ref | Texto/Documento | ref (hst/msu) + score |
|
||||
| 3 | **VALIDATOR** | Verificación de datos contra reglas | Datos + Esquema | PASS/FAIL + detalles |
|
||||
| 4 | **SUGGESTER** | Recomendaciones rankeadas | Contexto + Historial | Lista rankeada de sugerencias |
|
||||
| 5 | **NARRATOR** | Generación de texto natural | Datos + Template | Narrativa en lenguaje natural |
|
||||
| 6 | **AUDITOR** | Detección de anomalías | Serie de datos | Alertas + anomalías |
|
||||
| 7 | **MATCHER** | Conciliación de conjuntos | 2+ conjuntos de datos | Pares coincidentes + score |
|
||||
| 8 | **SUMMARIZER** | Resumen de documentos | Documento largo | Resumen conciso |
|
||||
| 9 | **TRANSLATOR** | Traducción de texto | Texto + idioma_origen + idioma_destino | Texto traducido |
|
||||
| 10 | **EXTRACTOR** | OCR avanzado + estructura | Imagen/PDF | Texto estructurado |
|
||||
| 11 | **PREDICTOR** | Pronóstico de series temporales | Series históricas + período | Pronóstico con intervalo |
|
||||
| 12 | **CLUSTERER** | Agrupación de datos | Dataset + k | Clusters con centroides |
|
||||
| 13 | **LINKER** | Detección de relaciones | 2+ entidades | Relaciones + tipo + peso |
|
||||
| 14 | **SCORER** | Puntuación según criterios | Entidad + criterios | Score numérico + componentes |
|
||||
| 15 | **ROUTER** | Enrutamiento de mensajes | Mensaje + destinos | Entrega a destino óptimo |
|
||||
| 16 | **RESPONDER** | Respuesta automática | Pregunta/Solicitud | Respuesta contextualizada |
|
||||
| 17 | **MONITOR** | Vigilancia de métricas | Métricas en tiempo real | Alertas + dashboards |
|
||||
| 18 | **LEARNER** | Mejora continua de modelos | Dataset + retroalimentación | Modelo mejorado |
|
||||
|
||||
---
|
||||
|
||||
## 8. SEGURIDAD Y TRAZABILIDAD
|
||||
|
||||
### 8.1 Sistemas de Protección
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **SENTINEL** | Sistema dual de auditoría y protección (LIGHT + DEEP). Nivel perimetral + interno. Validación continua. |
|
||||
| **SENTINEL LIGHT** | Perimetral: autenticación, autorización, acceso. Defensa en bordes. |
|
||||
| **SENTINEL DEEP** | Interno: auditoría de datos, detección de anomalías, verificación de integridad. Observabilidad completa. |
|
||||
| **NOTARIO** | Sistema de sellado blockchain con Merkle Tree para inmutabilidad temporal. Proof of existence. |
|
||||
| **Key Vault** | Gestor centralizado de secretos y claves de cifrado. Infisical en TZZR. |
|
||||
|
||||
### 8.2 Cifrado
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **DEK** | Data Encryption Key. Llave efímera que cifra datos directamente. Generada por sesión. |
|
||||
| **KEK** | Key Encryption Key. Llave maestra que cifra otras llaves. Almacenada en Key Vault. |
|
||||
| **Envelope Encryption** | Patrón: datos cifrados con DEK, DEK cifrada con KEK. Separación de responsabilidad. |
|
||||
| **PII** | Personally Identifiable Information. Datos personales que requieren cifrado estricto. GDPR. |
|
||||
|
||||
### 8.3 Perfiles de Cifrado
|
||||
|
||||
| Perfil | Uso | Rotación | Nivel |
|
||||
|--------|-----|----------|-------|
|
||||
| **ALTO** | Datos sensibles (PII, financieros) | 30 días | AES-256 + HMAC |
|
||||
| **MEDIO** | Datos operativos | 90 días | AES-192 |
|
||||
| **BAJO** | Datos públicos | N/A | Opcional |
|
||||
| **TRANSIT** | Datos en tránsito (TLS 1.3) | Por sesión | TLS 1.3 + ECDHE |
|
||||
|
||||
---
|
||||
|
||||
## 9. ALMACENAMIENTO
|
||||
|
||||
### 9.1 Modelo de Temperaturas
|
||||
|
||||
| Temperatura | Ubicación | Latencia | Uso | Retención |
|
||||
|-------------|-----------|----------|-----|-----------|
|
||||
| **Hot** | Local + Redis | <100ms | Trabajo activo | 7 días |
|
||||
| **Warm** | R2 (Cloudflare) | <5s | Histórico < 1 año | 1 año |
|
||||
| **Cold** | Arweave | <60s | Archivo permanente, inmutable | Permanente |
|
||||
|
||||
### 9.2 Términos de Almacenamiento
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **R2** | Almacenamiento S3-compatible de Cloudflare. Endpoint: https://7dedae6030f5554d99d37e98a5232996.r2.cloudflarestorage.com |
|
||||
| **Arweave** | Blockchain de almacenamiento permanente. Pago único, inmutable. Auditoría final. |
|
||||
| **WORM** | Write Once Read Many. Política de almacenamiento inmutable. Feldman usa WORM. |
|
||||
| **Bucket architect** | Bucket principal en R2 con carpetas: system/, documentos adjuntos/, auditorias/, backups/ |
|
||||
|
||||
---
|
||||
|
||||
## 10. PARADIGMAS DE PROPIEDAD
|
||||
|
||||
| Paradigma | Propietario | Alcance | Mutabilidad | Prefijo |
|
||||
|-----------|-------------|---------|-------------|---------|
|
||||
| **Sistema** | Plataforma SHE | Universal | Ninguna | `sys_` |
|
||||
| **Organización** | Empresa | Multi-usuario interno | Controlada | `org_` |
|
||||
| **Usuario** | Individual | Personal | Total | `usr_` |
|
||||
|
||||
---
|
||||
|
||||
## 11. LOGGING Y AUDITORÍA
|
||||
|
||||
| Término | Definición |
|
||||
|---------|------------|
|
||||
| **trace_id** | UUID v4 que identifica una ejecución completa de Método. Permite rastrear flujo entero. |
|
||||
| **idempotency_key** | Clave SHA-256 para detección de duplicados en 24h. Previene re-ejecución. |
|
||||
| **audit_status** | Estado de auditoría: `PENDING`, `PASS`, `WARN`, `FAIL`. Resultado de validación SENTINEL. |
|
||||
| **audit_log** | Registro inmutable de toda transacción. Almacenado en Feldman + Clara con hash verificable. |
|
||||
|
||||
---
|
||||
|
||||
## 12. REGLAS DE VALIDACIÓN (Resumen)
|
||||
|
||||
### Reglas SHE (Estructurales)
|
||||
|
||||
| Código | Regla | Explicación |
|
||||
|--------|-------|-------------|
|
||||
| SHE-E1 | Padre único (0..1 en propia tabla) | Una entidad no puede tener múltiples padres en la misma tabla |
|
||||
| SHE-E2 | Cruce único (0..1 con tabla opuesta) | Máximo 1 vínculo entre dos entidades opuestas |
|
||||
| SHE-E3 | Anti-loop interno | Una entidad no puede ser ancestro de sí misma en su tabla |
|
||||
| SHE-E4 | Anti-loop cruzado | Ciclos prohibidos entre tablas relacionadas |
|
||||
| SHE-E5 | Proyecto único obligatorio | Toda entidad operativa debe vincularse a un proyecto |
|
||||
|
||||
### Reglas HST
|
||||
|
||||
| Código | Regla | Aplicación |
|
||||
|--------|-------|-----------|
|
||||
| HST-1 | Hash maestro inmutable | H_maestro nunca cambia, define identidad |
|
||||
| HST-2 | Imagen primigenia inmutable | Atributos primarios son constantes |
|
||||
| HST-3 | Skins no alteran concepto | Visualización cosmética, no modifica datos |
|
||||
| HST-4 | Jerarquía coherente | Refs deben formar árbol válido sin ciclos |
|
||||
|
||||
---
|
||||
|
||||
## 13. PROJECT CANNON
|
||||
|
||||
Los tres documentos fundamentales e inseparables para gestionar cualquier producción o proyecto.
|
||||
|
||||
| Documento | Pregunta | Contenido | Propiedad |
|
||||
|-----------|----------|-----------|-----------|
|
||||
| **Listado de Costes** | ¿Qué? | Materiales + Procesos (BOM expandido) | Plano Cannon |
|
||||
| **Árbol de Procesos** | ¿Cómo? | Secuencia y dependencias | Plano Cannon |
|
||||
| **Gráfica de Gantt** | ¿Cuándo? | Distribución temporal | Milestones |
|
||||
|
||||
> **Regla:** No se aprueba proyecto sin los 3 documentos completos y consistentes.
|
||||
|
||||
---
|
||||
|
||||
## 14. PRINCIPIOS FUNDACIONALES v8
|
||||
|
||||
| Principio | Descripción |
|
||||
|-----------|-------------|
|
||||
| **Paradigma de Resultados** | El sistema registra resultados, no incidencias ni justificaciones. |
|
||||
| **Ocultación Legítima** | Si hay resultado válido, las incidencias del proceso no se documentan. |
|
||||
| **Acuerdo Bilateral** | Empresa ofrece herramientas; trabajador ofrece resultados evidenciados. |
|
||||
| **Trazabilidad como Movilidad** | La trazabilidad es portfolio verificable, no arma de control. |
|
||||
| **Flujo Energético** | Ante duda, analizar dónde se consume la energía clarifica la clasificación. |
|
||||
| **Tres Planos de Verdad** | Cannon, burocrático y físico deben estar interconectados. |
|
||||
| **Project Cannon** | Los tres documentos inseparables: Listado, Árbol, Gantt. |
|
||||
|
||||
---
|
||||
|
||||
## 15. MODELOS COMPLEMENTARIOS
|
||||
|
||||
| Modelo | Función | Propósito |
|
||||
|--------|---------|-----------|
|
||||
| **Vision Builder** | Herramienta de diseño visual de vida | Conecta objetivos con acciones |
|
||||
| **Cloudville** | Simulador de estructuras organizativas con agentes IA | Experimentación de configuraciones |
|
||||
| **Sistema de Voz (Penny)** | Flujo autoalojado: VAD → STT → NLU → TTS | Interfaz conversacional |
|
||||
| **Bloques de Información** | Sistema de 6 elementos para trabajo con IAs | Contexto, Instrucción, Ejemplo, Restricción, Datos, Formato |
|
||||
| **The Factory** | Generación iterativa de contenido | Desarrollo incremental |
|
||||
|
||||
---
|
||||
|
||||
## 16. NOMENCLATURA OBSOLETA (Pendiente de revisión)
|
||||
|
||||
Términos heredados que deben sustituirse en la documentación.
|
||||
|
||||
| Término Obsoleto | Sustituto | Origen | Notas |
|
||||
|------------------|-----------|--------|-------|
|
||||
| SFE (System Flow Engine) | *Eliminado* | Concepto obsoleto | Ya sustituido por SHE donde aplicaba |
|
||||
| Pipeline | *Eliminar* | Jerga n8n | Concepto innecesario, usar Método |
|
||||
| Santísima Trinidad Documental | **Project Cannon** | PARTE_I | Ya renombrado |
|
||||
| Ideal (plano) | **Cannon** | Tríada de Planos | Ya renombrado |
|
||||
| Orquestador genérico | **CAPTAIN CLAUDE** | v8 | Especificacion concreta |
|
||||
| Agentes TZZR | **Servicios TZZR** | v8 | Clara, Alfred, etc. son SERVICIOS, no agentes IA |
|
||||
|
||||
---
|
||||
|
||||
## 16.1 NOMENCLATURA OBLIGATORIA
|
||||
|
||||
**IMPORTANTE**: Los siguientes componentes son **SERVICIOS** (microservicios Python), **NO** son agentes de IA:
|
||||
|
||||
| Servicio | Funcion | Servidor |
|
||||
|----------|---------|----------|
|
||||
| Clara | Secretaria (ingesta inmutable) | DECK |
|
||||
| Alfred | Produccion (flujos) | DECK |
|
||||
| Mason | Administracion (enriquecimiento) | DECK/CORP |
|
||||
| Feldman | Contable (registro final) | DECK/CORP |
|
||||
| Margaret | Secretaria corporativa | CORP |
|
||||
| Jared | Produccion corporativa | CORP |
|
||||
|
||||
**Terminologia correcta:**
|
||||
- "Servicio Clara" o "Clara service"
|
||||
- "Microservicio Feldman"
|
||||
- "Servicios TZZR"
|
||||
|
||||
**Terminologia INCORRECTA (no usar):**
|
||||
- ~~"Agente Clara"~~
|
||||
- ~~"Agentes TZZR"~~
|
||||
- ~~"Agentes IA"~~ (excepto para Grace/CAPTAIN CLAUDE)
|
||||
|
||||
**Sistemas con IA:**
|
||||
- **Grace**: Capa cognitiva con modulos de IA
|
||||
- **CAPTAIN CLAUDE**: Sistema de coordinacion con LLM
|
||||
|
||||
---
|
||||
|
||||
## 17. ÍNDICE ALFABÉTICO RÁPIDO
|
||||
|
||||
**[A]** Acción | Agente | Almacén | Auditoría
|
||||
**[B]** Bloque | Bloques de información | Bucket
|
||||
**[C]** Cannon | CAPTAIN CLAUDE | Clasificación | Contrato Común | Contexto
|
||||
**[D]** DEK | Documento | Dashboard
|
||||
**[E]** Entidad | Enumeración | Especificación | Esquema
|
||||
**[F]** Feldman | Flagshot | Flujo | Frase
|
||||
**[G]** Glosario | Grace | Grafo
|
||||
**[H]** Hash | HST | h_maestro | h_metodo
|
||||
**[I]** Ítem | Imagen primigenia | Immutable Log
|
||||
**[J]** Jared | Jurisdicción
|
||||
**[K]** KEK | Key Vault
|
||||
**[L]** Localización | Listado | Licencia | Log
|
||||
**[M]** Maestro | Margaret | Mason | Método | Milestone | Módulo
|
||||
**[N]** Narración | Notario
|
||||
**[O]** Operativo | Orquestador
|
||||
**[P]** Parser | Payment | Player | Plano | Producción | Propuesta | Proyecto
|
||||
**[Q]** Query | Ruta
|
||||
**[R]** Receta | Ref | Relación | Resultado | R2 | Roothash
|
||||
**[S]** Secretaría | Sentimiento | Sentinel | Skin | SQL | Storage
|
||||
**[T]** Tabla | Tag | Temporal | Transacción | TZZR
|
||||
**[U]** Usuario | Utilidad
|
||||
**[V]** Validación | Versión | Vinculación
|
||||
**[W]** WORM
|
||||
**[X]** (no aplica)
|
||||
**[Y]** (no aplica)
|
||||
**[Z]** (no aplica)
|
||||
|
||||
---
|
||||
|
||||
*— Fin del Glosario v3 —*
|
||||
|
||||
**Última actualización:** 2025-12-30
|
||||
**Versión:** 3.0 - Sistema SHE Enterprise v5.1
|
||||
**Próxima revisión:** 2026-06-30
|
||||
Reference in New Issue
Block a user