# 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](#visión-general)
2. [Arquitectura del Sistema](#arquitectura-del-sistema)
3. [Componentes del Proyecto](#componentes-del-proyecto)
4. [Estado Actual](#estado-actual)
5. [Inicio Rápido](#inicio-rápido)
6. [URLs y Puertos](#urls-y-puertos)
7. [Documentación Detallada](#documentación-detallada)
8. [Datos del Cliente Pendientes](#datos-del-cliente-pendientes)
9. [Comandos de Operación](#comandos-de-operación)
10. [Seguridad](#seguridad)
11. [Contribución](#contribución)
12. [Licencia](#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

```bash
# 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

```bash
# 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](docs/arquitectura.md) | Arquitectura técnica, diagramas, decisiones de diseño. |
| [docs/instalacion.md](docs/instalacion.md) | Guía paso a paso de instalación y configuración. |
| [docs/configuracion.md](docs/configuracion.md) | Variables de entorno, credenciales, endpoints. |
| [docs/api.md](docs/api.md) | Referencia de endpoints REST de Odoo y WACRM. |
| [docs/skills-hermes.md](docs/skills-hermes.md) | Documentación de skills de Hermes y prompts de Sofía. |
| [docs/migracion.md](docs/migracion.md) | Guía de migración de datos legacy a Odoo. |
| [docs/seguridad.md](docs/seguridad.md) | Políticas de seguridad, manejo de secretos, HMAC. |
| [docs/mantenimiento.md](docs/mantenimiento.md) | Monitoreo, backups, troubleshooting. |
| [docs/ANALISIS_SKEEN_SISTEMA.md](docs/ANALISIS_SKEEN_SISTEMA.md) | Análisis del sistema legacy actual. |
| [docs/ROADMAP_SKEEN_MEJORA.md](docs/ROADMAP_SKEEN_MEJORA.md) | Roadmap de mejoras y fases del proyecto. |
| [docs/ESTADO_PROYECTO.md](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

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

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

### Logs

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

```bash
python3 scripts/simular_meta_webhook.py
```

### Acceder a bases de datos

```bash
# PostgreSQL Odoo
sudo -u postgres psql -d skeen_odoo

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

### Recompilar WACRM

```bash
cd wacrm && npm run build
```

### Recompilar Frontend

```bash
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](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