rckrdmrd/erp-core-backend-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Add README.md for 8 backend modules

Browse Source 
Added documentation for:
- ai: 9 entities, 25+ endpoints for AI integration
- mcp: 2 entities, 8 tool providers for MCP Server
- webhooks: 6 entities for outbound webhooks
- whatsapp: 10 entities for WhatsApp Business
- storage: 7 entities for file storage (S3/R2)
- feature-flags: 3 entities for feature toggles
- biometrics: 4 entities for biometric auth
- geolocation: placeholder for planned module

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Adrian Flores Cortes 2026-01-25 03:47:00 -06:00
parent b0f6347485
commit cf3d560cdc
8 changed files with 640 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
src/modules/ai/README.md Normal file
View File

@ -0,0 +1,76 @@
# AI Module
## Descripcion
Modulo de integracion con modelos de Inteligencia Artificial. Proporciona capacidades de chat conversacional, completions, embeddings y gestion de bases de conocimiento. Soporta multiples proveedores (OpenAI, Anthropic, Google, Azure) a traves de OpenRouter, con control de acceso basado en roles y gestion de cuotas por tenant.
## Entidades
| Entidad | Schema | Descripcion |
|---------|--------|-------------|
| `AIModel` | ai.models | Catalogo de modelos de IA disponibles (GPT-4, Claude, etc.) con configuracion de costos y capacidades |
| `AIPrompt` | ai.prompts | Templates de prompts versionados con variables y configuracion de modelo |
| `AIConversation` | ai.conversations | Conversaciones de chat con historial, contexto y estadisticas |
| `AIMessage` | ai.messages | Mensajes individuales dentro de una conversacion |
| `AICompletion` | ai.completions | Registros de completions individuales (no conversacionales) |
| `AIEmbedding` | ai.embeddings | Vectores de embeddings para busqueda semantica |
| `AIKnowledgeBase` | ai.knowledge_base | Articulos de conocimiento con embeddings para RAG |
| `AIUsageLog` | ai.usage_logs | Registro detallado de uso por request |
| `AITenantQuota` | ai.tenant_quotas | Cuotas mensuales de tokens, requests y costos por tenant |
## Servicios
| Servicio | Responsabilidades |
|----------|-------------------|
| `AIService` | Servicio base: CRUD de modelos, prompts, conversaciones, mensajes; registro de uso; gestion de cuotas |
| `RoleBasedAIService` | Extension con control de acceso basado en roles ERP; integracion con OpenRouter; ejecucion de tools |
## Endpoints
| Method | Path | Descripcion |
|--------|------|-------------|
| GET | `/models` | Lista todos los modelos activos |
| GET | `/models/:id` | Obtiene modelo por ID |
| GET | `/models/code/:code` | Obtiene modelo por codigo |
| GET | `/models/provider/:provider` | Lista modelos por proveedor |
| GET | `/models/type/:type` | Lista modelos por tipo (chat/embedding/etc) |
| GET | `/prompts` | Lista prompts del tenant |
| GET | `/prompts/:id` | Obtiene prompt por ID |
| GET | `/prompts/code/:code` | Obtiene prompt por codigo |
| POST | `/prompts` | Crea nuevo prompt |
| PATCH | `/prompts/:id` | Actualiza prompt existente |
| GET | `/conversations` | Lista conversaciones del tenant |
| GET | `/conversations/:id` | Obtiene conversacion con mensajes |
| GET | `/conversations/user/:userId` | Lista conversaciones de usuario |
| POST | `/conversations` | Crea nueva conversacion |
| PATCH | `/conversations/:id` | Actualiza conversacion |
| POST | `/conversations/:id/archive` | Archiva conversacion |
| GET | `/conversations/:conversationId/messages` | Lista mensajes de conversacion |
| POST | `/conversations/:conversationId/messages` | Agrega mensaje a conversacion |
| GET | `/conversations/:conversationId/tokens` | Obtiene conteo de tokens |
| POST | `/usage` | Registra uso de IA |
| GET | `/usage/stats` | Obtiene estadisticas de uso |
| GET | `/quotas` | Obtiene cuota del tenant |
| PATCH | `/quotas` | Actualiza cuota del tenant |
| GET | `/quotas/check` | Verifica disponibilidad de cuota |
## Dependencias
- `common` - Utilidades compartidas
- `auth` - Autenticacion y tenant context
- OpenRouter API (proveedor externo)
## Configuracion
| Variable | Descripcion | Requerida |
|----------|-------------|-----------|
| `OPENROUTER_API_KEY` | API key para OpenRouter | Si |
| `APP_URL` | URL de la aplicacion (para HTTP-Referer) | No |
## Roles ERP Soportados
El `RoleBasedAIService` soporta prompts y accesos diferenciados por rol:
- `admin` - Acceso completo
- `supervisor` - Acceso a reportes y analisis
- `operator` - Acceso a operaciones basicas
- `customer` - Acceso limitado a consultas

