consultoria-as/SKEEN-Proyecto
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: SKEEN Derma Experts - Sistema Integral de Gestión Clínica

Browse Source 
- 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/
This commit is contained in:
Consultoría Alcaraz Salazar
2026-07-20 07:44:23 +00:00
commit a718592291
699 changed files with 324602 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

435
README.md Normal file
View File

@@ -0,0 +1,435 @@
# 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