diff --git a/07_OPERACION/INDEX.md b/07_OPERACION/INDEX.md new file mode 100644 index 0000000..0bf613c --- /dev/null +++ b/07_OPERACION/INDEX.md @@ -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 diff --git a/07_OPERACION/incident_response.md b/07_OPERACION/incident_response.md new file mode 100644 index 0000000..e1eef12 --- /dev/null +++ b/07_OPERACION/incident_response.md @@ -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 | 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 -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 + diff --git a/07_OPERACION/monitoring.md b/07_OPERACION/monitoring.md new file mode 100644 index 0000000..1700cc6 --- /dev/null +++ b/07_OPERACION/monitoring.md @@ -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 + diff --git a/07_OPERACION/runbooks.md b/07_OPERACION/runbooks.md new file mode 100644 index 0000000..649c8f2 --- /dev/null +++ b/07_OPERACION/runbooks.md @@ -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 | + diff --git a/MANUAL_USUARIO_ARCHITECT.md b/MANUAL_USUARIO_ARCHITECT.md new file mode 100644 index 0000000..02208b9 --- /dev/null +++ b/MANUAL_USUARIO_ARCHITECT.md @@ -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 diff --git a/MANUAL_USUARIO_CORP.md b/MANUAL_USUARIO_CORP.md new file mode 100644 index 0000000..ace57c1 --- /dev/null +++ b/MANUAL_USUARIO_CORP.md @@ -0,0 +1,1396 @@ +# MANUAL DE USUARIO - CORP +## Sistema TZZR - Skynet v8 +**Servidor:** 92.112.181.188 +**Fecha:** 2025-12-30 + +--- + +# Manual de Usuario CORP - Parte 1: Introducción y Aplicaciones + +## 1. Introducción a CORP + +### ¿Qué es CORP en el sistema TTZR? + +CORP (Corporate Services Server) es el servidor de servicios empresariales del sistema TTZR. Forma parte de la infraestructura distribuida del sistema central TTZR (69.62.126.110) y proporciona soluciones integradas para gestión empresarial, contenidos y operaciones. + +**Información del Servidor:** +- **IP**: 92.112.181.188 +- **Rol en TTZR**: Servicios empresariales y gestión de contenidos +- **Ubicación en infraestructura**: Servidor remoto accesible desde servidor central +- **Estado**: Operativo en sistema TTZR + +### Acceso SSH a CORP + +Para acceder al servidor CORP desde el servidor central TTZR o cualquier máquina autorizada: + +```bash +ssh -i ~/.ssh/tzzr root@92.112.181.188 +``` + +**Requisitos:** +- Tener la clave privada SSH en `~/.ssh/tzzr` +- Estar autorizado en el sistema TTZR +- Conexión de red hacia 92.112.181.188 + +**Ejemplo de uso:** +```bash +# Conexión básica +ssh -i ~/.ssh/tzzr root@92.112.181.188 + +# Ejecutar comando remoto +ssh -i ~/.ssh/tzzr root@92.112.181.188 "systemctl status" + +# Transferencia de archivos +scp -i ~/.ssh/tzzr archivo.txt root@92.112.181.188:/home/ +``` + +### Servicios Disponibles en CORP + +CORP aloja los siguientes servicios principales: + +| Servicio | Puerto | Descripción | Estado | +|----------|--------|-------------|--------| +| Odoo 17 | 8069 | ERP - Gestión empresarial integral | Activo | +| Directus 11 | 8055 | CMS - Gestión de contenidos | Activo | +| PostgreSQL | 5432 | Base de datos relacional | Activo | +| SSH | 22 | Acceso remoto administrativo | Activo | + +--- + +## 2. Odoo 17 (ERP) + +### Acceso a Odoo 17 + +**URL:** `http://92.112.181.188:8069` + +Abrir en navegador web para acceder a la interfaz de gestión empresarial. + +### ¿Qué es Odoo 17? + +Odoo es un suite empresarial completo (ERP - Enterprise Resource Planning) que integra todos los procesos de negocio en una plataforma unificada. Odoo 17 es la última versión estable con mejoras significativas en rendimiento, interfaz de usuario y capacidades de integración. + +**Características principales:** +- Gestión integrada de múltiples módulos empresariales +- Interfaz web moderna y responsive +- API REST para integraciones +- Sistema de permisos y roles granular +- Reportes y análisis avanzados + +### Módulos Disponibles en CORP + +Odoo 17 en CORP incluye los siguientes módulos principales: + +#### Módulos de Negocio +- **Ventas** (Sales) - Gestión de oportunidades, presupuestos y pedidos +- **Compras** (Purchases) - Gestión de compras y proveedores +- **Inventario** (Inventory) - Control de stock y almacenes +- **Facturación** (Invoicing) - Facturas de venta y compra +- **Contabilidad** (Accounting) - Contabilidad general y fiscal +- **CRM** (Customer Relationship Management) - Gestión de clientes y relaciones + +#### Módulos de Recursos +- **Recursos Humanos** (HR) - Gestión de empleados y nóminas +- **Proyectos** (Projects) - Gestión de proyectos y tareas +- **Servicios** (Services) - Gestión de servicios y SLA + +#### Módulos de Análisis +- **Business Intelligence** - Reportes y cuadros de mando +- **Analítica** - Seguimiento de actividades y análisis + +### Configuración Básica de Odoo 17 + +#### Acceso por Primera Vez +1. Abrir `http://92.112.181.188:8069` +2. Credenciales por defecto o las configuradas en la instalación +3. Cambiar contraseña en el perfil de usuario + +#### Configuración Inicial Recomendada + +**1. Empresas y Ubicaciones** +``` +Configuración > Empresas +- Crear/editar empresa principal +- Definir moneda y país +- Configurar información fiscal +``` + +**2. Usuarios y Permisos** +``` +Configuración > Usuarios y Acceso +- Crear usuarios por departamento +- Asignar roles (Gerente de Ventas, Contador, etc.) +- Configurar permisos específicos por módulo +``` + +**3. Plan Contable** +``` +Contabilidad > Configuración > Plan Contable +- Adaptar al país/jurisdicción +- Configurar cuentas personalizadas +``` + +**4. Almacenes** +``` +Inventario > Configuración > Almacenes +- Definir ubicaciones físicas +- Configurar rutas de envío +``` + +**5. Socios Comerciales** +``` +CRM > Clientes o Compras > Proveedores +- Importar base de datos existente +- Configurar categorías y grupos +``` + +#### Operaciones Diarias +- **Crear presupuestos/pedidos**: Sales > Quotations/Orders +- **Registrar compras**: Purchases > Purchase Orders +- **Gestionar inventario**: Inventory > Products/Stock +- **Emitir facturas**: Invoicing > Customer/Vendor Invoices +- **Registros contables**: Accounting > Journal Entries + +--- + +## 3. Directus 11 (CMS) + +### Acceso a Directus 11 + +**URL:** `http://92.112.181.188:8055` + +Interfaz web para gestión de contenidos y datos. + +### ¿Qué es Directus 11? + +Directus es un CMS (Content Management System) y gestor de datos headless moderno. Permite gestionar contenidos, bases de datos y medios sin estar atado a una presentación específica. Directus 11 es la versión más reciente con arquitectura mejorada y mejor rendimiento. + +**Características principales:** +- Gestión visual de bases de datos sin necesidad de SQL +- CMS flexible para cualquier tipo de contenido +- APIs REST y GraphQL automáticas +- Versionado y auditoría de cambios +- Gestión de acceso granular +- Sistema de flujos de trabajo (workflows) + +### Gestión de Contenidos + +#### Estructura de Datos +En Directus, los contenidos se organizan en **Colecciones**: + +**Colecciones Comunes:** +- **Pages** - Páginas web principales +- **Blog Posts** - Artículos y publicaciones +- **Products** - Catálogo de productos +- **Team** - Información del equipo +- **Settings** - Configuración global del sitio +- **Media** - Archivos de imagen y documentos + +#### Interfaz de Gestión + +**Panel Principal:** +``` +Interfaz > Collections (Colecciones) +- Crear, editar, eliminar elementos +- Organizar por campos personalizados +- Relaciones entre colecciones +``` + +**Campos Disponibles:** +- Texto (Text, Long Text) +- Números (Integer, Decimal) +- Selecciones (Dropdown, Multiple) +- Fechas y hora +- Booleanos +- Relaciones (Many-to-One, One-to-Many, Many-to-Many) +- Archivos (Imágenes, documentos) +- JSON +- Campos personalizados + +#### Gestión de Medios +``` +Archivos > Todos los archivos +- Subir imágenes y documentos +- Organizar en carpetas +- Transformaciones de imagen (redimensionamiento, filtros) +- Integración automática en colecciones +``` + +### API REST y GraphQL + +#### API REST + +Directus genera automáticamente una API REST basada en tu estructura de datos. + +**Endpoints automáticos:** +``` +GET /items/pages - Obtener todas las páginas +GET /items/pages/:id - Obtener página específica +POST /items/pages - Crear página +PATCH /items/pages/:id - Actualizar página +DELETE /items/pages/:id - Eliminar página +``` + +**Ejemplo de petición:** +```bash +curl -X GET "http://92.112.181.188:8055/api/items/pages" \ + -H "Authorization: Bearer TOKEN" +``` + +**Autenticación:** +```bash +curl -X POST "http://92.112.181.188:8055/auth/login" \ + -H "Content-Type: application/json" \ + -d '{"email":"usuario@ejemplo.com", "password":"contraseña"}' +``` + +#### API GraphQL + +Consultas GraphQL para obtener datos de forma más flexible: + +**Endpoint:** +``` +POST http://92.112.181.188:8055/graphql +``` + +**Ejemplo de consulta:** +```graphql +query { + pages { + id + title + content + created_at + } +} +``` + +**Con filtros:** +```graphql +query { + pages(filter: {status: {_eq: "published"}}) { + id + title + featured_image { + id + filename_disk + } + } +} +``` + +### Configuración de Directus 11 + +#### Acceso Administrativo +``` +Configuración > Access Control +- Roles y permisos +- Usuarios administradores +- Tokens API para automatización +``` + +#### Flujos de Trabajo (Workflows) +``` +Flujos de Trabajo > Crear Flujo +- Estados de contenido (Borrador, Pendiente revisión, Publicado) +- Aprobaciones automáticas +- Notificaciones +``` + +#### Extensiones e Integraciones +``` +Extensiones > Gestionar +- Hooks personalizados +- Campos personalizados +- Integraciones con servicios externos +``` + +#### Configuración de Base de Datos +``` +Configuración > Colecciones +- Crear nuevas colecciones +- Definir campos +- Establecer relaciones +``` + +--- + +## Próximas Secciones + +Este es el Manual CORP Parte 1. Las siguientes secciones incluirán: + +- **Parte 2**: Administración de CORP (Gestión de servicios, bases de datos, backups) +- **Parte 3**: Integración entre Odoo y Directus +- **Parte 4**: Mantenimiento y troubleshooting +- **Parte 5**: Procedimientos de respaldo y recuperación + +--- + +**Versión:** 1.0 +**Fecha:** 2025-12-30 +**Sistema:** TZZR - CORP (92.112.181.188) + +--- + +# Manual de Usuario CORP - PARTE 2: Servicios y Administración + +**Servidor**: corp (92.112.181.188) +**Documento**: Guía de servicios, microservicios y administración del sistema TTZR + +--- + +## 1. Otros Servicios + +### Nextcloud (Puerto 8080) +**Acceso**: http://92.112.181.188:8080 + +**Propósito**: Gestor de archivos compartidos, sincronización y colaboración + +**Funcionalidades principales**: +- Almacenamiento personal y compartido +- Sincronización de archivos entre dispositivos +- Sharing de carpetas con permisos granulares +- Editor de documentos colaborativo +- Gestión de calendarios y contactos + +**Tareas comunes**: +```bash +# Ver estado del contenedor +docker ps | grep nextcloud + +# Acceder a logs +docker logs nextcloud + +# Reiniciar servicio +docker restart nextcloud +``` + +--- + +### Vaultwarden (Puerto 8081) +**Acceso**: http://92.112.181.188:8081 + +**Propósito**: Gestor de contraseñas y secretos cifrados + +**Funcionalidades principales**: +- Almacenamiento seguro de credenciales +- Generador de contraseñas +- Sincronización con clientes (Web, Desktop, Mobile) +- Auditoría de accesos +- Backup automático + +**Tareas comunes**: +```bash +# Ver estado +docker ps | grep vaultwarden + +# Reiniciar +docker restart vaultwarden + +# Backup de bóveda +docker exec vaultwarden tar czf /data/backup.tar.gz /data/ +``` + +--- + +### Shlink (Puerto 8082) +**Acceso**: http://92.112.181.188:8082 + +**Propósito**: Generador y gestor de URLs cortas + +**Funcionalidades principales**: +- Acortamiento de URLs largas +- Estadísticas de clics y accesos +- Dominio personalizado +- QR automático +- API para integración + +**Tareas comunes**: +```bash +# Ver estadísticas +curl http://92.112.181.188:8082/rest/stats + +# Crear URL corta (vía API) +curl -X POST http://92.112.181.188:8082/api/v2/short-urls \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -d '{"longUrl":"https://example.com/long/url"}' +``` + +--- + +### ntfy (Puerto 8880) +**Acceso**: http://92.112.181.188:8880 + +**Propósito**: Sistema de notificaciones push y eventos + +**Funcionalidades principales**: +- Notificaciones en tiempo real +- Suscripción a tópicos +- Integración con webhooks +- Sin autenticación (privacidad opcional) +- Cliente CLI disponible + +**Tareas comunes**: +```bash +# Enviar notificación +curl -d "Hello from CORP" http://92.112.181.188:8880/alerts + +# Suscribirse a tópico +curl -s http://92.112.181.188:8880/alerts/subscribe + +# Ver estado +docker ps | grep ntfy +``` + +--- + +## 2. Microservicios TTZR + +Los siguientes microservicios forman parte del sistema multiagente TTZR: + +### Margaret (Puerto 5051) +**Propósito**: Agente de orquestación y coordinación + +**Funcionalidades**: +- Gestión de tareas distribuidas +- Coordina workflows entre servicios +- Mantiene estado del sistema + +**Acceso**: +```bash +curl http://92.112.181.188:5051/health +``` + +--- + +### Jared (Puerto 5052) +**Propósito**: Procesamiento de datos y análisis + +**Funcionalidades**: +- Transformación de datos +- Análisis en tiempo real +- Integración con pipeline de datos + +**Acceso**: +```bash +curl http://92.112.181.188:5052/health +``` + +--- + +### Mason (Puerto 5053) +**Propósito**: Generación y gestión de reportes + +**Funcionalidades**: +- Compilación de reportes +- Exportación múltiples formatos +- Programación de reportes + +**Acceso**: +```bash +curl http://92.112.181.188:5053/reports +``` + +--- + +### Feldman (Puerto 5054) +**Propósito**: Auditoría y logging centralizado + +**Funcionalidades**: +- Registro de eventos +- Trazabilidad completa +- Alertas de seguridad + +**Acceso**: +```bash +curl http://92.112.181.188:5054/logs +``` + +--- + +### HSU User Library (Puerto 5002) +**Propósito**: Biblioteca de funciones y utilidades compartidas + +**Funcionalidades**: +- Librerías reutilizables +- Utilidades comunes +- Versionado de dependencias + +**Acceso**: +```bash +curl http://92.112.181.188:5002/api/libraries +``` + +--- + +## 3. PostgreSQL + +### Información General +**Puerto**: 5432 +**Conexión**: `psql -h 92.112.181.188 -U postgres -d ` + +### Bases de Datos Principales + +#### ttzr +**Propósito**: Base de datos central del sistema + +**Contenido**: +- 32 tablas del módulo context-manager +- Esquemas: + - `00_base` - Estructura base + - `01_immutable_log` - Log inmutable + - `02_context_manager` - Gestor de contexto + - `03_algorithm_engine` - Motor de algoritmos + +**Acceso**: +```bash +psql -h 92.112.181.188 -U postgres -d ttzr +\dt # Listar tablas +\dn # Listar esquemas +SELECT * FROM information_schema.tables WHERE table_schema = 'context_manager'; +``` + +--- + +#### corp +**Propósito**: Datos específicos de operaciones corporativas + +**Contenido**: +- Configuraciones locales +- Estado de servicios +- Logs de operación + +--- + +#### nextcloud +**Propósito**: Almacenamiento de metadatos de Nextcloud + +**Contenido**: +- Metadatos de archivos +- Permisos y shares +- Actividad de usuarios + +--- + +#### shlink +**Propósito**: Almacenamiento de URLs cortas + +**Contenido**: +- URLs originales y acortadas +- Estadísticas de acceso +- Dominio y mappeo + +--- + +#### odoo +**Propósito**: ERP integrado + +**Contenido**: +- Datos de negocio +- CRM y ventas +- Contabilidad + +**Acceso Odoo**: http://92.112.181.188:8069 + +--- + +### Context-Manager Esquemas (32 Tablas) + +El módulo context-manager proporciona 32 tablas distribuidas en 4 esquemas: + +#### 00_base (Base Structures) +Tablas fundamentales de estructura y tipos de datos + +#### 01_immutable_log (Auditoría y Trazabilidad) +Log inmutable para auditoría completa del sistema +```sql +SELECT * FROM immutable_log.events LIMIT 10; +SELECT event_type, COUNT(*) FROM immutable_log.events GROUP BY event_type; +``` + +#### 02_context_manager (Gestor de Contexto) +Gestión del contexto de ejecución y estado +```sql +SELECT * FROM context_manager.contexts WHERE status = 'active'; +SELECT * FROM context_manager.sessions; +``` + +#### 03_algorithm_engine (Motor de Algoritmos) +Definición y ejecución de algoritmos +```sql +SELECT * FROM algorithm_engine.algorithms; +SELECT * FROM algorithm_engine.executions ORDER BY created_at DESC; +``` + +**Consulta completa de estructura**: +```bash +psql -h 92.112.181.188 -U postgres -d ttzr -c "\dt" +``` + +--- + +## 4. Administración y Troubleshooting + +### Monitoreo General + +#### Estado de Servicios Docker +```bash +ssh root@92.112.181.188 + +# Ver todos los contenedores +docker ps -a + +# Ver logs en tiempo real +docker logs -f + +# Ver recursos utilizados +docker stats +``` + +#### Verificar Disponibilidad de Puertos +```bash +# Desde el servidor +netstat -tuln | grep LISTEN + +# Desde cliente remoto +nc -zv 92.112.181.188 8080 +nc -zv 92.112.181.188 5432 +``` + +--- + +### Troubleshooting Común + +#### Servicio No Responde +```bash +# 1. Verificar status +docker ps | grep + +# 2. Ver logs +docker logs + +# 3. Reiniciar +docker restart + +# 4. Rebuild si persiste +docker-compose down +docker-compose up -d +``` + +#### PostgreSQL Connection Refused +```bash +# Verificar que está corriendo +docker ps | grep postgres + +# Reiniciar PostgreSQL +docker restart postgres + +# Verificar conexión +psql -h 92.112.181.188 -U postgres -c "SELECT version();" +``` + +#### Problemas de Almacenamiento +```bash +# Ver uso de disco +df -h + +# Limpiar contenedores stopped +docker container prune -f + +# Limpiar imágenes sin usar +docker image prune -f + +# Ver volúmenes +docker volume ls +``` + +--- + +### Backups y Recuperación + +#### Backup PostgreSQL +```bash +docker exec postgres pg_dump -U postgres ttzr > ttzr_backup.sql + +# O completo (todas las BD) +docker exec postgres pg_dumpall -U postgres > full_backup.sql +``` + +#### Restaurar PostgreSQL +```bash +docker exec -i postgres psql -U postgres ttzr < ttzr_backup.sql +``` + +#### Backup Nextcloud +```bash +docker exec nextcloud tar czf /data/backup.tar.gz /var/www/html +``` + +--- + +### Logs y Auditoría + +#### Ver Logs Centralizados +```bash +# Tabla de auditoría +psql -h 92.112.181.188 -U postgres -d ttzr -c \ + "SELECT * FROM immutable_log.events ORDER BY created_at DESC LIMIT 20;" + +# Por tipo de evento +psql -h 92.112.181.188 -U postgres -d ttzr -c \ + "SELECT event_type, COUNT(*) FROM immutable_log.events GROUP BY event_type;" +``` + +#### Logs de Feldman +```bash +curl http://92.112.181.188:5054/logs?limit=100 +``` + +--- + +### Comandos Útiles + +#### Conectarse a Base de Datos +```bash +# Interactive +psql -h 92.112.181.188 -U postgres -d ttzr + +# Desde línea de comandos +psql -h 92.112.181.188 -U postgres -d ttzr -c "SELECT COUNT(*) FROM information_schema.tables;" +``` + +#### Ejecutar SQL Script +```bash +psql -h 92.112.181.188 -U postgres -d ttzr -f script.sql +``` + +#### Health Check Completo +```bash +#!/bin/bash +echo "=== Docker Containers ===" +ssh root@92.112.181.188 docker ps + +echo "=== PostgreSQL ===" +psql -h 92.112.181.188 -U postgres -c "SELECT 'OK' as status;" + +echo "=== Services HTTP ===" +for port in 8080 8081 8082 8880 5051 5052 5053 5054 5002; do + curl -s http://92.112.181.188:$port/health || echo "Port $port: DOWN" +done +``` + +--- + +## Contacto y Soporte + +Para problemas o preguntas: +- **Sistema Central**: Gitea en 69.62.126.110 +- **Auditoría**: Revisar logs en Feldman (5054) +- **Documentación**: R2 `s3://architect/documentos adjuntos/` + +--- + +**Última actualización**: 2025-12-30 +**Versión**: 2.0 - Servicios y Administración + +--- + +# MANUAL DE USUARIO CORP - PARTE 3 +## Guías Rápidas y Procedimientos Frecuentes + +**Fecha:** 2025-12-30 +**Versión:** 1.0 +**Servidor:** corp (root@92.112.181.188) + +--- + +## 1. GUÍA RÁPIDA DE INICIO + +### 1.1 Primeros Pasos en CORP + +#### Acceso al Servidor +```bash +# Conectarse via SSH +ssh root@92.112.181.188 + +# Verificar servicios activos +docker ps + +# Ver estado general +docker ps -a +``` + +#### Verificación de Conectividad +```bash +# Ping a servicios locales +curl -I http://localhost:3000 # Directus +curl -I http://localhost:8000 # Odoo +curl -I http://localhost:8080 # Nextcloud +curl -I http://localhost:3001 # Shlink + +# Ver logs de Docker Compose +docker-compose logs +``` + +### 1.2 Acceder a Odoo + +#### URL y Credenciales +- **URL:** `http://92.112.181.188:8000` +- **Usuario:** admin +- **Contraseña:** [Ver en .env] + +#### Primeros Pasos +1. Login con credenciales +2. Ir a Dashboard +3. Módulos disponibles: + - Ventas (Sales) + - Facturación (Invoicing) + - Inventario (Inventory) + - Contabilidad (Accounting) + - RR.HH. (HR) + +#### Navegación Básica +``` +Menú Principal > Módulo Deseado > Operación +``` + +Ejemplo: +``` +Sales > Orders > Create Order +``` + +### 1.3 Acceder a Directus + +#### URL y Credenciales +- **URL:** `http://92.112.181.188:3000` +- **Usuario:** admin@directus.io +- **Contraseña:** [Ver en .env] + +#### Interfaz Principal +1. **Collections** - Tablas de datos +2. **Items** - Registros individuales +3. **Settings** - Configuración +4. **Users** - Gestión de usuarios + +#### Primeros Pasos +1. Login +2. Explora Collections disponibles +3. Crea tu primer Item +4. Configurar permisos de acceso + +--- + +## 2. CASOS DE USO COMUNES + +### 2.1 Crear una Factura en Odoo + +#### Paso a Paso + +**1. Acceder a Facturación** +``` +Menu Principal > Accounting > Invoices > Create +``` + +**2. Completar Datos Básicos** +- Partner (Cliente) +- Invoice Type: Invoice +- Invoice Date +- Due Date + +**3. Agregar Líneas de Factura** +- Click en "Add a line" +- Seleccionar Producto +- Cantidad +- Precio unitario +- Impuesto (si aplica) + +**4. Revisar Totales** +- Subtotal +- Impuestos +- Total + +**5. Confirmar** +- Click en "Confirm" +- Estado cambia a "Posted" + +**6. Enviar al Cliente** +- Click en "Send & Print" +- Seleccionar método (Email/Print) + +#### Consejos +- Guardar borradores regularmente (Ctrl+S) +- Revisar datos del cliente antes de confirmar +- Mantener histórico de facturas + +--- + +### 2.2 Gestionar Contenido en Directus + +#### Crear una Nueva Colección + +**1. Ir a Settings** +``` +Settings > Data Model > New Collection +``` + +**2. Definir Estructura** +- Name: Nombre de la colección +- Primary Key: campo único +- Agregar Fields + - Nombre del campo + - Tipo de dato (String, Integer, etc.) + - Opciones adicionales + +**3. Crear Items** +``` +Collections > Mi Colección > Create +``` + +**4. Completar Datos** +- Rellenar campos +- Guardar ("Save") + +#### Tipos de Campos Comunes +| Tipo | Uso | +|------|-----| +| String | Texto corto | +| Text | Texto largo | +| Integer | Números enteros | +| Decimal | Números decimales | +| Date | Fechas | +| Boolean | Verdadero/Falso | +| JSON | Datos complejos | +| Relationship | Relaciones entre tablas | + +#### Gestionar Permisos +``` +Settings > Access Control > Roles > Editar Rol +``` + +Seleccionar permisos para: +- Create (crear) +- Read (leer) +- Update (actualizar) +- Delete (eliminar) + +--- + +### 2.3 Compartir Archivos en Nextcloud + +#### URL y Acceso +- **URL:** `http://92.112.181.188:8080` +- **Usuario:** [Ver en .env] +- **Contraseña:** [Ver en .env] + +#### Subir Archivo + +**1. Dashboard** +``` +Nextcloud > Files +``` + +**2. Subir** +- Arrastrar archivo o Click en "+" +- Seleccionar archivo +- Esperar carga + +**3. Compartir** +- Click derecho > Share +- Opciones: + - Por enlace + - Con usuario específico + - Configurar permisos (read/edit) + +#### Crear Carpeta Compartida + +**1. Nueva Carpeta** +``` +Click en "+" > Create Folder +``` + +**2. Nombrar Carpeta** +``` +"Nombre Proyecto" +``` + +**3. Compartir** +- Seleccionar carpeta +- Click "Share" +- Agregar usuarios +- Permisos: Read/Edit/Share + +#### Tips +- Organizar por proyectos +- Usar nombres descriptivos +- Revisar permisos regularmente +- Limpiar archivos antiguos + +--- + +### 2.4 Crear URL Corta con Shlink + +#### URL del Servicio +- **URL:** `http://92.112.181.188:3001` +- **API:** `http://92.112.181.188:3001/api/v3` + +#### Crear URL Corta (Web) + +**1. Acceder a Shlink** +``` +http://92.112.181.188:3001 +``` + +**2. New Short URL** +- Long URL: URL original +- Custom short code: (opcional) +- Domain: seleccionar dominio +- Options: + - Make it private + - Set expiration date + - Limit visits + +**3. Crear** +``` +Click "Create" +``` + +**4. Usar URL Corta** +``` +http://92.112.181.188:3001/{short-code} +``` + +#### Crear URL Corta (CLI) + +```bash +# Obtener API Key +# Está en Shlink Admin Panel + +curl -X POST http://92.112.181.188:3001/api/v3/short-urls \ + -H "Content-Type: application/json" \ + -H "X-API-Key: YOUR_API_KEY" \ + -d '{ + "longUrl": "https://ejemplo.com/ruta/muy/larga", + "customSlug": "mi-url-corta", + "maxVisits": 100, + "validSince": "2025-01-01T00:00:00Z" + }' +``` + +#### Ver Estadísticas +``` +Dashboard > Short URLs > Seleccionar URL > Ver Stats +``` + +Información disponible: +- Visitas totales +- Gráfico temporal +- Referrers +- Devices/OS +- Países + +--- + +## 3. COMANDOS FRECUENTES + +### 3.1 Comandos Docker + +#### Ver Servicios en Ejecución +```bash +# Listar contenedores activos +docker ps + +# Listar todos (incluyendo parados) +docker ps -a + +# Ver tamaño de contenedores +docker ps --size +``` + +#### Ver Logs + +```bash +# Logs del último servicio (últimas 100 líneas) +docker logs -f --tail=100 odoo + +# Logs de Directus +docker logs -f directus + +# Logs de Nextcloud +docker logs -f nextcloud + +# Logs en tiempo real (Ctrl+C para salir) +docker logs -f nombre-contenedor +``` + +#### Reiniciar Servicios + +```bash +# Reiniciar servicio específico +docker-compose restart odoo +docker-compose restart directus +docker-compose restart nextcloud + +# Reiniciar todos los servicios +docker-compose restart + +# Detener servicio +docker-compose stop nombre-servicio + +# Iniciar servicio +docker-compose start nombre-servicio + +# Recrear contenedor (con nuevas imágenes) +docker-compose up -d --force-recreate nombre-servicio +``` + +#### Estadísticas de Uso +```bash +# Ver CPU, memoria, red +docker stats + +# Salida formateada +docker stats --no-stream +``` + +#### Inspeccionar Contenedor +```bash +# Ver detalles del contenedor +docker inspect nombre-contenedor + +# Ver variables de entorno +docker inspect -f '{{json .Config.Env}}' nombre-contenedor | jq +``` + +### 3.2 Comandos PostgreSQL + +#### Conectarse a PostgreSQL +```bash +# Acceso directo +docker exec -it postgres psql -U postgres + +# Con base de datos específica +docker exec -it postgres psql -U postgres -d odoo_db +``` + +#### Queries Útiles + +**Información General** +```sql +-- Ver bases de datos +\l + +-- Ver tablas +\dt + +-- Conectarse a BD específica +\c nombre_bd + +-- Ver estructura de tabla +\d nombre_tabla +``` + +**Usuarios y Conexiones** +```sql +-- Ver usuarios +SELECT * FROM pg_user; + +-- Ver conexiones activas +SELECT datname, usename, application_name, state +FROM pg_stat_activity +WHERE state IS NOT NULL; + +-- Matar conexión específica +SELECT pg_terminate_backend(pid) +FROM pg_stat_activity +WHERE datname = 'nombre_bd' AND pid <> pg_backend_pid(); +``` + +**Odoo - Queries Comunes** +```sql +-- Ver empresas +SELECT id, name FROM res_company; + +-- Ver usuarios +SELECT id, login, name FROM res_users LIMIT 10; + +-- Ver facturas +SELECT id, name, state, amount_total +FROM account_move +WHERE move_type = 'out_invoice' +ORDER BY date DESC LIMIT 10; + +-- Contar facturas por estado +SELECT state, COUNT(*) as total +FROM account_move +GROUP BY state; + +-- Facturas sin pagar +SELECT id, name, amount_total, invoice_date +FROM account_move +WHERE move_type = 'out_invoice' +AND payment_state = 'not_paid' +ORDER BY invoice_date DESC; +``` + +**Directus - Queries** +```sql +-- Ver colecciones +SELECT * FROM directus_collections; + +-- Ver campos +SELECT collection, field, type FROM directus_fields; + +-- Ver usuarios Directus +SELECT id, email, first_name, last_name FROM directus_users; + +-- Ver roles +SELECT id, name FROM directus_roles; +``` + +**Performance** +```sql +-- Tablas más grandes +SELECT schemaname, tablename, + pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS size +FROM pg_tables +WHERE schemaname NOT IN ('pg_catalog', 'information_schema') +ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC; + +-- Índices no usados +SELECT schemaname, tablename, indexname +FROM pg_stat_user_indexes +WHERE idx_scan = 0 +ORDER BY pg_size_pretty(pg_relation_size(indexrelid)) DESC; +``` + +#### Backup y Restore +```bash +# Backup de base de datos +docker exec postgres pg_dump -U postgres nombre_bd > backup.sql + +# Backup comprimido +docker exec postgres pg_dump -U postgres nombre_bd | gzip > backup.sql.gz + +# Restaurar +docker exec -i postgres psql -U postgres nombre_bd < backup.sql + +# Restaurar desde comprimido +zcat backup.sql.gz | docker exec -i postgres psql -U postgres nombre_bd +``` + +### 3.3 Tips de Productividad + +#### Atajos de Teclado Útiles + +**Navegación General** +| Atajo | Acción | +|-------|--------| +| Ctrl+K | Búsqueda global (Odoo) | +| Ctrl+H | Historial | +| Ctrl+S | Guardar | +| Ctrl+Shift+N | Nueva pestaña | +| Alt+← | Atrás | +| Alt+→ | Adelante | + +**En Odoo** +| Atajo | Acción | +|-------|--------| +| Ctrl+L | Saltar a búsqueda de registros | +| Ctrl+Shift+J | Abrir consola de desarrollador | +| Tab | Siguiente campo | +| Shift+Tab | Campo anterior | + +**En Directus** +| Atajo | Acción | +|-------|--------| +| Ctrl+S | Guardar | +| Ctrl+D | Duplicar | +| Ctrl+L | Saltar a búsqueda | + +#### Macros y Automatización + +**Crear filtro rápido en Odoo** +``` +Haz clic en el icono de embudo (Filter) +Agrega condiciones +Guarda como filtro personalizado +``` + +**Búsqueda avanzada** +``` +[campo] = valor +[campo] >= valor +[campo] like '%texto%' +[campo] in (valor1, valor2) +``` + +#### Troubleshooting Rápido + +**Servicio no responde** +```bash +# 1. Ver logs +docker logs nombre-servicio + +# 2. Reiniciar +docker-compose restart nombre-servicio + +# 3. Ver estado +docker ps | grep nombre-servicio + +# 4. Si falla, recrear +docker-compose up -d --force-recreate nombre-servicio +``` + +**Olvidé credenciales** +```bash +# Ver variables de entorno +docker exec nombre-contenedor env | grep -i pass + +# O revisar el .env +cat .env | grep -i -E "(user|pass|secret)" +``` + +**Base de datos lenta** +```bash +# Ver conexiones activas +docker exec -it postgres psql -U postgres -c \ + "SELECT datname, count(*) FROM pg_stat_activity GROUP BY datname;" + +# Optimizar tabla +docker exec -it postgres psql -U postgres -c "VACUUM ANALYZE nombre_tabla;" +``` + +**Problema de espacio disco** +```bash +# Ver uso de disco +df -h + +# Ver tamaño de volúmenes Docker +docker system df + +# Limpiar datos no usados +docker system prune -a --volumes +``` + +--- + +## 4. GUÍA DE SOPORTE + +### Reportar Problemas +1. Recopilar información: + - Logs relevantes + - Pasos para reproducir + - Capturas de pantalla + +2. Contactar: + - **Admin del Sistema:** Revisar en documentación + - **Reportar en:** Gitea Issues + +### Contacto de Emergencia +- Sistema centralizado: TZZR (69.62.126.110) +- Acceso SSH disponible para administradores + +--- + +**Fin del Manual - PARTE 3** + +*Para actualizaciones y mejoras, contactar al equipo de administración del sistema.* diff --git a/MANUAL_USUARIO_DECK.md b/MANUAL_USUARIO_DECK.md new file mode 100644 index 0000000..3f06f6b --- /dev/null +++ b/MANUAL_USUARIO_DECK.md @@ -0,0 +1,1439 @@ +# MANUAL DE USUARIO - DECK +## Sistema TZZR - Skynet v8 +**Servidor:** 72.62.1.113 +**Fecha:** 2025-12-30 + +--- + +# Manual de Usuario - DECK (72.62.1.113) +## PARTE 1: Introducción y Servicios + +--- + +## 1. Introducción a DECK + +### ¿Qué es DECK? + +DECK es uno de los cuatro servidores principales del sistema TZZR (The Zero-Trust Resilient Resource Network), ubicado en la dirección IP **72.62.1.113**. + +DECK actúa como **servidor de servicios** y aloja: +- **Agentes especializados** (Clara, Alfred, Mason, Feldman) que procesan datos e interactúan con otros sistemas +- **Servicios empresariales** (Correo, almacenamiento en la nube, contraseñas, etc.) +- **Infraestructura de datos** (PostgreSQL con pgvector, Redis) +- **Aplicaciones integradas** (ERP, CMS, notificaciones, gestor de archivos) + +### Rol en la Infraestructura TZZR + +El sistema TZZR consta de 4 servidores distribuidos: + +| Servidor | IP | Función Principal | +|----------|----|--------------------| +| **Central** | 69.62.126.110 | Coordinación (Gitea, PostgreSQL central) | +| **DECK** | 72.62.1.113 | Servicios, Agentes, Mail (Este servidor) | +| **CORP** | 92.112.181.188 | Agentes especializados (Margaret, Jared) | +| **HST** | 72.62.2.84 | Directus, gestión de imágenes | + +### Acceso SSH a DECK + +Para conectarse a DECK desde la máquina central o cualquier servidor autorizado: + +```bash +ssh -i ~/.ssh/tzzr root@72.62.1.113 +``` + +**Requisitos:** +- Tener la clave privada SSH en `~/.ssh/tzzr` +- Permisos de acceso configurados +- Conectividad de red al servidor + +**Verificar conexión:** +```bash +ssh -i ~/.ssh/tzzr root@72.62.1.113 "echo 'Conexión exitosa'" +``` + +--- + +## 2. Servicios en DECK + +DECK aloja tres categorías principales de servicios: + +### 2.1 Microservicios TZZR (Puertos 505x) + +Estos son servicios especializados del ecosistema TZZR que se comunican entre sí: + +#### Clara (Puerto 5051) +- **Descripción:** Log inmutable y auditoría +- **Propósito:** Registra todas las transacciones y eventos del sistema de forma imposible de modificar +- **Uso:** Auditoría, trazabilidad, compliance +- **Estado:** Verificar con `service clara` + +#### Alfred (Puerto 5052) +- **Descripción:** Automatización de flujos de trabajo +- **Propósito:** Ejecuta flujos de trabajo definidos, orquesta tareas entre servicios +- **Uso:** Automatización de procesos empresariales +- **Estado:** Verificar con `service alfred` + +#### Mason (Puerto 5053) +- **Descripción:** Espacio de enriquecimiento de datos +- **Propósito:** Enriquece datos con información contextual, aplica transformaciones +- **Uso:** Procesamiento y normalización de datos +- **Estado:** Verificar con `service mason` + +#### Feldman (Puerto 5054) +- **Descripción:** Validador Merkle +- **Propósito:** Verifica integridad de datos mediante árboles de Merkle +- **Uso:** Validación criptográfica, verificación de integridad +- **Estado:** Verificar con `service feldman` + +### 2.2 Aplicaciones Empresariales + +Servicios de aplicación usuario-final para uso cotidiano: + +#### Nextcloud (Puerto 8084) +- **Descripción:** Almacenamiento en la nube y colaboración +- **URL:** https://cloud.tzzrdeck.me +- **Uso:** Compartir archivos, calendario, contactos +- **Capacidades:** Sincronización, compartir enlaces, versiones + +#### Odoo (Puerto 8069) +- **Descripción:** Sistema ERP completo +- **URL:** https://odoo.tzzrdeck.me +- **Uso:** Facturación, inventario, CRM, recursos humanos +- **Usuarios:** Acceso basado en roles + +#### Vaultwarden (Puerto 8085) +- **Descripción:** Gestor de contraseñas empresarial +- **URL:** https://vault.ttzrdeck.me +- **Uso:** Almacenar y gestionar contraseñas de forma segura +- **Integración:** Compatible con Bitwarden + +#### Directus (Puerto 8055) +- **Descripción:** CMS y gestor de contenido headless +- **URL:** https://directus.tzzrdeck.me +- **Uso:** Crear y gestionar contenido, APIs automáticas +- **Flexible:** Base de datos agnóstica + +#### Shlink (Puerto 8083) +- **Descripción:** Acortador de URLs +- **URL:** https://shlink.tzzrdeck.me +- **Uso:** Crear URLs cortas, rastreo de clics +- **Analytics:** Estadísticas de uso + +#### Ntfy (Puerto 8080) +- **Descripción:** Sistema de notificaciones +- **URL:** https://ntfy.tzzrdeck.me +- **Uso:** Enviar notificaciones a través de HTTP +- **Integración:** Webhooks y push notifications + +#### FileBrowser (Puerto 8082) +- **Descripción:** Gestor de archivos web +- **URL:** https://files.tzzrdeck.me +- **Uso:** Explorar, descargar, subir archivos +- **Seguridad:** Control de permisos por usuario + +### 2.3 Infraestructura de Datos + +#### PostgreSQL (Puerto 5432) +- **Descripción:** Base de datos principal del sistema +- **Características:** pgvector activado (búsqueda vectorial para IA) +- **Datos:** Contiene todas las bases de datos del sistema TZZR +- **Backup:** Se realiza automatizado + +#### Redis (Puerto 6379) +- **Descripción:** Cache en memoria de alta velocidad +- **Uso:** Cache de sesiones, cache de consultas, pub/sub +- **Rendimiento:** Milisegundos de latencia + +### 2.4 Servicios de Correo + +#### Mailcow (Puerto 8180) +- **Descripción:** Servidor de correo empresarial completo +- **URL:** https://mail.tzzr.net +- **Servicios incluidos:** + - SMTP (envío de correos) + - IMAP/POP3 (lectura de correos) + - Webmail integrado + - Filtrado de spam + - Certificados SSL automáticos +- **Componentes:** + - Postfix: SMTP + - Dovecot: IMAP/POP3 + - Nginx: Reverse proxy y webmail + - MySQL: Base de datos + - Redis: Cache + +**Contenedores Mailcow:** +``` +postfix-mailcow - Servidor SMTP +dovecot-mailcow - Servidor IMAP/POP3 +nginx-mailcow - Webmail y reverse proxy +mysql-mailcow - Base de datos +redis-mailcow - Cache +``` + +--- + +## 3. Context-Manager (Gestor de Contexto) + +### ¿Qué es Context-Manager? + +Context-Manager es una herramienta central que permite a los agentes TZZR: +- Mantener contexto persistente de conversaciones +- Acceder a bloques de contexto previamente creados +- Gestionar memoria de largo plazo +- Compartir información entre agentes + +### Instalación y Configuración + +Context-Manager está disponible como CLI en DECK. Para verificar su disponibilidad: + +```bash +ssh -i ~/.ssh/tzzr root@72.62.1.113 "context-manager --help" +``` + +### Comandos Principales + +#### `context-manager --help` +Muestra ayuda sobre todos los comandos disponibles. + +```bash +context-manager --help +``` + +**Ejemplo de salida:** +``` +Context Manager CLI +================== + +Comandos: + block list - Listar bloques de contexto + block add - Crear nuevo bloque + block view - Ver contenido de bloque + block remove - Eliminar bloque + + memory list - Listar memorias + memory add - Agregar a memoria + memory clear - Limpiar memoria + + chat - Iniciar chat interactivo +``` + +#### `context-manager block list` +Lista todos los bloques de contexto almacenados. + +```bash +context-manager block list +``` + +**Ejemplo:** +``` +ID | Nombre | Tipo | Fecha Creación +------|---------------------|----------|------------------ +001 | Historia Clara | metadata | 2025-12-15 10:30 +002 | Configuración TZZR | config | 2025-12-20 14:45 +003 | Directorio RFC | reference| 2025-12-28 09:15 +``` + +**Campos:** +- `ID`: Identificador único del bloque +- `Nombre`: Descripción del contenido +- `Tipo`: Categoría (metadata, config, reference, etc.) +- `Fecha Creación`: Cuándo se creó el bloque + +#### `context-manager block view ` +Ver el contenido completo de un bloque específico. + +```bash +context-manager block view 002 +``` + +**Ejemplo:** +``` +Bloque: 002 +Nombre: Configuración TZZR +Tipo: config +Creado: 2025-12-20 14:45 + +Contenido: +--------- +{ + "central_ip": "69.62.126.110", + "servers": { + "deck": "72.62.1.113", + "corp": "92.112.181.188", + "hst": "72.62.2.84" + }, + "database": { + "host": "localhost", + "port": 5432, + "name": "tzzr_main" + } +} +``` + +#### `context-manager memory list` +Lista todos los elementos guardados en memoria compartida. + +```bash +context-manager memory list +``` + +**Ejemplo:** +``` +Memoria Compartida (15 items) +============================= + +1. Clara - Último estado: up +2. Alfred - Procesos pendientes: 3 +3. Mason - Últimas transformaciones: 2025-12-29 16:42 +4. Feldman - Validaciones en caché: 127 +5. PostgreSQL - Conexiones activas: 8 +``` + +#### `context-manager memory add` +Agregar nueva información a memoria compartida. + +```bash +context-manager memory add "nombre_clave" "contenido o JSON" +``` + +**Ejemplo:** +```bash +context-manager memory add "configuracion_temporal" '{"modo": "mantenimiento", "fecha": "2025-12-30"}' +``` + +#### `context-manager chat` +Inicia una sesión de chat interactivo con Context-Manager (útil para debugging). + +```bash +context-manager chat +``` + +### Ejemplos de Uso Práctico + +#### Ejemplo 1: Verificar estado del sistema +```bash +# Ver si hay configuración de mantenimiento +context-manager block view configuracion_mantenimiento + +# Revisar estado en memoria +context-manager memory list +``` + +#### Ejemplo 2: Crear un bloque de contexto para una tarea +```bash +# Los agentes pueden crear bloques para compartir información +context-manager block add "migracion_datos_2025" \ + --tipo "project" \ + --contenido '{"estado": "en_progreso", "agentes": ["clara", "mason"]}' +``` + +#### Ejemplo 3: Consultar desde un script +```bash +#!/bin/bash +# Script que usa context-manager + +CONTEXTO=$(context-manager block view configuracion) +echo "Contexto actual: $CONTEXTO" + +# Actualizar estado +context-manager memory add "script_estado" "completado" +``` + +--- + +## 4. Gestión de Servicios en DECK + +### Comandos Generales de Estado + +#### Ver estado del sistema +```bash +ssh -i ~/.ssh/tzzr root@72.62.1.113 "docker ps -a" +``` + +Muestra todos los contenedores (activos e inactivos). + +#### Ver estadísticas del sistema +```bash +ssh -i ~/.ssh/tzzr root@72.62.1.113 "free -h" # Memoria +ssh -i ~/.ssh/tzzr root@72.62.1.113 "df -h /" # Disco +ssh -i ~/.ssh/tzzr root@72.62.1.113 "top -bn1" # Procesos +``` + +### Comandos para Servicios Específicos + +#### Obtener estado de un servicio +```bash +ssh -i ~/.ssh/tzzr root@72.62.1.113 "docker ps --filter name=clara" +``` + +#### Ver logs de un servicio +```bash +ssh -i ~/.ssh/tzzr root@72.62.1.113 "docker logs clara-service --tail 50" +``` + +#### Reiniciar un servicio +```bash +ssh -i ~/.ssh/tzzr root@72.62.1.113 "docker restart clara-service" +``` + +#### Detener un servicio +```bash +ssh -i ~/.ssh/tzzr root@72.62.1.113 "docker stop nextcloud" +``` + +#### Iniciar un servicio +```bash +ssh -i ~/.ssh/tzzr root@72.62.1.113 "docker start nextcloud" +``` + +--- + +## 5. Acceso a Servicios Web + +### URLs de Acceso + +Todos los servicios web están disponibles bajo el dominio `tzzrdeck.me`: + +| Servicio | URL | Puerto | Usuario Típico | +|----------|-----|--------|-----------------| +| Nextcloud | https://cloud.tzzrdeck.me | 8084 | Tu usuario LDAP | +| Odoo | https://odoo.tzzrdeck.me | 8069 | Tu usuario Odoo | +| Vaultwarden | https://vault.tzzrdeck.me | 8085 | Tu usuario Bitwarden | +| Directus | https://directus.tzzrdeck.me | 8055 | Tu usuario Directus | +| Shlink | https://shlink.tzzrdeck.me | 8083 | Tu usuario Shlink | +| Ntfy | https://ntfy.tzzrdeck.me | 8080 | Sin autenticación* | +| FileBrowser | https://files.tzzrdeck.me | 8082 | Tu usuario local | +| Webmail (Mailcow) | https://mail.tzzr.net | 8180 | Tu email | + +*Ntfy puede usarse sin autenticación o con ella según configuración. + +### Verificar Conectividad + +Para verificar que un servicio está accesible: + +```bash +curl -I https://cloud.tzzrdeck.me +curl -I https://mail.tzzr.net +``` + +Deberías recibir respuesta HTTP 200 o 302 (redirección a login). + +--- + +## 6. Tabla de Referencia Rápida + +### Puertos Principales en DECK + +``` +5051 - Clara (Log inmutable) +5052 - Alfred (Automatización) +5053 - Mason (Enriquecimiento) +5054 - Feldman (Validador Merkle) + +5432 - PostgreSQL +6379 - Redis + +8055 - Directus +8069 - Odoo +8080 - Ntfy +8082 - FileBrowser +8083 - Shlink +8084 - Nextcloud +8085 - Vaultwarden +8180 - Mailcow + +22 - SSH +``` + +### Comandos Rápidos + +```bash +# Conectar a DECK +ssh -i ~/.ssh/tzzr root@72.62.1.113 + +# Ver todos los servicios +docker ps -a + +# Ver memoria y disco +free -h && df -h / + +# Ver logs de Clara +docker logs clara-service -f + +# Reiniciar Nextcloud +docker restart nextcloud +``` + +--- + +## 7. Próximas Partes del Manual + +Este es el **PARTE 1** del manual. Las siguientes partes cubrirán: + +- **PARTE 2:** Guía de Usuarios - Acceso a aplicaciones web +- **PARTE 3:** Gestión de Correo - Administración de Mailcow +- **PARTE 4:** Backup y Recuperación +- **PARTE 5:** Troubleshooting y Resolución de Problemas +- **PARTE 6:** Integración y APIs de Servicios TZZR + +--- + +## 8. Soporte y Contacto + +Para problemas o consultas: + +1. **Verificar logs:** `docker logs ` +2. **Revisar documentación:** Contactar al equipo de ARCHITECT +3. **Escalation:** Reportar al coordinador central (CAPTAIN CLAUDE) + +--- + +**Última actualización:** 2025-12-30 +**Versión:** 1.0 +**Aplicable a:** DECK (72.62.1.113) +# Manual de Usuario DECK (72.62.1.113) - PARTE 2 +## PostgreSQL y Administración + +**Versión:** 1.0 +**Fecha:** 2025-12-30 +**Sistema:** TZZR - Infraestructura Centralizada + +--- + +## 1. PostgreSQL + +### 1.1 Conexión a PostgreSQL + +#### Conexión como usuario postgres +```bash +sudo -u postgres psql -d tzzr +``` + +#### Parámetros comunes +- **Host:** localhost (por defecto) +- **Puerto:** 5432 (por defecto) +- **Usuario:** postgres +- **Base de datos:** tzzr + +#### Comandos básicos en psql +```bash +\l # Listar bases de datos +\c [nombre_db] # Conectar a una base de datos +\dt # Listar tablas +\d [nombre_tabla] # Describir estructura de tabla +\du # Listar usuarios/roles +\q # Salir +\h # Ayuda de comandos SQL +``` + +### 1.2 Bases de Datos + +#### Base de datos: `tzzr` +Base de datos principal del sistema TZZR. + +#### Base de datos: `deck` +Base de datos específica del servidor DECK. + +#### Ver todas las bases de datos +```bash +sudo -u postgres psql -c "\l" +``` + +### 1.3 Tablas Principales del Context-Manager + +El context-manager gestiona las siguientes tablas en la base de datos `tzzr`: + +#### Tabla: `immutable_log` +Registro inmutable de todas las operaciones del sistema. + +```bash +# Ver estructura +sudo -u postgres psql -d tzzr -c "\d immutable_log" + +# Ver últimas 10 entradas +sudo -u postgres psql -d tzzr -c "SELECT * FROM immutable_log ORDER BY timestamp DESC LIMIT 10;" +``` + +#### Tabla: `context_state` +Estado actual del contexto del sistema. + +```bash +# Ver estado actual +sudo -u postgres psql -d tzzr -c "SELECT * FROM context_state;" +``` + +#### Tabla: `algorithm_engine` +Configuración y estado del motor de algoritmos. + +```bash +# Ver configuración +sudo -u postgres psql -d tzzr -c "SELECT * FROM algorithm_engine;" +``` + +#### Tabla: `agents` +Registro de agentes activos en el sistema. + +```bash +# Ver agentes activos +sudo -u postgres psql -d tzzr -c "SELECT * FROM agents WHERE active = true;" +``` + +#### Tabla: `audit_log` +Registro de auditoría de todas las operaciones administrativas. + +```bash +# Ver auditoría reciente +sudo -u postgres psql -d tzzr -c "SELECT * FROM audit_log ORDER BY timestamp DESC LIMIT 20;" +``` + +### 1.4 Consultas Útiles + +#### Verificar integridad de la base de datos +```bash +sudo -u postgres psql -d tzzr -c " + SELECT schemaname, tablename, pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) AS size + FROM pg_tables + WHERE schemaname NOT IN ('pg_catalog', 'information_schema') + ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;" +``` + +#### Verificar conexiones activas +```bash +sudo -u postgres psql -d tzzr -c " + SELECT pid, usename, application_name, client_addr, state + FROM pg_stat_activity + WHERE pid <> pg_backend_pid();" +``` + +#### Verificar índices +```bash +sudo -u postgres psql -d tzzr -c " + SELECT schemaname, tablename, indexname + FROM pg_indexes + WHERE schemaname NOT IN ('pg_catalog', 'information_schema');" +``` + +--- + +## 2. Administración + +### 2.1 Comandos Docker Útiles + +#### Ver estado de contenedores +```bash +docker ps # Contenedores activos +docker ps -a # Todos los contenedores +docker status # Estado general de Docker +``` + +#### Gestionar contenedores +```bash +docker start [container_id] # Iniciar contenedor +docker stop [container_id] # Detener contenedor +docker restart [container_id] # Reiniciar contenedor +docker logs [container_id] # Ver logs +docker logs -f [container_id] # Logs en tiempo real +docker exec -it [container_id] bash # Acceso interactivo +``` + +#### Gestionar imágenes +```bash +docker images # Listar imágenes +docker pull [image] # Descargar imagen +docker rmi [image_id] # Eliminar imagen +docker image prune # Limpiar imágenes no usadas +``` + +#### Ver recursos +```bash +docker stats # Uso de CPU/memoria en tiempo real +docker system df # Uso de disco +``` + +### 2.2 Logs y Diagnóstico + +#### Logs de PostgreSQL +```bash +# Si PostgreSQL está en Docker +docker logs [postgres_container_id] | tail -100 + +# Si PostgreSQL está en el host +sudo tail -100 /var/log/postgresql/postgresql.log +``` + +#### Logs de Gitea +```bash +docker logs [gitea_container_id] | tail -100 +``` + +#### Logs del sistema +```bash +sudo journalctl -xe # Últimos errores del sistema +sudo journalctl -u docker # Logs específicos de Docker +dmesg | tail -50 # Logs del kernel +``` + +#### Diagnóstico de red +```bash +netstat -tlnp # Puertos escuchando +ss -tlnp # Alternativa moderna de netstat +ping 69.62.126.110 # Conectividad con servidor central +``` + +#### Verificar espacio en disco +```bash +df -h # Espacio en particiones +du -sh /* # Uso por directorio +du -sh /var/lib/docker/* # Uso de Docker +``` + +### 2.3 Backups + +#### Backup manual de PostgreSQL +```bash +# Backup completo de la base de datos tzzr +sudo -u postgres pg_dump tzzr > /tmp/tzzr_backup_$(date +%Y%m%d_%H%M%S).sql + +# Backup de una tabla específica +sudo -u postgres pg_dump tzzr -t immutable_log > /tmp/immutable_log_backup.sql +``` + +#### Restaurar desde backup +```bash +# Restaurar base de datos completa +sudo -u postgres psql tzzr < /tmp/tzzr_backup.sql + +# Restaurar tabla específica (cuidado: borra la tabla actual) +sudo -u postgres psql tzzr < /tmp/immutable_log_backup.sql +``` + +#### Backup de Gitea +```bash +# Ver documentación de Gitea para backup +docker exec [gitea_container] /app/gitea dump -c /etc/gitea/app.ini +``` + +#### Automático: Script de backup diario +```bash +#!/bin/bash +# Guardar como /opt/scripts/backup_daily.sh + +BACKUP_DIR="/backups/postgresql" +DB_NAME="tzzr" +DATE=$(date +%Y%m%d_%H%M%S) + +mkdir -p $BACKUP_DIR + +sudo -u postgres pg_dump $DB_NAME > $BACKUP_DIR/tzzr_$DATE.sql +gzip $BACKUP_DIR/tzzr_$DATE.sql + +# Eliminar backups más antiguos de 30 días +find $BACKUP_DIR -name "tzzr_*.sql.gz" -mtime +30 -delete + +echo "Backup completado: $BACKUP_DIR/tzzr_$DATE.sql.gz" +``` + +Configurar en cron: +```bash +# Editar crontab +sudo crontab -e + +# Agregar línea (backup diario a las 2:00 AM) +0 2 * * * /opt/scripts/backup_daily.sh >> /var/log/backup.log 2>&1 +``` + +--- + +## 3. Troubleshooting + +### 3.1 Problemas Comunes y Soluciones + +#### Problema: No se puede conectar a PostgreSQL +```bash +# Verificar que PostgreSQL está corriendo +sudo systemctl status postgresql +# o si está en Docker: +docker ps | grep postgres + +# Verificar puerto 5432 +sudo netstat -tlnp | grep 5432 + +# Ver logs de PostgreSQL +sudo tail -50 /var/log/postgresql/postgresql.log + +# Reiniciar PostgreSQL +sudo systemctl restart postgresql +# o si está en Docker: +docker restart [postgres_container_id] +``` + +#### Problema: Espacio en disco bajo +```bash +# Ver distribución de espacio +du -sh /* | sort -rh + +# Limpiar logs antiguos +sudo journalctl --vacuum=30d + +# Limpiar Docker +docker system prune -a --volumes + +# Limpiar cache de PostgreSQL +sudo -u postgres psql -d tzzr -c "VACUUM ANALYZE;" +``` + +#### Problema: Conexiones agotadas a PostgreSQL +```bash +# Ver conexiones activas +sudo -u postgres psql -d tzzr -c "SELECT * FROM pg_stat_activity;" + +# Terminar conexión específica +sudo -u postgres psql -d tzzr -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE pid <> pg_backend_pid();" + +# Ver configuración de conexiones máximas +sudo -u postgres psql -d tzzr -c "SHOW max_connections;" +``` + +#### Problema: Base de datos bloqueada +```bash +# Ver transacciones abiertas +sudo -u postgres psql -d tzzr -c "SELECT * FROM pg_stat_activity WHERE state != 'idle';" + +# Ver locks +sudo -u postgres psql -d tzzr -c "SELECT * FROM pg_locks;" + +# Terminar transacción bloqueada +sudo -u postgres psql -d tzzr -c "SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE pid = [PID];" +``` + +#### Problema: Docker fuera de espacio +```bash +# Ver uso de Docker +docker system df + +# Limpiar imágenes sin usar +docker image prune -a + +# Limpiar volúmenes sin usar +docker volume prune + +# Limpiar redes sin usar +docker network prune + +# Limpieza total (cuidado!) +docker system prune -a --volumes +``` + +#### Problema: Gitea no responde +```bash +# Ver estado del contenedor +docker ps | grep gitea + +# Reiniciar Gitea +docker restart [gitea_container_id] + +# Ver logs +docker logs [gitea_container_id] | tail -100 + +# Acceso a terminal de Gitea +docker exec -it [gitea_container_id] bash +``` + +#### Problema: Alto uso de CPU/memoria +```bash +# Ver uso en tiempo real +docker stats + +# Identificar proceso problemático +ps aux | sort -k3 -rn | head -5 # Por CPU +ps aux | sort -k4 -rn | head -5 # Por memoria + +# Ver procesos de PostgreSQL +ps aux | grep postgres + +# Limitar recursos de contenedor (si es necesario) +docker update --memory 4g [container_id] +``` + +### 3.2 Contactos de Soporte + +#### Contactos Técnicos + +| Rol | Contacto | Disponibilidad | +|-----|----------|-----------------| +| **ARCHITECT** | architect@tzzr.local | Tiempo completo | +| **CAPTAIN CLAUDE** | captain@tzzr.local | Tiempo completo | +| **Soporte DB** | dba@tzzr.local | L-V 8AM-6PM | +| **Soporte Infraestructura** | infra@tzzr.local | 24/7 | + +#### Escalation Path +1. Contactar equipo de soporte directo +2. Crear ticket en Gitea: https://69.62.126.110/gitea +3. SSH a servidor central: `ssh architect@69.62.126.110` +4. Activar modo debug si es necesario + +#### Información para reportar problemas +Cuando reportes un problema, incluye: +- Fecha y hora exacta del incidente +- Mensajes de error completos +- Output de diagnósticos relevantes: + ```bash + docker ps -a + docker logs [container_id] + df -h + free -h + sudo -u postgres psql -d tzzr -c "SELECT * FROM pg_stat_activity;" + ``` +- Pasos para reproducir el problema + +### 3.3 Verificación de Salud del Sistema + +Script de diagnóstico completo: +```bash +#!/bin/bash +# Guardar como /opt/scripts/health_check.sh + +echo "=== SALUD DEL SISTEMA DECK ===" +echo "" +echo "1. Estado de Docker:" +docker ps -a +echo "" +echo "2. Uso de Recursos:" +free -h +df -h +echo "" +echo "3. Conectividad PostgreSQL:" +sudo -u postgres psql -d tzzr -c "SELECT version();" +echo "" +echo "4. Conexiones Activas:" +sudo -u postgres psql -d tzzr -c "SELECT COUNT(*) FROM pg_stat_activity;" +echo "" +echo "5. Conectividad con servidor central:" +ping -c 1 69.62.126.110 +echo "" +echo "=== FIN DIAGNÓSTICO ===" +``` + +Ejecutar: +```bash +chmod +x /opt/scripts/health_check.sh +/opt/scripts/health_check.sh +``` + +--- + +## Apéndice: Atajos Útiles + +### Alias recomendados para .bashrc +```bash +alias pgconnect='sudo -u postgres psql -d tzzr' +alias dockerps='docker ps -a --format "table {{.ID}}\t{{.Names}}\t{{.Status}}\t{{.Ports}}"' +alias dstats='docker stats --no-stream' +alias dblog='sudo tail -f /var/log/postgresql/postgresql.log' +alias sysdump='cd /tmp && docker ps -a > docker_status.txt && df -h > disk_status.txt && free -h > memory_status.txt && ps aux > process_status.txt' +``` + +Cargar alias: +```bash +source ~/.bashrc +``` + +--- + +**Fin del Manual - PARTE 2** + +Para más información sobre PARTE 1 (Primeros Pasos y Servicios), consulta el manual anterior. + +Fecha de última actualización: 2025-12-30 +# DECK - Manual de Usuario PARTE 3: Guías Rápidas + +## 1. Guía Rápida de Inicio + +### Primeros Pasos + +Cuando accedas a DECK por primera vez: + +```bash +# 1. Conéctate al servidor +ssh root@72.62.1.113 + +# 2. Verifica que estés en el directorio correcto +pwd +# Deberías estar en /root + +# 3. Visualiza la estructura general +ls -la +``` + +### Verificar Servicios con Docker + +Para asegurar que todos los servicios están funcionando: + +```bash +# Ver todos los contenedores activos +docker ps + +# Ver todos los contenedores (incluyendo detenidos) +docker ps -a + +# Ver logs de un servicio específico +docker logs -f nombre_contenedor + +# Ejemplo: Ver logs de Mailcow +docker logs -f mailcow-mailserver-1 +``` + +**Servicios esperados:** +- `mailcow-mailserver-1` - Servidor de correo +- `nextcloud-app-1` - Gestor de archivos +- `vaultwarden-app-1` - Gestor de contraseñas +- `postgres-db-1` - Base de datos +- Base de datos local de context-manager + +### Verificar PostgreSQL + +PostgreSQL es crítico para context-manager y otros servicios: + +```bash +# Acceder a PostgreSQL +docker exec -it postgres-db-1 psql -U postgres + +# Dentro de psql, ver bases de datos +\l + +# Ver usuarios +\du + +# Conectar a una base de datos específica +\c nombre_base_datos + +# Ver tablas +\dt + +# Salir +\q + +# Alternativa: Verificar desde el host +sudo systemctl status postgresql +``` + +**Status esperado:** +- PostgreSQL debe estar `active (running)` +- Puerto 5432 debe estar escuchando + +--- + +## 2. Casos de Uso Comunes + +### Caso 1: Enviar Correo con Mailcow + +#### Acceder a la interfaz web +``` +URL: https://deck.local/mailcow +o +URL: https://72.62.1.113/mailcow +``` + +#### Crear usuario de correo +1. Accede a **Mail → Mailboxes** +2. Haz clic en **+ Add Mailbox** +3. Completa: + - **Local part**: (el nombre antes del @) + - **Domain**: (selecciona dominio) + - **Password**: (contraseña segura) +4. Haz clic en **Add** + +#### Usar desde cliente de correo (Outlook, Thunderbird, Apple Mail) +``` +Servidor IMAP: mail.deck.local (o IP del servidor) +Puerto IMAP: 993 (SSL/TLS) +Servidor SMTP: mail.deck.local +Puerto SMTP: 465 (SSL/TLS) +Usuario: correo@dominio.com +Contraseña: (la que configuraste) +``` + +#### Verificar correos desde terminal +```bash +# Acceder al contenedor de Mailcow +docker exec -it mailcow-mailserver-1 bash + +# Verificar logs de correos +tail -f /var/log/mail.log + +# Salir +exit +``` + +### Caso 2: Usar Nextcloud (Gestor de Archivos) + +#### Acceder a la interfaz web +``` +URL: https://deck.local/nextcloud +o +URL: https://72.62.1.113/nextcloud +``` + +#### Crear usuario en Nextcloud +1. Accede como administrador +2. Haz clic en el icono de usuario (arriba a la derecha) +3. Selecciona **Usuarios** +4. Haz clic en **+ Nuevo usuario** +5. Completa: + - **Nombre de usuario** + - **Contraseña** +6. Asigna grupos si es necesario +7. Haz clic en **Crear** + +#### Subir archivos +1. Accede a Nextcloud +2. Haz clic en **+ (botón azul)** → **Subir archivo** +3. Selecciona archivo desde tu computadora +4. El archivo se sincronizará automáticamente + +#### Sincronizar con tu computadora +1. Descarga el cliente Nextcloud: https://nextcloud.com/install/ +2. Instala y abre el cliente +3. Completa: + - **Servidor**: https://72.62.1.113/nextcloud + - **Usuario y contraseña**: Usa las credenciales de Nextcloud +4. Selecciona carpeta local para sincronizar +5. ¡Listo! Los archivos se sincronizarán automáticamente + +### Caso 3: Gestionar Contraseñas con Vaultwarden + +#### Acceder a Vaultwarden +``` +URL: https://deck.local/vaultwarden +o +URL: https://72.62.1.113/vaultwarden +``` + +#### Crear cuenta +1. Haz clic en **Create account** +2. Completa: + - **Email**: Tu correo + - **Master password**: Contraseña maestra (muy importante, no la olvides) +3. Haz clic en **Create account** + +#### Agregar contraseña +1. Accede a Vaultwarden +2. Haz clic en **+ New item** (botón azul) +3. Selecciona **Login** +4. Completa: + - **Name**: Nombre del servicio (ej: Gmail, GitHub) + - **Username**: Tu usuario + - **Password**: Tu contraseña (o genera una) +5. Haz clic en **Save** + +#### Generar contraseña segura +1. Al crear/editar un login +2. Haz clic en el icono **🔄 Generate** junto al campo de contraseña +3. Ajusta las opciones: + - **Length**: Longitud (16+ recomendado) + - **Uppercase**: Incluir mayúsculas + - **Lowercase**: Incluir minúsculas + - **Numbers**: Incluir números + - **Special**: Incluir caracteres especiales +4. Haz clic en **Regenerate** hasta estar satisfecho +5. Haz clic en **Select** + +#### Usar en otros dispositivos +- **Extensión navegador**: Bitwarden/Vaultwarden para Chrome, Firefox, Edge +- **Aplicación móvil**: Descargar "Bitwarden" desde App Store o Google Play +- **Sincronización**: Se sincroniza automáticamente entre dispositivos + +### Caso 4: Usar context-manager para Chat IA + +#### Acceder a context-manager +```bash +# Desde la terminal de DECK +ssh root@72.62.1.113 + +# Ir a la carpeta de context-manager +cd /root/captain-claude/context-manager + +# Ver estado +docker ps | grep context +# O si se ejecuta como servicio +systemctl status context-manager +``` + +#### Configurar context-manager +```bash +# 1. Verificar archivo de configuración +cat /root/captain-claude/context-manager/.env + +# Debe contener: +# - API_KEY de Anthropic o OpenAI +# - URL de PostgreSQL +# - Configuración de base de datos + +# 2. Si necesitas cambiar configuración +nano /root/captain-claude/context-manager/.env + +# 3. Reiniciar servicio +docker restart context-manager-app-1 +# O si es servicio del sistema +systemctl restart context-manager +``` + +#### Usar context-manager desde API +```bash +# Ejemplo: Enviar consulta y obtener respuesta con contexto + +curl -X POST http://localhost:8000/api/chat \ + -H "Content-Type: application/json" \ + -d '{ + "message": "¿Cuál es la temperatura actual?", + "context_type": "sensor_data", + "session_id": "session-123" + }' + +# Respuesta esperada: +# { +# "response": "La temperatura es de 22°C", +# "context_used": ["sensor_data"], +# "timestamp": "2025-01-15T10:30:00Z" +# } +``` + +#### Ver logs de context-manager +```bash +# Ver logs en tiempo real +docker logs -f context-manager-app-1 + +# O si es servicio del sistema +journalctl -u context-manager -f +``` + +--- + +## 3. Comandos Frecuentes + +### Servicios y Estado + +| Comando | Descripción | +|---------|-------------| +| `docker ps` | Ver contenedores activos | +| `docker ps -a` | Ver todos los contenedores | +| `docker logs -f nombre` | Ver logs en tiempo real | +| `docker restart nombre` | Reiniciar contenedor | +| `docker stop nombre` | Detener contenedor | +| `docker start nombre` | Iniciar contenedor | +| `systemctl status` | Ver estado de servicios del sistema | +| `systemctl restart nombre` | Reiniciar servicio | + +### Base de Datos (PostgreSQL) + +| Comando | Descripción | +|---------|-------------| +| `docker exec -it postgres psql -U postgres` | Acceder a psql | +| `\l` | Listar bases de datos (dentro de psql) | +| `\dt` | Listar tablas (dentro de psql) | +| `\du` | Listar usuarios (dentro de psql) | +| `\q` | Salir de psql | + +### Sistema de Archivos + +| Comando | Descripción | +|---------|-------------| +| `ls -la` | Listar archivos con detalles | +| `cd /ruta` | Cambiar de directorio | +| `pwd` | Mostrar directorio actual | +| `mkdir nombre` | Crear directorio | +| `cp archivo destino` | Copiar archivo | +| `mv archivo destino` | Mover archivo | +| `rm archivo` | Eliminar archivo | +| `rm -rf carpeta` | Eliminar carpeta completa | + +### Red y Conectividad + +| Comando | Descripción | +|---------|-------------| +| `ping host` | Verificar conexión | +| `netstat -tulpn` | Ver puertos en escucha | +| `curl http://url` | Hacer solicitud HTTP | +| `ss -tulpn` | Alternativa moderna a netstat | +| `dig dominio.com` | Resolver DNS | +| `nslookup dominio.com` | Alternativa a dig | + +### SSH y Acceso Remoto + +| Comando | Descripción | +|---------|-------------| +| `ssh root@72.62.1.113` | Conectar a DECK | +| `ssh-copy-id -i ~/.ssh/tzzr root@72.62.1.113` | Copiar clave SSH | +| `ssh -i ~/.ssh/tzzr root@72.62.1.113` | Conectar con clave específica | +| `scp archivo root@72.62.1.113:/destino` | Copiar archivo a servidor | + +### Monitoreo y Rendimiento + +| Comando | Descripción | +|---------|-------------| +| `top` | Monitor de procesos | +| `htop` | Monitor mejorado (si está instalado) | +| `df -h` | Espacio en disco | +| `du -sh carpeta` | Tamaño de carpeta | +| `free -h` | Uso de RAM | +| `uptime` | Tiempo de actividad del servidor | + +--- + +## 4. Atajos y Tips Productivos + +### Tips Generales + +**1. Usa alias para comandos frecuentes** +```bash +# Editar ~/.bashrc +nano ~/.bashrc + +# Agregar alias +alias ll='ls -la' +alias dc='docker ps' +alias psql-con='docker exec -it postgres-db-1 psql -U postgres' + +# Guardar y aplicar cambios +source ~/.bashrc +``` + +**2. Historial de comandos** +```bash +# Ver últimos comandos +history + +# Ejecutar comando anterior +!! + +# Ejecutar comando que contiene "palabra" +!palabra + +# Buscar en historial +Ctrl + R (luego escribe para buscar) +``` + +**3. Copiar/Pegar eficientemente** +```bash +# Copiar salida de comando +comando | xclip -selection clipboard + +# O más simple, seleccionar con ratón en terminal +``` + +### Tips para Docker + +**1. Ver logs en tiempo real con seguimiento de errores** +```bash +# Ver últimas 100 líneas +docker logs --tail 100 nombre_contenedor + +# Ver con timestamp +docker logs -t nombre_contenedor + +# Seguir logs en tiempo real +docker logs -f --tail 20 nombre_contenedor +``` + +**2. Ejecutar comandos dentro de contenedores** +```bash +# Acceso interactivo (bash) +docker exec -it nombre_contenedor bash + +# Ejecutar comando específico +docker exec nombre_contenedor ls -la + +# Con variable de entorno +docker exec -e VAR=valor nombre_contenedor comando +``` + +**3. Gestionar múltiples contenedores** +```bash +# Detener todos los contenedores +docker stop $(docker ps -q) + +# Eliminar contenedores parados +docker container prune + +# Ver uso de recursos +docker stats +``` + +### Tips para PostgreSQL + +**1. Backups rápidos** +```bash +# Crear backup +docker exec postgres-db-1 pg_dump -U postgres nombre_base > backup.sql + +# Restaurar backup +docker exec -i postgres-db-1 psql -U postgres < backup.sql +``` + +**2. Consultas útiles** +```bash +# Dentro de psql: + +-- Ver tamaño de tablas +SELECT schemaname, tablename, pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) +FROM pg_tables ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC; + +-- Ver conexiones activas +SELECT * FROM pg_stat_activity; + +-- Matar conexión +SELECT pg_terminate_backend(pid) FROM pg_stat_activity WHERE datname='base_datos'; +``` + +### Tips para Nextcloud + +**1. Sincronización manual** +```bash +# Forzar verificación de cambios +# (Espera 30 segundos en el cliente de Nextcloud) + +# O rescanea el servidor +docker exec -it nextcloud-app-1 php occ files:scan --all +``` + +**2. Gestionar espacio** +```bash +# Ver uso de espacio en Nextcloud +docker exec -it nextcloud-app-1 php occ statistics:get + +# Eliminar versiones antiguas (liberar espacio) +docker exec -it nextcloud-app-1 php occ versions:cleanup +``` + +### Tips para Vaultwarden + +**1. Exportar contraseñas (Backup)** +``` +En la interfaz de Vaultwarden: +1. Haz clic en icono de usuario → Settings +2. Selecciona "Import/Export" +3. Haz clic en "Export vault" +4. Guarda el archivo CSV en lugar seguro +``` + +**2. Importar desde otro gestor de contraseñas** +``` +1. En el otro gestor (LastPass, 1Password, etc): + - Exporta en formato CSV +2. En Vaultwarden: + - Haz clic en usuario → Settings + - Selecciona "Import/Export" + - Haz clic en "Import" + - Selecciona archivo CSV +``` + +--- + +## Próximos Pasos + +Si necesitas ayuda adicional: +- **Problemas técnicos**: Revisa logs con `docker logs -f nombre` +- **Configuración avanzada**: Ver DECK - Manual de Usuario PARTE 2 +- **Solución de problemas**: Ver sección de Troubleshooting en el manual +- **Contacto**: Consulta con el administrador del sistema diff --git a/MANUAL_USUARIO_HST.md b/MANUAL_USUARIO_HST.md new file mode 100644 index 0000000..f82f537 --- /dev/null +++ b/MANUAL_USUARIO_HST.md @@ -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 diff --git a/glosario_she_enterprise_v2.md b/glosario_she_enterprise_v2.md deleted file mode 100644 index 6dd9307..0000000 --- a/glosario_she_enterprise_v2.md +++ /dev/null @@ -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 —* diff --git a/glosario_she_enterprise_v3.md b/glosario_she_enterprise_v3.md new file mode 100644 index 0000000..7ab08c0 --- /dev/null +++ b/glosario_she_enterprise_v3.md @@ -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