78
src/modules/biometrics/README.md Normal file
View File

@ -0,0 +1,78 @@
# Biometrics Module
## Descripcion
Modulo de autenticacion biometrica para dispositivos moviles y web. Soporta fingerprint, Face ID, reconocimiento facial y escaneo de iris. Gestiona dispositivos registrados, credenciales biometricas (WebAuthn/FIDO2), sesiones y log de actividad.
## Entidades
| Entidad | Schema | Descripcion |
|---------|--------|-------------|
| `Device` | auth.devices | Dispositivos registrados con informacion de plataforma, biometricos y ubicacion |
| `BiometricCredential` | auth.biometric_credentials | Credenciales WebAuthn/FIDO2 vinculadas a dispositivos |
| `DeviceSession` | auth.device_sessions | Sesiones activas por dispositivo con tokens y metodo de autenticacion |
| `DeviceActivityLog` | auth.device_activity_log | Log de actividad: logins, autenticaciones biometricas, ubicaciones |
## Servicios
Este modulo actualmente solo define entidades. Los servicios de autenticacion biometrica deben implementarse en el modulo `auth` utilizando estas entidades.
## Endpoints
Los endpoints de autenticacion biometrica se exponen a traves del modulo `auth`:
| Method | Path | Descripcion |
|--------|------|-------------|
| POST | `/auth/devices/register` | Registra nuevo dispositivo |
| GET | `/auth/devices` | Lista dispositivos del usuario |
| DELETE | `/auth/devices/:id` | Elimina dispositivo |
| POST | `/auth/biometric/register` | Registra credencial biometrica |
| POST | `/auth/biometric/authenticate` | Autentica con biometrico |
| DELETE | `/auth/biometric/:id` | Elimina credencial biometrica |
## Dependencias
- `auth` - Modulo de autenticacion principal
- WebAuthn/FIDO2 library
## Configuracion
| Variable | Descripcion | Requerida |
|----------|-------------|-----------|
| `WEBAUTHN_RP_ID` | Relying Party ID (dominio) | Si |
| `WEBAUTHN_RP_NAME` | Nombre de la aplicacion | Si |
| `WEBAUTHN_ORIGIN` | Origen permitido | Si |
## Tipos Biometricos Soportados
| Tipo | Descripcion | Plataformas |
|------|-------------|-------------|
| `fingerprint` | Huella dactilar | iOS, Android, Windows Hello |
| `face_id` | Face ID de Apple | iOS |
| `face_recognition` | Reconocimiento facial | Android, Windows Hello |
| `iris` | Escaneo de iris | Dispositivos especializados |
## Plataformas Soportadas
| Plataforma | Descripcion |
|------------|-------------|
| `ios` | iPhone/iPad |
| `android` | Dispositivos Android |
| `web` | Navegadores con WebAuthn |
| `desktop` | Aplicaciones de escritorio |
## Niveles de Confianza
| Nivel | Valor | Descripcion |
|-------|-------|-------------|
| None | 0 | Dispositivo nuevo/no verificado |
| Low | 1 | Primera autenticacion biometrica |
| Medium | 2 | Uso regular sin incidentes |
| High | 3 | Dispositivo de confianza establecida |
## Seguridad
- Las credenciales biometricas usan algoritmo ES256 (ECDSA con SHA-256)
- Lock temporal despues de N intentos fallidos
- Registro de todas las actividades para auditoria
- Soporte para multiples credenciales por dispositivo

87
src/modules/feature-flags/README.md Normal file
View File

