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/
436 lines
17 KiB
Markdown
436 lines
17 KiB
Markdown
# 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
|