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

docs: update README with completed phases and add Odoo module install guide

Browse Source 
- Updated README with all 6 completed phases
- Added access URLs for local network
- Added default credentials section
- Created comprehensive Odoo module installation guide
- Added project structure documentation

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Claude AI
2026-01-29 22:53:29 +00:00
parent e10d67b19d
commit 991b8ddfe8
2 changed files with 432 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

231
README.md
View File

@@ -2,6 +2,19 @@
Plataforma de mensajería centralizada con automatización de chatbots, gestión multi-agente e integración profunda con Odoo. Plataforma de mensajería centralizada con automatización de chatbots, gestión multi-agente e integración profunda con Odoo.
## Estado del Proyecto
| Fase | Descripción | Estado |
|------|-------------|--------|
| Fase 1 | Fundación (WhatsApp Core + API + Frontend) | Completada |
| Fase 2 | Flow Engine Básico | Completada |
| Fase 3 | Inbox Avanzado + Multi-agente | Completada |
| Fase 4 | Flow Engine Avanzado | Completada |
| Fase 5 | Integración Odoo Completa | Completada |
| Fase 6 | Módulo Odoo (odoo_whatsapp_hub) | Completada |
| Fase 7 | Reportes y Analytics | Pendiente |
| Fase 8 | Multi-canal (Email, SMS) | Futuro |
## Descripción ## Descripción
WhatsApp Centralizado es una solución empresarial similar a Kommo, Wasapi, ManyChat y Brevo, diseñada para: WhatsApp Centralizado es una solución empresarial similar a Kommo, Wasapi, ManyChat y Brevo, diseñada para:
@@ -11,15 +24,16 @@ WhatsApp Centralizado es una solución empresarial similar a Kommo, Wasapi, Many
- **Integrar con Odoo** de forma bidireccional (CRM, Ventas, Inventario, Helpdesk, etc.) - **Integrar con Odoo** de forma bidireccional (CRM, Ventas, Inventario, Helpdesk, etc.)
- **Conectar múltiples números** de WhatsApp desde una sola plataforma - **Conectar múltiples números** de WhatsApp desde una sola plataforma
## Características Principales ## Características Implementadas
### Flow Builder Visual ### Flow Builder Visual
- 30+ tipos de nodos (mensajes, lógica, validación, acciones) - 30+ tipos de nodos (mensajes, lógica, validación, acciones)
- Editor drag & drop con React Flow - Editor drag & drop con React Flow
- Variables y contexto de conversación - Variables globales y contexto de conversación
- A/B Testing integrado - A/B Testing integrado
- Integración con IA (GPT, Claude, Ollama) - Integración con IA (DeepSeek)
- Sub-flujos reutilizables - Sub-flujos reutilizables
- Plantillas predefinidas
### Gestión Multi-Agente ### Gestión Multi-Agente
- Sistema de colas (Ventas, Soporte, etc.) - Sistema de colas (Ventas, Soporte, etc.)
@@ -27,38 +41,53 @@ WhatsApp Centralizado es una solución empresarial similar a Kommo, Wasapi, Many
- Transferencia bot → humano → bot - Transferencia bot → humano → bot
- Panel de supervisor en tiempo real - Panel de supervisor en tiempo real
- SLA tracking con alertas - SLA tracking con alertas
- Encuestas CSAT integradas - Notas internas y respuestas rápidas
### Integración Odoo ### Integración Odoo (Fase 5)
- Conexión bidireccional via XML-RPC - Conexión via XML-RPC con autenticación
- 8 módulos soportados (Contactos, CRM, Ventas, Inventario, Helpdesk, Facturación, Calendario, Productos) - Sincronización bidireccional de contactos
- 20+ acciones disponibles en flujos - 8 nodos de flujo para Odoo:
- Automatizaciones Odoo → WhatsApp - Buscar/Crear Partner
- Módulo Odoo con widget de chat - Consultar Saldo
- Buscar/Ver Pedidos
- Buscar Productos
- Verificar Stock
- Crear Lead CRM
- Webhooks para eventos de Odoo
### Módulo Odoo - odoo_whatsapp_hub (Fase 6)
- Módulo nativo para Odoo 19
- Gestión de cuentas WhatsApp
- Historial de conversaciones en contactos
- Widget de chat OWL en tiempo real
- Envío individual y masivo de mensajes
- Webhooks bidireccionales
- Integración completa con res.partner
## Stack Tecnológico ## Stack Tecnológico
| Componente | Tecnología | | Componente | Tecnología | Puerto |
|------------|------------| |------------|------------|--------|
| WhatsApp Core | Node.js + TypeScript + Baileys | | WhatsApp Core | Node.js + TypeScript + Baileys | 3001 |
| API Gateway | Python + FastAPI | | API Gateway | Python + FastAPI | 8000 |
| Flow Engine | Python | | Flow Engine | Python + FastAPI | 8001 |
| Frontend | React + TypeScript | | Integrations | Python + FastAPI | 8002 |
| Base de Datos | PostgreSQL + Redis | | Frontend | React + TypeScript + Vite | 3000 |
| Despliegue | Docker + Docker Compose | | Base de Datos | PostgreSQL 16 | 5432 |
| Cache/PubSub | Redis 7 | 6379 |
## Arquitectura ## Arquitectura
``` ```
┌─────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────┐
│ FRONTEND (React) │ │ FRONTEND (React) │
│ Dashboard │ Inbox Chat │ Flow Builder (React Flow) │ │ Dashboard │ Inbox Chat │ Flow Builder │ Odoo Config │
└─────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────┐
│ API GATEWAY (FastAPI) │ │ API GATEWAY (FastAPI) │
│ JWT Auth │ REST API │ WebSocket (tiempo real) │ │ JWT Auth │ REST API │ WebSocket │ Odoo Config API │
└─────────────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────────┘
│ │
┌───────────────┼───────────────┐ ┌───────────────┼───────────────┐
@@ -66,76 +95,188 @@ WhatsApp Centralizado es una solución empresarial similar a Kommo, Wasapi, Many
┌──────────────────┐ ┌──────────────┐ ┌──────────────────────────┐ ┌──────────────────┐ ┌──────────────┐ ┌──────────────────────────┐
│ WHATSAPP CORE │ │ FLOW ENGINE │ │ INTEGRATIONS │ │ WHATSAPP CORE │ │ FLOW ENGINE │ │ INTEGRATIONS │
│ (Node.js) │ │ (Python) │ │ (Python) │ │ (Node.js) │ │ (Python) │ │ (Python) │
│ Baileys │ │ Motor bot │ │ Odoo, Webhooks │ │ Baileys │ │ 30+ Nodos │ │ Odoo XML-RPC │
│ Multi-número │ │ AI Response │ │ Webhooks │
└──────────────────┘ └──────────────┘ └──────────────────────────┘ └──────────────────┘ └──────────────┘ └──────────────────────────┘
│ │ │
└───────────────┼───────────────┘
│ │
┌─────────┴─────────┐ ┌─────────┴─────────┐
▼ ▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│PostgreSQL│ │ Redis │ │PostgreSQL│ │ Redis │
│ :5432 │ │ :6379 │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
│
▼
┌──────────────────┐
│ ODOO 19 │
│ odoo_whatsapp_hub│
└──────────────────┘
``` ```
## Inicio Rápido ## Instalación
### Requisitos ### Requisitos
- Docker 24.0+ - Docker 24.0+
- Docker Compose 2.20+ - Docker Compose 2.20+
- 4GB RAM mínimo (8GB recomendado) - 4GB RAM mínimo (8GB recomendado)
- Odoo 19 (para el módulo)
### Instalación ### Instalación Rápida
```bash ```bash
# Clonar repositorio # Clonar repositorio
git clone https://git.consultoria-as.com/tu-usuario/WhatsAppCentralizado.git git clone https://git.consultoria-as.com/consultoria-as/WhatsAppCentralizado.git
cd WhatsAppCentralizado cd WhatsAppCentralizado
# Copiar configuración # Copiar configuración
cp .env.example .env cp .env.example .env
# Editar variables de entorno # Editar variables de entorno (ver sección Configuración)
nano .env nano .env
# Iniciar servicios # Iniciar servicios
docker-compose up -d docker-compose up -d
# Aplicar migraciones # Ver logs
docker-compose exec api-gateway alembic upgrade head docker-compose logs -f
# Crear usuario admin # Aplicar migraciones de base de datos
docker-compose exec api-gateway python scripts/create_admin.py docker-compose exec api-gateway alembic upgrade head
``` ```
### Acceso ## Configuración
- Frontend: http://localhost:3000
- API: http://localhost:8000 ### Variables de Entorno Principales
- Docs API: http://localhost:8000/docs
```bash
# Base de Datos
DB_USER=whatsapp_admin
DB_PASSWORD=tu_password_seguro
DB_NAME=whatsapp_central
# JWT (generar con: openssl rand -base64 64)
JWT_SECRET=tu_secreto_jwt
# Odoo
ODOO_URL=https://tu-empresa.odoo.com
ODOO_DB=nombre_base_datos
ODOO_USER=usuario@empresa.com
ODOO_API_KEY=tu_api_key
# DeepSeek AI (opcional, para nodos AI)
DEEPSEEK_API_KEY=tu_api_key
```
## Acceso
### URLs de Acceso Local
| Servicio | URL Local | URL Red Local |
|----------|-----------|---------------|
| Frontend | http://localhost:3000 | http://192.168.10.221:3000 |
| API Gateway | http://localhost:8000 | http://192.168.10.221:8000 |
| API Docs (Swagger) | http://localhost:8000/docs | http://192.168.10.221:8000/docs |
| WhatsApp Core | http://localhost:3001 | http://192.168.10.221:3001 |
| Integrations API | http://localhost:8002 | http://192.168.10.221:8002 |
### Credenciales por Defecto
```
Usuario: admin@whatsapp.local
Password: admin123
(Cambiar inmediatamente en producción)
```
## Instalación del Módulo Odoo
Ver guía completa en: [docs/odoo-module-install.md](docs/odoo-module-install.md)
### Instalación Rápida
1. Copiar el módulo a tu instancia de Odoo:
```bash
cp -r odoo_whatsapp_hub /ruta/a/odoo/addons/
```
2. Reiniciar Odoo y actualizar lista de apps
3. Buscar "WhatsApp Hub" e instalar
4. Configurar la cuenta en WhatsApp > Configuración > Cuentas
## Estructura del Proyecto
```
WhatsAppCentralizado/
├── services/
│ ├── whatsapp-core/ # Node.js + Baileys
│ ├── api-gateway/ # FastAPI principal
│ ├── flow-engine/ # Motor de flujos
│ └── integrations/ # Odoo XML-RPC
├── frontend/ # React + Vite
├── database/
│ └── migrations/ # Alembic migrations
├── odoo_whatsapp_hub/ # Módulo Odoo 19
│ ├── models/
│ ├── views/
│ ├── wizards/
│ ├── controllers/
│ └── static/
├── nginx/ # Configuración reverse proxy
├── docs/ # Documentación
└── docker-compose.yml
```
## Documentación ## Documentación
- [Diseño del Sistema](docs/plans/2026-01-29-whatsapp-centralizado-design.md) - [Diseño del Sistema](docs/plans/2026-01-29-whatsapp-centralizado-design.md)
- [Arquitectura](docs/architecture/README.md) - [Arquitectura de Base de Datos](docs/database/README.md)
- [API Reference](docs/api/README.md) - [API Reference](docs/api/README.md)
- [Flow Builder](docs/flow-builder/README.md) - [Flow Builder](docs/flow-builder/README.md)
- [Integración Odoo](docs/odoo-integration/README.md) - [Integración Odoo](docs/odoo-integration/README.md)
- [Instalación Módulo Odoo](docs/odoo-module-install.md)
- [Guía de Despliegue](docs/deployment/README.md) - [Guía de Despliegue](docs/deployment/README.md)
## Roadmap ## Servicios Docker
- [x] Diseño y arquitectura ```bash
- [ ] Fase 1: Fundación (WhatsApp Core + API + Frontend básico) # Ver estado de servicios
- [ ] Fase 2: Flow Engine Básico docker-compose ps
- [ ] Fase 3: Inbox Avanzado + Multi-agente
- [ ] Fase 4: Flow Engine Avanzado # Reiniciar un servicio
- [ ] Fase 5: Integración Odoo Completa docker-compose restart api-gateway
- [ ] Fase 6: Módulo Odoo
- [ ] Fase 7: Reportes y Analytics # Ver logs de un servicio
- [ ] Fase 8: Multi-canal (Email, SMS) docker-compose logs -f flow-engine
# Escalar servicios (si es necesario)
docker-compose up -d --scale whatsapp-core=2
```
## Próximas Fases
### Fase 7: Reportes y Analytics (Pendiente)
- Dashboard de analytics
- Métricas por agente/cola/flujo
- Reportes CSAT
- Exportación de datos
- Reportes programados
### Fase 8: Multi-canal (Futuro)
- Integración Email (SMTP/IMAP)
- Integración SMS (Twilio)
- WhatsApp Business API oficial
- Inbox unificado
## Licencia ## Licencia
Propietario - Todos los derechos reservados. Propietario - Todos los derechos reservados.
Desarrollado por Consultoria AS.
## Contacto ## Contacto
Desarrollado para uso interno empresarial. - Repositorio: https://git.consultoria-as.com/consultoria-as/WhatsAppCentralizado
- Desarrollado para uso interno empresarial.