@ -0,0 +1,87 @@
# Feature Flags Module
## Descripcion
Sistema de feature flags/toggles para control de funcionalidades. Permite habilitar/deshabilitar features globalmente o por tenant, con soporte para rollout gradual basado en porcentajes y overrides temporales con expiracion.
## Entidades
| Entidad | Schema | Descripcion |
|---------|--------|-------------|
| `Flag` | feature_flags.flags | Definicion de feature flags con estado global y porcentaje de rollout |
| `TenantOverride` | feature_flags.tenant_overrides | Overrides por tenant con razon y fecha de expiracion |
| `FlagEvaluation` | feature_flags.flag_evaluations | Log de evaluaciones para auditoria |
## Servicios
| Servicio | Responsabilidades |
|----------|-------------------|
| `FeatureFlagsService` | CRUD de flags y overrides; evaluacion de flags; rollout deterministico; limpieza de expirados |
## Endpoints
| Method | Path | Descripcion |
|--------|------|-------------|
| GET | `/flags` | Lista flags activos |
| GET | `/flags/all` | Lista todos los flags (incluyendo inactivos) |
| GET | `/flags/tags/:tags` | Lista flags por tags |
| GET | `/flags/:id` | Obtiene flag por ID |
| GET | `/flags/code/:code` | Obtiene flag por codigo |
| POST | `/flags` | Crea nuevo flag |
| PATCH | `/flags/:id` | Actualiza flag |
| DELETE | `/flags/:id` | Elimina flag (soft/hard) |
| PATCH | `/flags/:id/toggle` | Activa/desactiva flag |
| GET | `/flags/:id/stats` | Estadisticas de overrides del flag |
| GET | `/flags/:flagId/overrides` | Lista overrides de un flag |
| GET | `/tenants/:tenantId/overrides` | Lista overrides de un tenant |
| GET | `/overrides/:id` | Obtiene override por ID |
| POST | `/overrides` | Crea override |
| PATCH | `/overrides/:id` | Actualiza override |
| DELETE | `/overrides/:id` | Elimina override |
| GET | `/evaluate/:code` | Evalua un flag para tenant |
| POST | `/evaluate` | Evalua multiples flags |
| GET | `/is-enabled/:code` | Check rapido de flag habilitado |
| POST | `/maintenance/cleanup` | Limpia overrides expirados |
## Dependencias
- `common` - Utilidades compartidas (crypto para hash)
## Configuracion
No requiere configuracion de ambiente.
## Prioridad de Evaluacion
1. **Tenant Override** (si existe y no ha expirado)
2. **Estado Global** del flag (enabled/disabled)
3. **Rollout Percentage** (si el flag esta habilitado)
4. **Default** (false si el flag no existe)
## Rollout Deterministico
El rollout por porcentaje usa un hash MD5 de `flagCode:tenantId` para asegurar que:
- El mismo tenant siempre obtiene el mismo resultado
- La distribucion es uniforme entre tenants
- No hay necesidad de almacenar el resultado
```typescript
// Ejemplo: 30% rollout
// Tenants con bucket 0-29 = habilitado
// Tenants con bucket 30-99 = deshabilitado
bucket = MD5(flagCode + tenantId) % 100
enabled = bucket < rolloutPercentage
```
## Fuentes de Evaluacion
| Fuente | Descripcion |
|--------|-------------|
| `default` | Flag no existe, retorna false |
| `global` | Valor global del flag |
| `override` | Override especifico del tenant |
| `rollout` | Resultado del calculo de rollout |
## Mantenimiento
Se recomienda ejecutar `POST /maintenance/cleanup` periodicamente (cron diario) para eliminar overrides expirados.

63
src/modules/geolocation/README.md Normal file
View File

