Consultoría Alcaraz Salazar
a718592291
- Frontend React (SKEEN Brand) con Vite, TypeScript, Tailwind - Frontend Homenest (versión alternativa) - Módulos Odoo 17 custom (citas, pacientes, monedero, pagos, ventas, inventario, whatsapp) - WACRM fork (Next.js 16 + Supabase) - Hermes + Bridge + Skills (Qwen3.6 via Nan Builders) - Scripts de migración y operación - Documentación extensiva en docs/
17 KiB
17 KiB
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
- Visión General
- Arquitectura del Sistema
- Componentes del Proyecto
- Estado Actual
- Inicio Rápido
- URLs y Puertos
- Documentación Detallada
- Datos del Cliente Pendientes
- Comandos de Operación
- Seguridad
- Contribución
- 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
- Paciente escribe por WhatsApp → Meta Cloud API → WACRM.
- WACRM registra contacto, conversación y mensaje; dispara automatización.
- Automatización envía webhook al Bridge SKEEN (
:8090). - Bridge consulta a Nan Builders (Qwen3.6) con el contexto de Sofía.
- Respuesta generada se envía de vuelta a WACRM → WhatsApp.
- 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).
- Catálogo de servicios (
- 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
- Crear rama feature:
git checkout -b feature/nombre-feature - Commits atómicos y descriptivos.
- Abrir Pull Request en Gitea.
- 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