245
docs/odoo-module-install.md Normal file
View File

@@ -0,0 +1,245 @@
# Guía de Instalación: Módulo Odoo WhatsApp Hub
Esta guía explica cómo instalar y configurar el módulo `odoo_whatsapp_hub` en tu instancia de Odoo 19.
## Requisitos Previos
- Odoo 19 Community o Enterprise
- Acceso de administrador a la instancia de Odoo
- WhatsApp Centralizado en ejecución y accesible desde Odoo
- Python 3.10+ (incluido en Odoo 19)
## Método 1: Instalación Manual (Recomendado)
### Paso 1: Copiar el Módulo
Copia la carpeta `odoo_whatsapp_hub` al directorio de addons de tu instalación de Odoo:
```bash
# Si Odoo está instalado localmente
cp -r /ruta/a/WhatsAppCentralizado/odoo_whatsapp_hub /ruta/a/odoo/addons/
# Si usas Docker
docker cp odoo_whatsapp_hub odoo_container:/mnt/extra-addons/
# Si usas Odoo.sh
# Sube el módulo via Git al repositorio de tu proyecto
```
### Paso 2: Agregar Ruta de Addons (si es necesario)
Si usas un directorio custom, asegúrate de que esté en la configuración de Odoo:
```ini
# /etc/odoo/odoo.conf
[options]
addons_path = /usr/lib/python3/dist-packages/odoo/addons,/mnt/extra-addons
```
### Paso 3: Reiniciar Odoo
```bash
# Systemd
sudo systemctl restart odoo
# Docker
docker-compose restart odoo
# Manual
./odoo-bin -c /etc/odoo/odoo.conf
```
### Paso 4: Actualizar Lista de Aplicaciones
1. Ir a **Aplicaciones**
2. Hacer clic en **Actualizar lista de aplicaciones**
3. Confirmar la actualización
### Paso 5: Instalar el Módulo
1. En **Aplicaciones**, quitar el filtro "Apps"
2. Buscar "**WhatsApp Hub**"
3. Hacer clic en **Instalar**
## Método 2: Instalación via Git (Odoo.sh o desarrollo)
```bash
# En el directorio de tu proyecto Odoo
cd /ruta/a/tu/proyecto/odoo
# Clonar o copiar como submódulo
git submodule add https://git.consultoria-as.com/consultoria-as/WhatsAppCentralizado.git external/whatsapp
# Crear enlace simbólico
ln -s ../external/whatsapp/odoo_whatsapp_hub addons/odoo_whatsapp_hub
# Commit y push
git add .
git commit -m "Add WhatsApp Hub module"
git push
```
## Configuración Post-Instalación
### 1. Configurar Cuenta WhatsApp
1. Ir a **WhatsApp > Configuración > Cuentas WhatsApp**
2. Editar la cuenta "WhatsApp Principal" o crear una nueva
3. Configurar:
| Campo | Valor | Descripción |
|-------|-------|-------------|
| Nombre | Mi WhatsApp | Nombre descriptivo |
| URL API | http://192.168.10.221:8000 | URL de WhatsApp Centralizado |
| API Key | (tu token JWT) | Token de autenticación |
| ID Externo | (ID de la cuenta) | ID de la cuenta en WhatsApp Central |
| Cuenta por Defecto | ✓ | Marcar si es la principal |
### 2. Obtener el API Key
Para obtener el token JWT:
```bash
# Hacer login en la API
curl -X POST http://192.168.10.221:8000/api/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "admin@whatsapp.local", "password": "admin123"}'
# Respuesta:
# {"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."}
```
Copia el `access_token` y pégalo en el campo **API Key** de la cuenta WhatsApp.
### 3. Vincular Cuenta Externa
El **ID Externo** es el ID de la cuenta de WhatsApp en el sistema central:
1. Ir a WhatsApp Centralizado > Cuentas
2. Copiar el ID de la cuenta conectada
3. Pegarlo en el campo **ID Externo** en Odoo
### 4. Configurar Webhook en WhatsApp Central
Para recibir mensajes en Odoo, configura el webhook:
**URL del Webhook:** `https://tu-odoo.com/whatsapp/webhook`
En WhatsApp Centralizado, ve a Configuración y agrega:
- URL: `https://tu-odoo.com/whatsapp/webhook`
- Eventos: `message`, `status_update`, `conversation_update`
## Uso del Módulo
### Ver Conversaciones
1. Ir a **WhatsApp > Conversaciones**
2. Vista Kanban agrupada por estado
3. Filtros: No leídos, Activas, Mis conversaciones
### Enviar WhatsApp desde Contacto
1. Abrir un contacto en **Contactos**
2. Hacer clic en **Enviar WhatsApp** (botón verde)
3. Escribir mensaje y enviar
### Envío Masivo
1. Seleccionar múltiples contactos en la lista
2. Acción > **Enviar WhatsApp**
3. Escribir mensaje con variables opcionales (`{{name}}`, `{{email}}`)
4. Confirmar envío
### Widget de Chat
El widget de chat OWL está disponible en la vista de conversaciones para enviar mensajes en tiempo real.
## Estructura del Módulo
```
odoo_whatsapp_hub/
├── __manifest__.py # Manifest del módulo (v19.0.1.0.0)
├── __init__.py
├── models/
│ ├── whatsapp_account.py # Cuentas WhatsApp
│ ├── whatsapp_conversation.py # Conversaciones
│ ├── whatsapp_message.py # Mensajes
│ └── res_partner.py # Extensión de contactos
├── controllers/
│ └── webhook.py # Endpoint para webhooks
├── wizards/
│ ├── send_whatsapp.py # Wizard envío individual
│ └── mass_whatsapp.py # Wizard envío masivo
├── views/
│ ├── whatsapp_menu.xml
│ ├── whatsapp_account_views.xml
│ ├── whatsapp_conversation_views.xml
│ ├── res_partner_views.xml
│ └── send_whatsapp_wizard.xml
├── security/
│ └── ir.model.access.csv # Permisos de acceso
├── data/
│ └── whatsapp_data.xml # Datos iniciales
└── static/src/
├── css/whatsapp.css # Estilos WhatsApp
├── js/chat_widget.js # Widget OWL
└── xml/chat_widget.xml # Template OWL
```
## Permisos
| Modelo | Usuario Normal | Administrador |
|--------|----------------|---------------|
| whatsapp.account | Solo lectura | CRUD completo |
| whatsapp.conversation | Leer, Crear, Escribir | CRUD completo |
| whatsapp.message | Leer, Crear, Escribir | CRUD completo |
## Solución de Problemas
### El módulo no aparece en la lista
1. Verificar que la carpeta esté en `addons_path`
2. Reiniciar Odoo con `-u all` o `--update=all`
3. Verificar logs: `tail -f /var/log/odoo/odoo.log`
### Error de conexión a la API
1. Verificar que WhatsApp Centralizado esté corriendo
2. Probar conexión: `curl http://192.168.10.221:8000/health`
3. Verificar firewall permite conexión desde Odoo
### Webhooks no funcionan
1. Verificar que Odoo sea accesible desde WhatsApp Central
2. Probar endpoint: `curl https://tu-odoo.com/whatsapp/webhook/test`
3. Revisar logs de Odoo para errores
### Mensajes no se envían
1. Verificar API Key válido
2. Verificar ID Externo correcto
3. Verificar cuenta conectada en WhatsApp Central
4. Revisar logs del servicio integrations
## Actualizaciones
Para actualizar el módulo:
```bash
# Copiar nueva versión
cp -r /nueva/version/odoo_whatsapp_hub /ruta/a/odoo/addons/
# Reiniciar y actualizar
./odoo-bin -c /etc/odoo/odoo.conf -u odoo_whatsapp_hub
```
O desde la interfaz:
1. Ir a **Aplicaciones**
2. Buscar "WhatsApp Hub"
3. Menú ⋮ > **Actualizar**
## Soporte
Para problemas o consultas:
- Repositorio: https://git.consultoria-as.com/consultoria-as/WhatsAppCentralizado
- Issues: Crear issue en el repositorio