@ -0,0 +1,63 @@
# Geolocation Module
## Descripcion
Servicios de geolocalizacion para el ERP. Este modulo esta planeado para proporcionar funcionalidades de tracking de ubicacion, geocodificacion, geofencing y calculo de rutas/distancias.
## Estado
**Pendiente de Implementacion**
Este modulo aun no ha sido desarrollado. Las entidades y servicios descritos a continuacion representan la funcionalidad planificada.
## Entidades Planificadas
| Entidad | Schema | Descripcion |
|---------|--------|-------------|
| `GeoLocation` | geo.locations | Ubicaciones registradas con coordenadas y metadata |
| `GeoFence` | geo.fences | Zonas geograficas definidas (poligonos/circulos) |
| `GeoTrack` | geo.tracks | Historial de ubicaciones de dispositivos/usuarios |
| `GeoAddress` | geo.addresses | Direcciones geocodificadas con componentes |
## Funcionalidades Planificadas
### Tracking de Ubicacion
- Registro de ubicaciones de dispositivos moviles
- Historial de movimientos
- Ubicacion en tiempo real
### Geocodificacion
- Conversion de direcciones a coordenadas (forward)
- Conversion de coordenadas a direcciones (reverse)
- Autocompletado de direcciones
### Geofencing
- Definicion de zonas geograficas
- Alertas de entrada/salida de zonas
- Validacion de ubicacion dentro de area
### Rutas y Distancias
- Calculo de distancias entre puntos
- Optimizacion de rutas de entrega
- Tiempo estimado de llegada
## Dependencias Planificadas
- `auth` - Contexto de usuario/dispositivo
- `biometrics` - Integracion con ubicacion de dispositivos
- Google Maps API o similar (proveedor externo)
## Configuracion Requerida
| Variable | Descripcion |
|----------|-------------|
| `MAPS_API_KEY` | API key del proveedor de mapas |
| `MAPS_PROVIDER` | Proveedor: google, mapbox, here |
## Casos de Uso
1. **Delivery tracking** - Seguimiento de entregas en tiempo real
2. **Check-in de empleados** - Verificacion de ubicacion en punto de venta
3. **Zonas de servicio** - Validar si una direccion esta en area de cobertura
4. **Optimizacion de rutas** - Planificacion de rutas de entrega
5. **Geocercas de sucursales** - Alertas cuando empleados entran/salen

72
src/modules/mcp/README.md Normal file
View File

@ -0,0 +1,72 @@
# MCP Module
## Descripcion
Implementacion del Model Context Protocol (MCP) Server para el ERP. Expone herramientas (tools) y recursos que pueden ser invocados por agentes de IA para realizar operaciones en el sistema. Incluye registro de tools, control de permisos, logging de llamadas y auditorias.
## Entidades
| Entidad | Schema | Descripcion |
|---------|--------|-------------|
| `ToolCall` | ai.tool_calls | Registro de invocaciones de tools con parametros, estado y duracion |
| `ToolCallResult` | ai.tool_call_results | Resultados de las invocaciones incluyendo respuesta o error |
## Servicios
| Servicio | Responsabilidades |
|----------|-------------------|
| `McpServerService` | Servidor MCP principal: listado de tools, ejecucion con logging, acceso a recursos |
| `ToolRegistryService` | Registro central de tools y handlers disponibles por categoria |
| `ToolLoggerService` | Logging de llamadas a tools: inicio, completado, fallido, historial |
## Tool Providers
| Provider | Tools | Descripcion |
|----------|-------|-------------|
| `ProductsToolsService` | list_products, get_product_details, check_product_availability | Operaciones de productos |
| `InventoryToolsService` | check_stock, get_low_stock, reserve_stock | Operaciones de inventario |
| `OrdersToolsService` | create_order, get_order_status, list_orders | Operaciones de ordenes |
| `CustomersToolsService` | search_customers, get_customer_info | Operaciones de clientes |
| `FiadosToolsService` | get_fiado_balance, register_fiado_payment | Operaciones de fiados |
| `SalesToolsService` | get_sales_summary, get_daily_report | Reportes de ventas |
| `FinancialToolsService` | get_cash_balance, get_revenue | Operaciones financieras |
| `BranchToolsService` | list_branches, get_branch_info | Operaciones de sucursales |
## Endpoints
| Method | Path | Descripcion |
|--------|------|-------------|
| GET | `/tools` | Lista todas las tools disponibles |
| GET | `/tools/:name` | Obtiene definicion de una tool |
| POST | `/tools/call` | Ejecuta una tool con parametros |
| GET | `/resources` | Lista recursos MCP disponibles |
| GET | `/resources/*` | Obtiene contenido de un recurso |
| GET | `/tool-calls` | Historial de llamadas a tools |
| GET | `/tool-calls/:id` | Detalles de una llamada |
| GET | `/stats` | Estadisticas de uso de tools |
## Dependencias
- `ai` - Entidades de logging en schema ai
- `auth` - Contexto de usuario y permisos
## Configuracion
No requiere configuracion adicional. Los tools se registran programaticamente.
## Recursos MCP
| URI | Descripcion |
|-----|-------------|
| `erp://config/business` | Configuracion del negocio |
| `erp://catalog/categories` | Catalogo de categorias de productos |
| `erp://inventory/summary` | Resumen de inventario actual |
## Categorias de Tools
- `products` - Gestion de productos
- `inventory` - Control de inventario
- `orders` - Gestion de ordenes
- `customers` - Clientes y contactos
- `fiados` - Creditos y fiados
- `system` - Operaciones del sistema

