SKEEN Derma Experts — Sistema Integral de Gestión Clínica

Cliente: SKEEN Derma Experts
Contrato: $182,500 MXN — 8 semanas (29 junio – 24 agosto 2026)
Repositorio: https://git.consultoria-as.com/consultoria-as/SKEEN-Proyecto
Servidor actual: Hetzner VPS (22 GB RAM / 6 vCPU / 77 GB SSD)
Fecha de documentación: 16 de julio de 2026

---

Tabla de Contenidos

1. Visión General
2. Arquitectura del Sistema
3. Componentes del Proyecto
4. Estado Actual
5. Inicio Rápido
6. URLs y Puertos
7. Documentación Detallada
8. Datos del Cliente Pendientes
9. Comandos de Operación
10. Seguridad
11. Contribución
12. Licencia

---

Visión General

Este proyecto implementa un sistema integral de gestión clínica para SKEEN Derma Experts, una clínica dermatológica ubicada en Playas de Rosarito, BC, México. El sistema sustituye al software legacy (https://sistema.skeenmx.app/) y unifica:

• WhatsApp Business como canal principal de comunicación con pacientes.
• IA conversacional (Hermes + modelo Qwen3.6 de Nan Builders) para atención automatizada.
• Odoo 17 como ERP/CRM central (pacientes, citas, ventas, pagos, monedero, inventario).
• WACRM como inbox compartido, pipelines Kanban y automatizaciones no-code.
• Frontend React como panel de control unificado para recepción, médicos y administración.
• Supabase self-hosted como backend de datos para WACRM y futuras integraciones.

Objetivos del Proyecto

Objetivo	Métrica
Reducir no-shows	Recordatorios automáticos 24h antes
Aumentar re-agendamiento	Re-engagement de pacientes inactivos (90 días)
Ahorrar tiempo de recepción	10–15 horas/semana en agendamiento manual
Mejorar experiencia del paciente	Respuesta inmediata 24/7 vía Sofía
Centralizar información	Un solo sistema para citas, ventas, pagos e inventario

---

Arquitectura del Sistema

┌─────────────┐      ┌─────────────────┐      ┌──────────────────┐
│   WhatsApp  │──────│  Meta Cloud API  │──────│      WACRM       │
│   (Meta)    │      │   (Oficial)      │      │  (Next.js 16)    │
└─────────────┘      └─────────────────┘      │  Inbox + CRM     │
                                              │  Pipelines       │
                                              └────────┬─────────┘
                                                       │
                              ┌────────────────────────┼────────────────────────┐
                              │                        │                        │
                              ▼                        ▼                        ▼
                       ┌─────────────┐        ┌─────────────────┐      ┌──────────────────┐
                       │   Hermes    │        │   Bridge        │      │   Supabase       │
                       │   Gateway   │◄───────│   Webhook       │      │   (PostgreSQL)   │
                       │   (IA)      │        │   (Node.js)     │      │   + Auth + RLS   │
                       └──────┬──────┘        └─────────────────┘      └────────┬─────────┘
                              │                                                  │
                              ▼                                                  ▼
                       ┌─────────────┐                                   ┌──────────────────┐
                       │  Nan Builders │                                   │      Odoo 17     │
                       │  (Qwen3.6)   │                                   │  (ERP/CRM)       │
                       └─────────────┘                                    │  Citas, Ventas,  │
                                                                          │  Pagos, Monedero │
                                                                          └────────┬─────────┘
                                                                                   │
                              ┌────────────────────────────────────────────────────┘
                              │
                              ▼
                       ┌─────────────┐
                       │  Frontend   │
                       │  React 18   │
                       │  (Vite +    │
                       │  Tailwind)  │
                       └─────────────┘

Flujo de Datos Principal

1. Paciente escribe por WhatsApp → Meta Cloud API → WACRM.
2. WACRM registra contacto, conversación y mensaje; dispara automatización.
3. Automatización envía webhook al Bridge SKEEN (:8090).
4. Bridge consulta a Nan Builders (Qwen3.6) con el contexto de Sofía.
5. Respuesta generada se envía de vuelta a WACRM → WhatsApp.
6. Sofía puede consultar Odoo vía API para:
   • Catálogo de servicios (skeen-rag).
   • Agendar citas (skeen-agendar).
   • Consultar saldo/monedero (skeen-monedero).
   • Procesar pagos (skeen-pagos).
7. Frontend React muestra citas, pacientes, ventas, mensajes WACRM y leads en tiempo real.

---

Componentes del Proyecto

1. Frontend React (frontend/)

Tecnologías: React 18, Vite, TypeScript, Tailwind CSS, React Router, Recharts, Axios.

Rol: Panel de control unificado para recepción, médicos y administración.

Secciones:

• Dashboard (stats, citas del día, ventas).
• Agenda / Calendario (crear, editar, cancelar citas).
• Pacientes (búsqueda, expediente, historial).
• Servicios (catálogo con precios y paquetes).
• Ventas / Corte de caja.
• Pagos / Adeudos.
• Monedero digital (puntos de fidelidad).
• Inventario (productos y consumibles).
• WACRM Mensajes (conversaciones de WhatsApp).
• WACRM Leads (pipelines Kanban).
• Reportes y analytics.

Build: npm run build → desplegado en /var/www/skeen-frontend vía nginx.

2. Frontend Homenest (frontend-homenest/)

Tecnologías: React 18, Vite, TypeScript, Tailwind CSS.

Rol: Versión alternativa del frontend con diseño "Homenest" (basado en la guía de marca de designmd.ai). No está en uso actualmente; se mantiene como referencia.

3. Módulos Odoo Custom (odoo-addons/)

Odoo 17 Community con módulos personalizados para SKEEN:

Módulo	Propósito
skeen_citas	Gestión de citas médicas, disponibilidad, paquetes de sesiones.
skeen_pacientes	Extensión de res.partner para pacientes, expedientes médicos.
skeen_monedero	Sistema de puntos/fidelidad (1 punto = $1 MXN por cada $10 gastados).
skeen_pagos	Pagos, adeudos, integración futura Stripe/MercadoPago.
skeen_ventas	Ventas, corte de caja, comisiones, metas.
skeen_inventario	Inventario de productos y consumibles.
skeen_whatsapp	API REST para Hermes/WACRM y Frontend React.

Base de datos: PostgreSQL (skeen_odoo)
Puerto: 8069
Usuario admin: admin / contraseña almacenada en odoo.conf

4. WACRM (wacrm/)

Fork: https://github.com/ArnasDon/wacrm (MIT)
Rol: Inbox compartido de WhatsApp, CRM, pipelines, automatizaciones no-code.

Características:

• Shared inbox multi-agente.
• Contactos, tags, campos personalizados.
• Pipelines Kanban (Lead → Consulta → Tratamiento → Recurrente).
• Automatizaciones visuales.
• Broadcasts con templates Meta.
• API REST pública (/api/v1/*).
• Webhooks outbound firmados con HMAC-SHA256.

Puerto: 3000
Backend: Supabase (PostgreSQL + Auth + Realtime)

5. Hermes + Bridge (hermes/)

Hermes: Agente IA autónomo de Nous Research.
Modelo: Qwen3.6 via https://api.nan.builders/v1
Bridge: Servidor Node.js (webhook-bridge.js) que conecta WACRM con la API de Nan Builders.

Skills disponibles:

• skeen-rag: Catálogo de servicios, precios, paquetes.
• skeen-agendar: Agendamiento de citas en Odoo.
• skeen-pagos: Consulta de saldo y generación de links de pago.
• skeen-monedero: Consulta y redención de puntos.
• skeen-recordatorios: Recordatorios automáticos (heartbeat cada 30 min).

Puertos:

• Hermes Gateway: 8080 (API)
• Hermes Serve: 9119 (Dashboard)
• Bridge Webhook: 8090

6. Migración (migracion/)

Scripts para extraer datos del sistema legacy e importarlos a Odoo:

• importar_a_odoo.py: Importación principal de pacientes, servicios, citas, ventas, pagos.
• importar_servicios_inventario.py: Importación de catálogo de servicios e inventario desde CSV.
• extraer_skeen.py: Extracción de datos del sistema legacy (requiere autorización).
• ejecutar_migracion.sh: Script wrapper de ejecución.

7. Scripts (scripts/)

• skeen-start-all.sh: Inicia todo el ecosistema.
• skeen-stop-all.sh: Detiene todo el ecosistema.
• skeen-start-odoo.sh: Inicia solo Odoo.
• odoo-test-data.py: Pruebas de datos en Odoo.
• simular_meta_webhook.py: Simulador de webhook de Meta para testing.

8. Infraestructura (infra/)

• odoo.conf: Configuración de Odoo.
• docker-compose.dev.yml: Desarrollo local (roadmap-hermes).

---

Estado Actual

✅ Completado

Área	Estado
Supabase self-hosted	Funcionando (Docker healthy)
WACRM	Funcionando (build producción)
Odoo 17 + módulos custom	Funcionando
Frontend React "SKEEN Brand"	Funcionando (nginx)
Hermes Gateway + Bridge	Funcionando
Integración WACRM ↔ Hermes	Funcionando (flujo end-to-end)
Integración Odoo ↔ Frontend	Funcionando
Integración WACRM ↔ Odoo	Funcionando (proxy/cache)
Catálogo de servicios con paquetes	Funcionando
Agendamiento normal y paquetes	Funcionando
Script de importación CSV	Funcionando
Documentación	En progreso

⚠️ Pendiente

Área	Bloqueo
Número WhatsApp Business real	Cliente debe verificar en Meta
Meta App ID / Secret / Token	Cliente debe crear app en Meta Developers
Templates de WhatsApp aprobados	Subir y esperar aprobación de Meta
Lista de servicios real	Cliente debe enviar CSV
Stripe / MercadoPago	Cliente debe entregar keys
Dominio skeen.mx	DNS no apuntado aún
SSL / HTTPS	Configurar con Let's Encrypt
Backups automatizados	Configurar cron
Monitoreo Uptime Kuma	Configurar

---

Inicio Rápido

Requisitos

• Ubuntu 22.04+
• Docker + Docker Compose
• Node.js 20+
• Python 3.12+
• PostgreSQL 16
• nginx

Instalación

# Clonar el repositorio
git clone https://git.consultoria-as.com/consultoria-as/SKEEN-Proyecto.git
cd SKEEN-Proyecto

# Instalar dependencias del frontend
cd frontend && npm install && cd ..

# Configurar variables de entorno
cp wacrm/.env.local.example wacrm/.env.local
# Editar wacrm/.env.local con credenciales reales

# Iniciar todo
./scripts/skeen-start-all.sh

Verificación

# Estado de servicios
ss -tlnp | grep -E "3000|5173|8069|8000|8090|8644|8080|9119"

# Health checks
curl http://localhost:8069/web/health
curl http://localhost:8090/health
curl http://localhost:8069/skeen/frontend/v1/health

---

URLs y Puertos

Servicio	URL Local	Puerto	Descripción
Frontend React	http://localhost:5173	5173	Dev server Vite
Frontend React (prod)	http://192.168.10.114	80	Nginx
Odoo	http://localhost:8069	8069	ERP/CRM
WACRM	http://localhost:3000	3000	Inbox WhatsApp
Supabase Kong	http://localhost:8000	8000	API Gateway
Supabase PostgreSQL	localhost:5433	5433	Base de datos
Hermes Gateway	http://localhost:8080	8080	API del agente
Hermes Serve	http://localhost:9119	9119	Dashboard Hermes
Bridge Webhook	http://localhost:8090	8090	Webhook WACRM→Hermes

---

Documentación Detallada

Documento	Contenido
docs/arquitectura.md	Arquitectura técnica, diagramas, decisiones de diseño.
docs/instalacion.md	Guía paso a paso de instalación y configuración.
docs/configuracion.md	Variables de entorno, credenciales, endpoints.
docs/api.md	Referencia de endpoints REST de Odoo y WACRM.
docs/skills-hermes.md	Documentación de skills de Hermes y prompts de Sofía.
docs/migracion.md	Guía de migración de datos legacy a Odoo.
docs/seguridad.md	Políticas de seguridad, manejo de secretos, HMAC.
docs/mantenimiento.md	Monitoreo, backups, troubleshooting.
docs/ANALISIS_SKEEN_SISTEMA.md	Análisis del sistema legacy actual.
docs/ROADMAP_SKEEN_MEJORA.md	Roadmap de mejoras y fases del proyecto.
docs/ESTADO_PROYECTO.md	Estado detallado del proyecto.

---

Datos del Cliente Pendientes

Cuando SKEEN entregue estos datos, se conectan en los siguientes lugares:

Dato	Dónde se usa	Archivo / UI
Número WhatsApp Business verificado	Meta Developers + WACRM	WACRM Settings → WhatsApp
Meta App ID + App Secret	WACRM webhook signature	wacrm/.env.local (META_APP_SECRET)
Meta Access Token + WABA ID + Phone Number ID	Envío/recepción WhatsApp	WACRM Settings → WhatsApp
Templates de WhatsApp aprobados	Automatizaciones y campañas	WACRM + Meta Business Manager
Lista de servicios y precios (CSV)	Catálogo + Odoo	migracion/importar_servicios_inventario.py
Horarios de atención	Agendamiento	Skill skeen-agendar + Odoo skeen_citas
Stripe / MercadoPago keys	Pagos	Odoo skeen_pagos + skill skeen-pagos
Dominio skeen.mx	DNS + Nginx	Configuración DNS
Logo / branding	WACRM + Frontend	Assets y configuración

---

Comandos de Operación

Iniciar / Detener

# Iniciar todo el ecosistema
./scripts/skeen-start-all.sh

# Detener todo
./scripts/skeen-stop-all.sh

Logs

tail -f /tmp/wacrm.log
tail -f /tmp/hermes-bridge.log
tail -f /tmp/odoo.log
tail -f /tmp/frontend.log
tail -f /tmp/hermes-gateway.log
tail -f /tmp/hermes-serve.log

Simular mensaje de WhatsApp

python3 scripts/simular_meta_webhook.py

Acceder a bases de datos

# PostgreSQL Odoo
sudo -u postgres psql -d skeen_odoo

# PostgreSQL Supabase
docker exec supabase-db psql -U postgres -d postgres

Recompilar WACRM

cd wacrm && npm run build

Recompilar Frontend

cd frontend && npm run build
cp -r dist/* /var/www/skeen-frontend/

---

Seguridad

• No commitear secretos: .env, .env.local, *.key, *.pem, tokens de Meta, keys de Stripe.
• Webhooks WACRM: Firman con HMAC-SHA256 usando WACRM_WEBHOOK_SECRET.
• Odoo API: Autenticación con API key para endpoints JSON-RPC.
• Supabase: Row-Level Security (RLS) habilitado en tablas sensibles.
• Supabase self-hosted: Solo escuchar en localhost o red interna.
• HTTPS: Configurar SSL en producción con Let's Encrypt.

Ver docs/seguridad.md para más detalles.

---

Contribución

1. Crear rama feature: git checkout -b feature/nombre-feature
2. Commits atómicos y descriptivos.
3. Abrir Pull Request en Gitea.
4. Code review obligatorio antes de merge a main.

---

Licencia

Este proyecto es propiedad de Consultoría Alcaraz Salazar, S.A.S. y SKEEN Derma Experts.

Componentes open-source:

• WACRM: MIT License
• Odoo: LGPL v3
• Supabase: Apache 2.0
• Hermes: Ver licencia en https://github.com/NousResearch/Hermes-Agent
• React / Vite / Tailwind: MIT

---

Contacto

Consultoría Alcaraz Salazar, S.A.S.
Desarrollador: Iván Alcaraz
Email: ialcarazsalazar@consultoria-as.com
Gitea: https://git.consultoria-as.com/consultoria-as/SKEEN-Proyecto