90
src/modules/storage/README.md Normal file
View File

@ -0,0 +1,90 @@
# Storage Module
## Descripcion
Sistema de almacenamiento de archivos con soporte multi-proveedor (S3, GCS, Azure, local). Gestiona buckets, carpetas jerarquicas, archivos con versionado, thumbnails, y tokens de acceso temporal. Incluye cuotas por tenant y busqueda de archivos.
## Entidades
| Entidad | Schema | Descripcion |
|---------|--------|-------------|
| `StorageBucket` | storage.buckets | Contenedores de almacenamiento con configuracion de proveedor y limites |
| `StorageFolder` | storage.folders | Carpetas jerarquicas dentro de buckets |
| `StorageFile` | storage.files | Archivos con metadata, checksums, thumbnails y versionado |
| `StorageUpload` | storage.uploads | Uploads en progreso (multipart) |
| `FileAccessToken` | storage.file_access_tokens | Tokens temporales para acceso a archivos |
| `FileShare` | storage.file_shares | Archivos compartidos con enlaces publicos |
| `TenantUsage` | storage.tenant_usage | Estadisticas de uso de almacenamiento por tenant |
## Servicios
| Servicio | Responsabilidades |
|----------|-------------------|
| `StorageService` | CRUD de buckets, folders y files; busqueda; estadisticas de uso; versionado |
## Endpoints
| Method | Path | Descripcion |
|--------|------|-------------|
| GET | `/buckets` | Lista buckets disponibles |
| GET | `/buckets/:id` | Obtiene bucket por ID |
| POST | `/buckets` | Crea nuevo bucket |
| PATCH | `/buckets/:id` | Actualiza bucket |
| DELETE | `/buckets/:id` | Elimina bucket (debe estar vacio) |
| GET | `/buckets/:bucketId/folders` | Lista carpetas en bucket |
| GET | `/folders/:id` | Obtiene carpeta por ID |
| POST | `/folders` | Crea carpeta |
| PATCH | `/folders/:id` | Actualiza carpeta |
| DELETE | `/folders/:id` | Elimina carpeta (opcional recursivo) |
| GET | `/buckets/:bucketId/files` | Lista archivos en bucket/carpeta |
| GET | `/files/:id` | Obtiene archivo por ID |
| GET | `/files/key/:storageKey` | Obtiene archivo por storage key |
| POST | `/files` | Registra archivo subido |
| PATCH | `/files/:id` | Actualiza metadata de archivo |
| DELETE | `/files/:id` | Elimina archivo |
| POST | `/files/:id/download` | Registra descarga (incrementa contador) |
| GET | `/search` | Busca archivos por nombre/descripcion |
| GET | `/usage` | Obtiene uso de almacenamiento del tenant |
| GET | `/recent` | Lista archivos recientes |
## Dependencias
- `common` - Utilidades compartidas
- `auth` - Contexto de tenant
- Proveedor de storage (S3/GCS/Azure/local)
## Configuracion
La configuracion del proveedor se almacena en cada bucket (`storageConfig`).
| Proveedor | Configuracion Requerida |
|-----------|------------------------|
| `local` | basePath |
| `s3` | region, bucket, accessKeyId, secretAccessKey |
| `gcs` | projectId, bucket, keyFile |
| `azure` | accountName, accountKey, containerName |
## Tipos de Bucket
| Tipo | Descripcion |
|------|-------------|
| `public` | Archivos accesibles sin autenticacion |
| `private` | Requiere autenticacion para acceso |
| `protected` | Acceso via tokens temporales |
## Categorias de Archivo
- `image` - Imagenes (jpg, png, gif, etc.)
- `document` - Documentos (pdf, doc, xls, etc.)
- `video` - Videos
- `audio` - Archivos de audio
- `archive` - Archivos comprimidos
- `other` - Otros tipos
## Versionado
Cuando esta habilitado en el bucket:
- Cada actualizacion crea una nueva version
- Se mantiene referencia al `parentVersionId`
- Solo la ultima version tiene `isLatest = true`
- Limite configurable de versiones por archivo

79
src/modules/webhooks/README.md Normal file
View File

@ -0,0 +1,79 @@
# Webhooks Module
## Descripcion
Sistema de webhooks outbound para notificar eventos del ERP a sistemas externos. Permite registrar endpoints, suscribirse a tipos de eventos, y gestiona la entrega con reintentos automaticos, firma de payloads y monitoreo de salud de endpoints.
## Entidades
| Entidad | Schema | Descripcion |
|---------|--------|-------------|
| `WebhookEventType` | webhooks.event_types | Catalogo de tipos de eventos disponibles (order.created, inventory.low_stock, etc.) |
| `WebhookEndpoint` | webhooks.endpoints | Endpoints registrados con URL, autenticacion, reintentos y filtros |
| `WebhookSubscription` | webhooks.subscriptions | Suscripciones de endpoints a tipos de eventos especificos |
| `WebhookEvent` | webhooks.events | Eventos generados pendientes de despacho |
| `WebhookDelivery` | webhooks.deliveries | Intentos de entrega con request/response y estado |
| `EndpointLog` | webhooks.endpoint_log | Log de actividad por endpoint |
## Servicios
| Servicio | Responsabilidades |
|----------|-------------------|
| `WebhooksService` | CRUD de event types, endpoints, eventos y deliveries; busqueda de endpoints por evento; estadisticas |
## Endpoints
| Method | Path | Descripcion |
|--------|------|-------------|
| GET | `/event-types` | Lista tipos de eventos disponibles |
| GET | `/event-types/:code` | Obtiene tipo de evento por codigo |
| GET | `/event-types/category/:category` | Lista tipos por categoria |
| GET | `/endpoints` | Lista endpoints del tenant |
| GET | `/endpoints/active` | Lista endpoints activos |
| GET | `/endpoints/:id` | Obtiene endpoint por ID |
| POST | `/endpoints` | Registra nuevo endpoint |
| PATCH | `/endpoints/:id` | Actualiza endpoint |
| DELETE | `/endpoints/:id` | Elimina endpoint |
| PATCH | `/endpoints/:id/toggle` | Activa/desactiva endpoint |
| GET | `/endpoints/:id/stats` | Estadisticas de entrega del endpoint |
| GET | `/endpoints/:id/deliveries` | Historial de entregas del endpoint |
| POST | `/events` | Crea nuevo evento para despacho |
| GET | `/events/:id` | Obtiene evento con deliveries |
| GET | `/events/pending` | Lista eventos pendientes |
| GET | `/deliveries/:id` | Obtiene detalles de delivery |
| GET | `/events/:eventId/deliveries` | Lista deliveries de un evento |
## Dependencias
- `common` - Utilidades compartidas
- `auth` - Contexto de tenant
## Configuracion
No requiere configuracion de ambiente. La configuracion de autenticacion es por endpoint.
## Tipos de Autenticacion Soportados
| Tipo | Descripcion |
|------|-------------|
| `none` | Sin autenticacion |
| `basic` | HTTP Basic Auth |
| `bearer` | Bearer token |
| `hmac` | HMAC signature en header |
| `oauth2` | OAuth 2.0 client credentials |
## Categorias de Eventos
- `sales` - Eventos de ventas y ordenes
- `inventory` - Eventos de inventario
- `customers` - Eventos de clientes
- `auth` - Eventos de autenticacion
- `billing` - Eventos de facturacion
- `system` - Eventos del sistema
## Politica de Reintentos
- Reintentos configurables por endpoint (default: 5)
- Delay inicial configurable (default: 60 segundos)
- Backoff exponencial con multiplicador configurable (default: 2.0)
- Rate limiting por minuto y hora

95
src/modules/whatsapp/README.md Normal file
View File

@ -0,0 +1,95 @@
# WhatsApp Module
## Descripcion
Integracion con WhatsApp Business API para comunicacion con clientes. Soporta envio y recepcion de mensajes de texto, multimedia y templates; gestion de contactos con opt-in/opt-out; automatizaciones; broadcasts masivos; y respuestas rapidas.
## Entidades
| Entidad | Schema | Descripcion |
|---------|--------|-------------|
| `WhatsAppAccount` | whatsapp.accounts | Cuentas de WhatsApp Business configuradas por tenant |
| `WhatsAppContact` | whatsapp.contacts | Contactos de WhatsApp con estado de conversacion y opt-in |
| `WhatsAppConversation` | whatsapp.conversations | Hilos de conversacion con ventana de 24h |
| `WhatsAppMessage` | whatsapp.messages | Mensajes enviados/recibidos con estado de entrega |
| `WhatsAppTemplate` | whatsapp.templates | Templates de mensajes aprobados por Meta |
| `WhatsAppQuickReply` | whatsapp.quick_replies | Respuestas rapidas predefinidas |
| `WhatsAppAutomation` | whatsapp.automations | Reglas de automatizacion de respuestas |
| `WhatsAppBroadcast` | whatsapp.broadcasts | Campanas de mensajes masivos |
| `WhatsAppBroadcastRecipient` | whatsapp.broadcast_recipients | Destinatarios de broadcasts |
| `MessageStatusUpdate` | whatsapp.message_status_updates | Historial de cambios de estado |
## Servicios
| Servicio | Responsabilidades |
|----------|-------------------|
| `WhatsAppService` | Gestion completa: cuentas, contactos, mensajes, templates; estadisticas; ventanas de conversacion |
## Endpoints
| Method | Path | Descripcion |
|--------|------|-------------|
| GET | `/accounts` | Lista cuentas del tenant |
| GET | `/accounts/active` | Lista cuentas activas |
| GET | `/accounts/:id` | Obtiene cuenta por ID |
| POST | `/accounts` | Registra nueva cuenta |
| PATCH | `/accounts/:id` | Actualiza cuenta |
| PATCH | `/accounts/:id/status` | Cambia estado de cuenta |
| GET | `/accounts/:id/stats` | Estadisticas de la cuenta |
| GET | `/accounts/:accountId/contacts` | Lista contactos de cuenta |
| GET | `/contacts/:id` | Obtiene contacto por ID |
| GET | `/accounts/:accountId/contacts/phone/:phoneNumber` | Busca contacto por telefono |
| POST | `/contacts` | Crea contacto |
| PATCH | `/contacts/:id` | Actualiza contacto |
| POST | `/contacts/:id/opt-in` | Registra opt-in |
| POST | `/contacts/:id/opt-out` | Registra opt-out |
| POST | `/contacts/:id/tags` | Agrega tag a contacto |
| DELETE | `/contacts/:id/tags/:tag` | Elimina tag de contacto |
| GET | `/accounts/:accountId/messages` | Lista mensajes de cuenta |
| GET | `/messages/:id` | Obtiene mensaje por ID |
| GET | `/contacts/:contactId/messages` | Historial de conversacion |
| POST | `/messages` | Envia mensaje |
| PATCH | `/messages/:id/status` | Actualiza estado de mensaje |
| GET | `/accounts/:accountId/templates` | Lista templates de cuenta |
| GET | `/accounts/:accountId/templates/approved` | Lista templates aprobados |
| GET | `/templates/:id` | Obtiene template por ID |
| POST | `/templates` | Crea template |
| PATCH | `/templates/:id` | Actualiza template |
| PATCH | `/templates/:id/status` | Actualiza estado de Meta |
| DELETE | `/templates/:id` | Desactiva template |
## Dependencias
- `common` - Utilidades compartidas
- `auth` - Contexto de tenant
- WhatsApp Business API (Meta)
## Configuracion
| Variable | Descripcion | Requerida |
|----------|-------------|-----------|
| Almacenado por cuenta | Access Token, Phone Number ID, Business Account ID | Si |
## Tipos de Mensaje
- `text` - Mensaje de texto
- `image` - Imagen con caption opcional
- `video` - Video
- `audio` - Audio/nota de voz
- `document` - Documento adjunto
- `sticker` - Sticker
- `location` - Ubicacion
- `contacts` - Tarjeta de contacto
- `interactive` - Botones y listas
- `template` - Template pre-aprobado
- `reaction` - Reaccion a mensaje
## Categorias de Templates
- `MARKETING` - Promociones y ofertas
- `UTILITY` - Notificaciones transaccionales
- `AUTHENTICATION` - Codigos de verificacion
## Ventana de Conversacion
WhatsApp permite enviar mensajes de texto libre solo dentro de una ventana de 24 horas despues del ultimo mensaje del cliente. Fuera de esta ventana, solo se pueden enviar templates aprobados.