From 27b4e7bccfb0b7ab25a94e635c7f46e97947b807 Mon Sep 17 00:00:00 2001 From: rckrdmrd Date: Fri, 16 Jan 2026 00:28:18 -0600 Subject: [PATCH] [DOCS] feat: Add phase 04-SAAS and 05-IA documentation structure - Update docs/_MAP.md with new phase references - Add docs/04-fase-saas/ phase structure - Add docs/05-fase-ia/ phase structure Co-Authored-By: Claude Opus 4.5 --- docs/04-fase-saas/MGN-016-billing/README.md | 232 +++++++++++ docs/04-fase-saas/MGN-016-billing/_MAP.md | 112 ++++++ docs/04-fase-saas/MGN-017-plans/README.md | 173 +++++++++ docs/04-fase-saas/MGN-017-plans/_MAP.md | 101 +++++ docs/04-fase-saas/MGN-018-webhooks/README.md | 198 ++++++++++ docs/04-fase-saas/MGN-018-webhooks/_MAP.md | 82 ++++ .../MGN-019-feature-flags/README.md | 176 +++++++++ .../MGN-019-feature-flags/_MAP.md | 91 +++++ docs/04-fase-saas/README.md | 104 +++++ docs/04-fase-saas/_MAP.md | 101 +++++ .../MGN-020-ai-integration/README.md | 210 ++++++++++ .../05-fase-ia/MGN-020-ai-integration/_MAP.md | 95 +++++ .../MGN-021-whatsapp-business/README.md | 363 ++++++++++++++++++ .../MGN-021-whatsapp-business/_MAP.md | 126 ++++++ docs/05-fase-ia/MGN-022-mcp-server/README.md | 316 +++++++++++++++ docs/05-fase-ia/MGN-022-mcp-server/_MAP.md | 167 ++++++++ docs/05-fase-ia/README.md | 172 +++++++++ docs/05-fase-ia/_MAP.md | 115 ++++++ docs/_MAP.md | 127 ++++-- 19 files changed, 3036 insertions(+), 25 deletions(-) create mode 100644 docs/04-fase-saas/MGN-016-billing/README.md create mode 100644 docs/04-fase-saas/MGN-016-billing/_MAP.md create mode 100644 docs/04-fase-saas/MGN-017-plans/README.md create mode 100644 docs/04-fase-saas/MGN-017-plans/_MAP.md create mode 100644 docs/04-fase-saas/MGN-018-webhooks/README.md create mode 100644 docs/04-fase-saas/MGN-018-webhooks/_MAP.md create mode 100644 docs/04-fase-saas/MGN-019-feature-flags/README.md create mode 100644 docs/04-fase-saas/MGN-019-feature-flags/_MAP.md create mode 100644 docs/04-fase-saas/README.md create mode 100644 docs/04-fase-saas/_MAP.md create mode 100644 docs/05-fase-ia/MGN-020-ai-integration/README.md create mode 100644 docs/05-fase-ia/MGN-020-ai-integration/_MAP.md create mode 100644 docs/05-fase-ia/MGN-021-whatsapp-business/README.md create mode 100644 docs/05-fase-ia/MGN-021-whatsapp-business/_MAP.md create mode 100644 docs/05-fase-ia/MGN-022-mcp-server/README.md create mode 100644 docs/05-fase-ia/MGN-022-mcp-server/_MAP.md create mode 100644 docs/05-fase-ia/README.md create mode 100644 docs/05-fase-ia/_MAP.md diff --git a/docs/04-fase-saas/MGN-016-billing/README.md b/docs/04-fase-saas/MGN-016-billing/README.md new file mode 100644 index 0000000..b527eb9 --- /dev/null +++ b/docs/04-fase-saas/MGN-016-billing/README.md @@ -0,0 +1,232 @@ +--- +id: MGN-016-billing +title: Modulo Billing - Suscripciones para Clinica Dental +type: ModuleOverview +status: Draft +version: 1.0.0 +created_date: 2026-01-13 +updated_date: 2026-01-13 +module: billing +priority: P0 +normativas: [NOM-013-SSA2-2015, CFDI-4.0] +--- + +# MGN-016: Billing - Sistema de Facturacion y Suscripciones Dentales + +## Resumen Ejecutivo + +El modulo Billing implementa el sistema de facturacion y suscripciones para consultorios y clinicas dentales, integrando Stripe Billing como proveedor de pagos. Permite gestionar suscripciones por tipo de consultorio (individual, grupal, centro dental), periodos de prueba, upgrades/downgrades y facturacion automatica con soporte para CFDI 4.0. + +--- + +## Objetivos + +### Objetivo Principal + +Implementar un sistema de billing completo para clinicas dentales que permita: +- Suscripciones mensuales y anuales por tipo de consultorio +- Planes diferenciados por numero de sillones dentales +- Facturacion automatica recurrente con CFDI 4.0 +- Portal de cliente self-service via Stripe + +### Objetivos Secundarios + +- Sincronizacion bidireccional con Stripe via webhooks +- Soporte para periodos de prueba (14 dias) +- Manejo de pagos fallidos y dunning +- Historial de facturas accesible para clinicas +- Facturacion adicional por servicios especiales + +--- + +## Planes para Clinica Dental + +| Plan | Precio/mes | Sillones | Usuarios | Storage | Features | +|------|------------|----------|----------|---------|----------| +| **Consultorio** | $499 MXN | 1 | 3 | 5 GB | Odontograma, Citas, Expedientes | +| **Clinica** | $1,499 MXN | 5 | 15 | 25 GB | + Ortodoncia, Radiografias, Reportes | +| **Centro Dental** | $3,999 MXN | Ilimitado | Ilimitado | 100 GB | + IA, WhatsApp, Multi-sucursal | + +--- + +## Alcance + +### Incluido (In Scope) + +| Caracteristica | Descripcion | Prioridad | +|----------------|-------------|-----------| +| Stripe Billing | Integracion completa con Stripe | P0 | +| Planes dentales | Consultorio, Clinica, Centro | P0 | +| Suscripciones | Crear, actualizar, cancelar | P0 | +| Webhooks Stripe | Recibir y procesar eventos | P0 | +| Portal cliente | Redirect a Stripe Customer Portal | P0 | +| CFDI 4.0 | Generacion de facturas fiscales | P0 | +| Pagos OXXO | Soporte para pago en efectivo | P1 | +| Invoices | Historial con PDF | P1 | + +### Excluido (Out of Scope) + +| Caracteristica | Razon | Fase Futura | +|----------------|-------|-------------| +| Multi-currency | Solo MXN por ahora | Fase 2 | +| Servicios adicionales | Pagos one-time | Fase 2 | +| Facturacion por tratamiento | Complejidad | Fase 3 | + +--- + +## Arquitectura + +### Diagrama de Integracion + +``` ++-------------------+ +-------------------+ +-------------------+ +| Frontend |---->| Billing API |---->| Stripe API | +| (Checkout) | | (NestJS) | | | ++-------------------+ +-------------------+ +-------------------+ + | | + +-------+---------+ | + | | v + +----------+ +-----------+ +-------------+ + | Plans DB | | Invoices | | Webhooks | + | (Dental) | | + CFDI | | (events) | + +----------+ +-----------+ +-------------+ + | + v + +-----------+ + | SAT/CFDI | + | Timbrado | + +-----------+ +``` + +### Flujo de Suscripcion Dental + +``` +1. Dentista selecciona plan en frontend + | +2. Frontend llama POST /billing/checkout + | +3. Backend crea Checkout Session en Stripe + | +4. Backend retorna URL de Stripe Checkout + | +5. Frontend redirige a Stripe Checkout + | +6. Dentista paga (tarjeta o OXXO) + | +7. Stripe envia webhook: checkout.session.completed + | +8. Backend crea/actualiza subscription en DB + | +9. Backend activa features del plan (sillones, odontograma, etc.) + | +10. Clinica operativa con funcionalidades activas +``` + +--- + +## Facturacion CFDI 4.0 + +### Datos Requeridos + +- RFC de la clinica +- Razon social +- Regimen fiscal +- Uso CFDI (G03 - Gastos en general) +- Codigo postal fiscal + +### Flujo de Facturacion + +``` +1. Stripe cobra suscripcion + | +2. Webhook notifica pago exitoso + | +3. Backend genera pre-CFDI + | +4. Envia a PAC para timbrado + | +5. Almacena XML y PDF + | +6. Notifica a clinica via email +``` + +--- + +## Dependencias + +### Modulos Prerequisito + +| Modulo | Tipo | Descripcion | +|--------|------|-------------| +| MGN-001-auth | Requerido | Autenticacion JWT | +| MGN-002-users | Requerido | Usuario owner clinica | +| MGN-004-tenants | Requerido | Contexto multi-tenant | +| MGN-007-audit | Requerido | Logs de cambios | + +### Servicios Externos + +| Servicio | Proposito | Requerido | +|----------|-----------|-----------| +| Stripe | Billing y pagos | Si | +| PAC CFDI | Timbrado facturas | Si | +| Redis | Cache de planes | Opcional | + +--- + +## Seguridad y Normativas + +| Medida | Implementacion | +|--------|----------------| +| PCI Compliance | No almacenar datos de tarjeta | +| Webhook Signature | Verificar Stripe-Signature | +| CFDI Seguro | Almacenar XMLs firmados | +| Access Control | Solo owner gestiona billing | +| NOM-013-SSA2-2015 | Registro de servicios | +| LFPDPPP | Proteccion datos clinica | + +--- + +## Configuracion + +### Variables de Entorno + +```bash +# Stripe +STRIPE_SECRET_KEY=sk_live_xxx +STRIPE_PUBLISHABLE_KEY=pk_live_xxx +STRIPE_WEBHOOK_SECRET=whsec_xxx + +# Billing Config Dental +BILLING_TRIAL_DAYS=14 +BILLING_DEFAULT_PLAN=consultorio +BILLING_SUCCESS_URL=https://clinica.ejemplo.com/billing/success +BILLING_CANCEL_URL=https://clinica.ejemplo.com/billing/cancel + +# CFDI +CFDI_PAC_URL=https://pac.ejemplo.com +CFDI_PAC_USER=xxx +CFDI_PAC_PASSWORD=xxx +``` + +--- + +## Indices + +- [Requerimientos Funcionales](requerimientos/INDICE-RF-BILLING.md) +- [Especificaciones Tecnicas](especificaciones/INDICE-ET-BILLING.md) +- [Historias de Usuario](historias-usuario/INDICE-US-BILLING.md) +- [Trazabilidad](implementacion/TRACEABILITY.yml) + +--- + +## Referencias + +- [erp-core/MGN-016-billing](../../../../../erp-core/docs/04-fase-saas/MGN-016-billing/) - Origen +- [Stripe Billing Docs](https://stripe.com/docs/billing) - Documentacion oficial +- [SAT CFDI 4.0](https://www.sat.gob.mx/consultas/42214/cfdi-version-4.0) - Especificacion + +--- + +*Modulo: MGN-016-billing | Clinica Dental | Version: 1.0.0* +*Propagado desde erp-core via erp-clinicas* +*Actualizado: 2026-01-13* diff --git a/docs/04-fase-saas/MGN-016-billing/_MAP.md b/docs/04-fase-saas/MGN-016-billing/_MAP.md new file mode 100644 index 0000000..0cf8a68 --- /dev/null +++ b/docs/04-fase-saas/MGN-016-billing/_MAP.md @@ -0,0 +1,112 @@ +--- +id: MAP-MGN-016-billing +title: Mapa de Navegacion - Modulo Billing +type: NavigationMap +status: Draft +version: 1.0.0 +created_date: 2026-01-13 +updated_date: 2026-01-13 +--- + +# Mapa de Navegacion - MGN-016: Billing Dental + +## Estructura del Modulo + +``` +MGN-016-billing/ ++-- README.md <- Vision general del modulo ++-- _MAP.md <- ESTE ARCHIVO +| ++-- requerimientos/ <- Requerimientos funcionales +| +-- INDICE-RF-BILLING.md <- Indice de RFs +| +-- RF-BILLING-001.md <- Suscripciones dentales +| +-- RF-BILLING-002.md <- Webhooks de Stripe +| +-- RF-BILLING-003.md <- Portal cliente +| +-- RF-BILLING-004.md <- Facturacion CFDI 4.0 +| ++-- especificaciones/ <- Especificaciones tecnicas +| +-- INDICE-ET-BILLING.md <- Indice de ETs +| +-- ET-BILLING-DATABASE.md <- Modelo de datos SQL +| +-- ET-BILLING-BACKEND.md <- API endpoints y servicios +| +-- ET-BILLING-FRONTEND.md <- Componentes UI +| ++-- historias-usuario/ <- User stories +| +-- INDICE-US-BILLING.md <- Indice de USs +| ++-- implementacion/ <- Artefactos de implementacion + +-- TRACEABILITY.yml <- Matriz de trazabilidad +``` + +--- + +## Indice de Documentos + +### Vision General + +| Documento | Descripcion | Estado | +|-----------|-------------|--------| +| [README.md](README.md) | Vision general del modulo Billing Dental | Draft | + +### Requerimientos Funcionales + +| ID | Documento | Descripcion | Estado | +|----|-----------|-------------|--------| +| RF-BILLING-001 | Suscripciones | Planes: Consultorio, Clinica, Centro | Draft | +| RF-BILLING-002 | Webhooks | Procesamiento de webhooks Stripe | Draft | +| RF-BILLING-003 | Portal | Portal de cliente Stripe | Draft | +| RF-BILLING-004 | CFDI | Facturacion CFDI 4.0 | Draft | + +### Especificaciones Tecnicas + +| ID | Documento | Descripcion | Estado | +|----|-----------|-------------|--------| +| ET-BILLING-DATABASE | Database | Modelo de datos (plans, subscriptions) | Draft | +| ET-BILLING-BACKEND | Backend | API endpoints NestJS | Draft | +| ET-BILLING-FRONTEND | Frontend | Componentes React | Draft | + +--- + +## Planes Dentales + +| Plan | Precio | Sillones | Features | +|------|--------|----------|----------| +| Consultorio | $499/mes | 1 | Basico | +| Clinica | $1,499/mes | 5 | + Ortodoncia, Radiografias | +| Centro Dental | $3,999/mes | Ilimitado | + IA, WhatsApp | + +--- + +## Flujo de Navegacion Recomendado + +### Para Entender el Modulo + +``` +1. README.md -> Vision general y planes +2. RF-BILLING-001.md -> Suscripciones dentales +3. ET-BILLING-DATABASE.md -> Modelo de datos +4. ET-BILLING-BACKEND.md -> API y servicios +``` + +### Para Implementar + +``` +1. ET-BILLING-DATABASE.md -> Crear schema billing +2. ET-BILLING-BACKEND.md -> Implementar servicios Stripe +3. ET-BILLING-FRONTEND.md -> Crear UI de suscripcion +4. TRACEABILITY.yml -> Verificar completitud +``` + +--- + +## Referencias Externas + +| Recurso | URL | +|---------|-----| +| Stripe Billing | https://stripe.com/docs/billing | +| Stripe Webhooks | https://stripe.com/docs/webhooks | +| SAT CFDI 4.0 | https://www.sat.gob.mx/consultas/42214/cfdi-version-4.0 | + +--- + +*Mapa de Navegacion | MGN-016-billing | Clinica Dental* +*Actualizado: 2026-01-13* diff --git a/docs/04-fase-saas/MGN-017-plans/README.md b/docs/04-fase-saas/MGN-017-plans/README.md new file mode 100644 index 0000000..04811b8 --- /dev/null +++ b/docs/04-fase-saas/MGN-017-plans/README.md @@ -0,0 +1,173 @@ +--- +id: MGN-017-plans +title: Modulo Plans - Planes y Feature Gating para Clinica Dental +type: Module +status: Draft +version: 1.0.0 +created_date: 2026-01-13 +updated_date: 2026-01-13 +source: erp-core/MGN-017-plans +normativas: [NOM-013-SSA2-2015] +--- + +# MGN-017: Modulo Plans - Planes y Feature Gating Dental + +## Descripcion + +El modulo **Plans** gestiona la definicion de planes de suscripcion para clinicas dentales, feature gating por plan, y enforcement de limites y cuotas por consultorio. Controla acceso a funcionalidades especializadas como odontograma digital, radiografias, ortodoncia 3D y herramientas de IA. + +## Objetivos + +1. **Definicion de Planes Dentales** - Planes diferenciados por tipo de consultorio +2. **Feature Gating Odontologico** - Control de acceso a funcionalidades dentales +3. **Limites por Sillon** - Enforcar limites por numero de sillones +4. **Usage Tracking** - Monitorear uso de funcionalidades +5. **Upgrade/Downgrade** - Flujos para cambio de plan + +## Planes para Clinica Dental + +| Plan | Precio/mes | Sillones | Usuarios | Storage | Pacientes/mes | +|------|------------|----------|----------|---------|---------------| +| **Consultorio** | $499 MXN | 1 | 3 | 5 GB | 100 | +| **Clinica** | $1,499 MXN | 5 | 15 | 25 GB | 500 | +| **Centro Dental** | $3,999 MXN | Ilimitado | Ilimitado | 100 GB | Ilimitado | + +## Features por Plan + +| Feature | Consultorio | Clinica | Centro Dental | +|---------|-------------|---------|---------------| +| odontograma_basico | Si | Si | Si | +| odontograma_digital | No | Si | Si | +| radiografias_digitales | No | Si | Si | +| ortodoncia_3d | No | No | Si | +| presupuestos_dentales | Si | Si | Si | +| reportes_basicos | Si | Si | Si | +| reportes_avanzados | No | Si | Si | +| whatsapp_business | No | No | Si | +| asistente_ia | No | No | Si | +| multi_sucursal | No | No | Si | +| api_access | No | Si | Si | +| exportar_datos | Si | Si | Si | +| historial_auditoria | 7 dias | 30 dias | 365 dias | + +## Limites por Plan + +| Limite | Consultorio | Clinica | Centro Dental | +|--------|-------------|---------|---------------| +| Sillones | 1 | 5 | Ilimitado | +| Usuarios | 3 | 15 | Ilimitado | +| Pacientes/mes | 100 | 500 | Ilimitado | +| Storage | 5 GB | 25 GB | 100 GB | +| Radiografias/mes | 50 | 250 | Ilimitado | +| API calls/mes | 0 | 10,000 | Ilimitado | + +## Alcance + +| Caracteristica | Incluido | Notas | +|----------------|----------|-------| +| Plans CRUD | Si | Admin only | +| Limites por sillon | Si | Enforcement estricto | +| Feature flags dentales | Si | Boolean y limites | +| Quota enforcement | Si | Middleware | +| Usage tracking | Si | Snapshots diarios | +| Usage alerts | Si | 80%, 90%, 100% | +| Overage billing | No | Fase posterior | + +## Arquitectura + +### Flujo de Quota Check + +``` +Request (ej: crear_radiografia) + | + v ++-------------------+ +| QuotaMiddleware |-----> Permitido (si dentro de limite) ++-------------------+ + | + v (check) ++-------------------+ +| PlanLimitsService | ++-------------------+ + | + v ++-------------------+ +| Usage Tracking | ++-------------------+ + | + v (excede limite) +QuotaExceededException -> "Limite de radiografias alcanzado" +``` + +### Prioridad de Evaluacion + +1. **Tenant Override** - Maxima prioridad, excepciones manuales +2. **Plan Features** - Features incluidas en plan de la clinica +3. **Global Flag** - Valor default con soporte de rollout + +## Casos de Uso Odontologicos + +### Ejemplo: Verificar Feature Odontograma Digital + +```typescript +// Controller +@Get('odontograma/digital') +@FeatureGuard('odontograma_digital') +async getDigitalOdontograma(@Tenant() tenant: Tenant) { + // Solo accesible para planes Clinica y Centro + return this.odontogramaService.getDigital(tenant.id); +} +``` + +### Ejemplo: Verificar Limite de Radiografias + +```typescript +// Antes de crear radiografia +const canCreate = await this.quotaService.checkLimit( + tenantId, + 'radiografias_mes', + 1 // cantidad a crear +); + +if (!canCreate) { + throw new QuotaExceededException( + 'Limite de radiografias mensuales alcanzado. ' + + 'Actualiza a plan Clinica para mas radiografias.' + ); +} +``` + +## Contenido del Modulo + +- [_MAP.md](./_MAP.md) - Indice del modulo +- [requerimientos/](./requerimientos/) - Requerimientos funcionales +- [especificaciones/](./especificaciones/) - Especificaciones tecnicas +- [historias-usuario/](./historias-usuario/) - User stories +- [implementacion/](./implementacion/) - Trazabilidad + +## Dependencias + +### Modulos Requeridos + +- **MGN-001-tenants** - Gestion de tenants (tenant_id) +- **MGN-016-billing** - Suscripciones y pagos (plan_id) + +### Modulos Dependientes + +- Odontograma (feature gating) +- Radiografias (limites) +- Ortodoncia (feature gating) +- IA (feature gating) +- WhatsApp (feature gating) + +## Referencias + +- **Fuente:** [erp-core/MGN-017-plans](../../../../../erp-core/docs/04-fase-saas/MGN-017-plans/) +- **Billing:** [MGN-016-billing](../MGN-016-billing/) +- **Feature Flags:** [MGN-019-feature-flags](../MGN-019-feature-flags/) + +--- + +*Modulo: MGN-017-plans | Clinica Dental* +*Propagado desde erp-core via erp-clinicas* +*Actualizado: 2026-01-13* diff --git a/docs/04-fase-saas/MGN-017-plans/_MAP.md b/docs/04-fase-saas/MGN-017-plans/_MAP.md new file mode 100644 index 0000000..dfcee31 --- /dev/null +++ b/docs/04-fase-saas/MGN-017-plans/_MAP.md @@ -0,0 +1,101 @@ +--- +id: MAP-MGN-017-plans +title: Mapa de Navegacion - Modulo Plans +type: NavigationMap +status: Draft +version: 1.0.0 +created_date: 2026-01-13 +updated_date: 2026-01-13 +--- + +# Mapa de Navegacion - MGN-017: Plans Dental + +## Estructura del Modulo + +``` +MGN-017-plans/ ++-- README.md <- Vision general del modulo ++-- _MAP.md <- ESTE ARCHIVO +| ++-- requerimientos/ <- Requerimientos funcionales +| +-- INDICE-RF-PLANS.md <- Indice de RFs +| +-- RF-PLANS-001.md <- Definicion de planes dentales +| +-- RF-PLANS-002.md <- Feature gating +| +-- RF-PLANS-003.md <- Limites y cuotas +| ++-- especificaciones/ <- Especificaciones tecnicas +| +-- INDICE-ET-PLANS.md <- Indice de ETs +| +-- ET-PLANS-DATABASE.md <- Modelo de datos +| +-- ET-PLANS-BACKEND.md <- API y servicios +| ++-- historias-usuario/ <- User stories +| +-- INDICE-US-PLANS.md <- Indice de USs +| ++-- implementacion/ <- Artefactos + +-- TRACEABILITY.yml <- Matriz de trazabilidad +``` + +--- + +## Planes Dentales + +| Plan | Precio | Sillones | Features Clave | +|------|--------|----------|----------------| +| Consultorio | $499/mes | 1 | Odontograma basico | +| Clinica | $1,499/mes | 5 | + Radiografias, Ortodoncia | +| Centro Dental | $3,999/mes | Ilimitado | + IA, WhatsApp | + +--- + +## Features por Plan + +| Feature | Consultorio | Clinica | Centro | +|---------|:-----------:|:-------:|:------:| +| odontograma_digital | - | X | X | +| radiografias_digitales | - | X | X | +| ortodoncia_3d | - | - | X | +| asistente_ia | - | - | X | +| whatsapp_business | - | - | X | + +--- + +## Indice de Documentos + +### Requerimientos Funcionales + +| ID | Descripcion | Estado | +|----|-------------|--------| +| RF-PLANS-001 | Planes Consultorio/Clinica/Centro | Draft | +| RF-PLANS-002 | Feature gating odontologico | Draft | +| RF-PLANS-003 | Limites por sillon y pacientes | Draft | + +### Especificaciones Tecnicas + +| ID | Descripcion | Estado | +|----|-------------|--------| +| ET-PLANS-DATABASE | Modelo de datos de planes | Draft | +| ET-PLANS-BACKEND | API y middleware de cuotas | Draft | + +--- + +## Flujo de Navegacion + +### Para Entender + +``` +1. README.md -> Vision y planes +2. RF-PLANS-001.md -> Definicion de planes +3. RF-PLANS-002.md -> Feature gating +``` + +### Para Implementar + +``` +1. ET-PLANS-DATABASE.md -> Schema de planes +2. ET-PLANS-BACKEND.md -> Middleware de cuotas +``` + +--- + +*Mapa | MGN-017-plans | Clinica Dental* +*Actualizado: 2026-01-13* diff --git a/docs/04-fase-saas/MGN-018-webhooks/README.md b/docs/04-fase-saas/MGN-018-webhooks/README.md new file mode 100644 index 0000000..285965c --- /dev/null +++ b/docs/04-fase-saas/MGN-018-webhooks/README.md @@ -0,0 +1,198 @@ +--- +id: MGN-018-webhooks +title: Modulo Webhooks para Clinica Dental +type: Module +status: Draft +version: 1.0.0 +created_date: 2026-01-13 +updated_date: 2026-01-13 +phase: 04-fase-saas +normativas: [NOM-013-SSA2-2015, LFPDPPP] +--- + +# MGN-018: Webhooks Outbound para Clinica Dental + +**Modulo:** MGN-018 +**Nombre:** Webhooks Outbound +**Fase:** 04 - SaaS +**Estado:** Pendiente Documentacion +**Ultima actualizacion:** 2026-01-13 + +--- + +## Descripcion + +Sistema de webhooks outbound para notificar eventos de la clinica dental a sistemas externos. Permite a las clinicas registrar endpoints HTTP para recibir notificaciones automaticas cuando ocurren eventos como agendamiento de citas, finalizacion de tratamientos, actualizacion de odontogramas, pagos de servicios, etc. + +--- + +## Funcionalidades Principales + +1. **Registro de Endpoints** - CRUD de endpoints webhook por clinica +2. **Firma HMAC-SHA256** - Firma criptografica de payloads +3. **Reintentos con Backoff** - Politica de reintentos exponencial +4. **Dead Letter Queue** - Almacenamiento de entregas fallidas +5. **Delivery Logs** - Historial completo de entregas + +--- + +## Eventos Disponibles para Clinica Dental + +| Categoria | Eventos | +|-----------|---------| +| **Citas** | `cita.creada`, `cita.confirmada`, `cita.cancelada`, `cita.completada` | +| **Pacientes** | `paciente.creado`, `paciente.actualizado` | +| **Tratamientos** | `tratamiento.iniciado`, `tratamiento.completado`, `tratamiento.cancelado` | +| **Odontograma** | `odontograma.actualizado`, `pieza.tratada` | +| **Pagos** | `pago.recibido`, `pago.fallido` | +| **Presupuestos** | `presupuesto.creado`, `presupuesto.aprobado`, `presupuesto.rechazado` | + +--- + +## Casos de Uso Odontologicos + +- Sincronizar pacientes con sistema de laboratorio dental +- Notificar a aseguradoras sobre tratamientos completados +- Actualizar sistema contable con pagos recibidos +- Integrar con Slack/Teams para alertas del equipo +- Trigger de recordatorios automaticos en herramientas externas +- Notificar a sistema de rayos X sobre nuevas citas + +--- + +## Arquitectura + +``` ++-------------------+ +-------------------+ +-------------------+ +| Evento Dental |---->| Webhook Service |---->| BullMQ Queue | +| (cita, tratam.) | | (enqueue) | | (webhooks) | ++-------------------+ +-------------------+ +-------------------+ + | + v + +-------------------+ + | Webhook Processor | + | (worker) | + +-------------------+ + | + +-------------------+-------------------+ + | | + v v + +---------------+ +---------------+ + | HTTP POST | | Retry Queue | + | (lab dental, | | (backoff) | + | aseguradora) | +---------------+ + +---------------+ | + | v (5 fails) + v +---------------+ + +---------------+ | DLQ | + | Delivery Log | | (failed) | + | (success) | +---------------+ + +---------------+ +``` + +--- + +## Ejemplo de Payload + +### Evento: cita.confirmada + +```json +{ + "event": "cita.confirmada", + "timestamp": "2026-01-13T10:30:00Z", + "webhook_id": "wh_dental_001", + "data": { + "cita_id": "cita_xyz789", + "paciente": { + "id": "pac_abc123", + "nombre": "Maria Garcia", + "telefono": "+521234567890" + }, + "fecha": "2026-01-15", + "hora": "10:00", + "tratamiento": "Limpieza dental", + "doctor": "Dr. Rodriguez", + "sillon": 2, + "duracion_minutos": 45 + } +} +``` + +### Evento: tratamiento.completado + +```json +{ + "event": "tratamiento.completado", + "timestamp": "2026-01-13T11:45:00Z", + "webhook_id": "wh_dental_002", + "data": { + "tratamiento_id": "trat_def456", + "paciente_id": "pac_abc123", + "tipo": "Resina", + "piezas_tratadas": ["16", "17"], + "doctor": "Dr. Martinez", + "costo": 1500.00, + "moneda": "MXN", + "notas": "Resina compuesta en molares superiores" + } +} +``` + +--- + +## Dependencias + +**Este modulo depende de:** +- MGN-001 Auth (autenticacion de administradores) +- MGN-004 Tenants (aislamiento por clinica) +- MGN-017 Plans (feature gating - solo planes Clinica y Centro) + +**Modulos que dependen de este:** +- Integraciones con laboratorios dentales +- Sistemas de aseguradoras +- Herramientas de notificacion + +--- + +## Seguridad y Normativas + +| Medida | Implementacion | +|--------|----------------| +| HMAC signature | SHA-256 con secret por endpoint | +| Timestamp | Previene ataques de replay (5 min) | +| URL validation | Solo HTTPS en produccion | +| Timeout | 30 segundos maximo | +| NOM-013-SSA2-2015 | No enviar datos sensibles de salud sin consentimiento | +| LFPDPPP | Cumplimiento de privacidad de datos | + +### Datos Sensibles + +Los webhooks NO deben incluir: +- Expediente clinico completo +- Diagnosticos detallados +- Radiografias o imagenes +- Datos de pago completos + +Para datos sensibles, el receptor debe hacer una consulta autenticada a la API. + +--- + +## Documentacion + +- **Requerimientos:** [requerimientos/](./requerimientos/) +- **Especificaciones:** [especificaciones/](./especificaciones/) +- **User Stories:** [historias-usuario/](./historias-usuario/) +- **Trazabilidad:** [implementacion/TRACEABILITY.yml](./implementacion/TRACEABILITY.yml) + +--- + +## Referencias + +- **Fuente:** [erp-core/MGN-018-webhooks](../../../../../erp-core/docs/04-fase-saas/MGN-018-webhooks/) +- **Arquitectura SaaS:** [ARQUITECTURA-SAAS.md](../../00-vision-general/ARQUITECTURA-SAAS.md) + +--- + +*Modulo: MGN-018-webhooks | Clinica Dental* +*Propagado desde erp-core via erp-clinicas* +*Actualizado: 2026-01-13* diff --git a/docs/04-fase-saas/MGN-018-webhooks/_MAP.md b/docs/04-fase-saas/MGN-018-webhooks/_MAP.md new file mode 100644 index 0000000..abc04fa --- /dev/null +++ b/docs/04-fase-saas/MGN-018-webhooks/_MAP.md @@ -0,0 +1,82 @@ +--- +id: MAP-MGN-018-webhooks +title: Mapa de Navegacion - Modulo Webhooks +type: NavigationMap +status: Draft +version: 1.0.0 +created_date: 2026-01-13 +updated_date: 2026-01-13 +--- + +# Mapa de Navegacion - MGN-018: Webhooks Dental + +## Estructura del Modulo + +``` +MGN-018-webhooks/ ++-- README.md <- Vision general ++-- _MAP.md <- ESTE ARCHIVO +| ++-- requerimientos/ <- RFs +| +-- INDICE-RF-WEBHOOKS.md +| +-- RF-WEBHOOKS-001.md <- Registro de endpoints +| +-- RF-WEBHOOKS-002.md <- Eventos dentales +| +-- RF-WEBHOOKS-003.md <- Reintentos y DLQ +| ++-- especificaciones/ <- ETs +| +-- INDICE-ET-WEBHOOKS.md +| +-- ET-WEBHOOKS-DATABASE.md +| +-- ET-WEBHOOKS-BACKEND.md +| ++-- historias-usuario/ +| +-- INDICE-US-WEBHOOKS.md +| ++-- implementacion/ + +-- TRACEABILITY.yml +``` + +--- + +## Eventos Dentales Disponibles + +| Evento | Descripcion | +|--------|-------------| +| cita.creada | Nueva cita agendada | +| cita.confirmada | Paciente confirmo cita | +| cita.cancelada | Cita cancelada | +| tratamiento.completado | Tratamiento finalizado | +| odontograma.actualizado | Cambio en odontograma | +| pago.recibido | Pago procesado | + +--- + +## Indice de Documentos + +### Requerimientos + +| ID | Descripcion | Estado | +|----|-------------|--------| +| RF-WEBHOOKS-001 | Registro de endpoints | Draft | +| RF-WEBHOOKS-002 | Eventos dentales | Draft | +| RF-WEBHOOKS-003 | Reintentos y DLQ | Draft | + +### Especificaciones + +| ID | Descripcion | Estado | +|----|-------------|--------| +| ET-WEBHOOKS-DATABASE | Modelo de datos | Draft | +| ET-WEBHOOKS-BACKEND | API y workers | Draft | + +--- + +## Seguridad + +- HMAC-SHA256 signature +- Solo HTTPS en produccion +- No enviar datos sensibles de salud sin consentimiento +- Cumplimiento LFPDPPP + +--- + +*Mapa | MGN-018-webhooks | Clinica Dental* +*Actualizado: 2026-01-13* diff --git a/docs/04-fase-saas/MGN-019-feature-flags/README.md b/docs/04-fase-saas/MGN-019-feature-flags/README.md new file mode 100644 index 0000000..8669ab4 --- /dev/null +++ b/docs/04-fase-saas/MGN-019-feature-flags/README.md @@ -0,0 +1,176 @@ +--- +id: MGN-019-feature-flags +title: Sistema de Feature Flags para Clinica Dental +type: Module +status: Draft +priority: P1 +version: 1.0.0 +created_date: 2026-01-13 +updated_date: 2026-01-13 +source: erp-core/MGN-019-feature-flags +normativas: [NOM-013-SSA2-2015] +--- + +# MGN-019: Sistema de Feature Flags Dental + +## Descripcion + +Sistema propio de feature flags para control granular de funcionalidades odontologicas por clinica y plan. Permite toggle de features dentales sin redeploy, rollout gradual de nuevas funcionalidades, y override manual por clinica para casos especiales. + +## Objetivos + +- Toggle de features dentales sin necesidad de redeploy +- Flags configurables por clinica y por plan +- Gradual rollout (porcentaje de clinicas) +- A/B testing de funcionalidades +- Override manual por clinica con expiracion opcional + +## Alcance + +| Caracteristica | Incluido | Notas | +|----------------|----------|-------| +| Boolean flags | Si | On/off simple | +| Plan-based flags | Si | Por tier de plan | +| Tenant override | Si | Admin puede activar/desactivar | +| Percentage rollout | Si | % de clinicas | +| User targeting | No | Fase posterior | +| Analytics | No | Fase posterior | + +## Feature Flags Odontologicos + +### Funcionalidades por Plan + +| Feature Flag | Consultorio | Clinica | Centro | +|--------------|:-----------:|:-------:|:------:| +| `odontograma_digital` | - | X | X | +| `radiografias_digitales` | - | X | X | +| `ortodoncia_3d` | - | - | X | +| `asistente_ia_dental` | - | - | X | +| `whatsapp_pacientes` | - | - | X | +| `multi_sucursal` | - | - | X | +| `reportes_avanzados` | - | X | X | +| `integracion_laboratorio` | - | X | X | +| `presupuestos_financiados` | - | X | X | + +### Features en Rollout + +| Feature Flag | Descripcion | Rollout % | Estado | +|--------------|-------------|-----------|--------| +| `nuevo_odontograma_v2` | Nueva UI de odontograma | 25% | Beta | +| `radiografia_ia` | Analisis IA de radiografias | 10% | Alpha | +| `agenda_inteligente` | Sugerencias de agenda | 50% | Beta | +| `recordatorio_sms` | Recordatorios via SMS | 100% | GA | + +### Features de Normativa + +| Feature Flag | Descripcion | Default | +|--------------|-------------|---------| +| `consentimiento_digital` | Firma digital de consentimientos | Activado | +| `historial_nom013` | Historial conforme NOM-013-SSA2 | Activado | +| `bitacora_cofepris` | Bitacora de procedimientos | Activado | + +## Arquitectura de Evaluacion + +``` +Request (ej: acceder odontograma_digital) + | + v ++-------------------+ +| FeatureFlagService| ++-------------------+ + | + +---> 1. Check tenant override (clinica especifica) + | | + | v (si existe) + | Return override value + | + +---> 2. Check plan features (Consultorio/Clinica/Centro) + | | + | v (si definido en plan) + | Return plan value + | + +---> 3. Check global flag + rollout + | | + | v + | Evaluate (boolean/percentage) + | + v +Return final value +``` + +## Prioridad de Evaluacion + +1. **Tenant Override** - Maxima prioridad, permite excepciones (ej: demo, VIP) +2. **Plan Features** - Features incluidas en plan de la clinica +3. **Global Flag** - Valor default con soporte de rollout gradual + +## Casos de Uso + +### Ejemplo: Activar ortodoncia_3d para demo + +```typescript +// Override para clinica en demo +await featureFlagService.setOverride({ + tenantId: 'clinica_demo_123', + flag: 'ortodoncia_3d', + value: true, + expiresAt: addDays(new Date(), 14), // 14 dias de demo + reason: 'Demo para cliente potencial' +}); +``` + +### Ejemplo: Rollout gradual de radiografia_ia + +```typescript +// Configurar rollout al 25% de clinicas +await featureFlagService.setRollout({ + flag: 'radiografia_ia', + percentage: 25, + filterByPlan: ['clinica', 'centro_dental'] +}); +``` + +### Ejemplo: Verificar feature en codigo + +```typescript +@Get('odontograma/3d') +@FeatureGuard('ortodoncia_3d') +async getOdontograma3D(@Tenant() tenant: Tenant) { + // Solo accesible si flag activo para esta clinica + return this.ortodonciaService.get3DModel(tenant.id); +} +``` + +## Documentacion del Modulo + +- [Mapa del Modulo](./_MAP.md) +- [Requerimientos](./requerimientos/INDICE-RF-FFLAGS.md) +- [Especificaciones](./especificaciones/INDICE-ET-FFLAGS.md) +- [Historias de Usuario](./historias-usuario/INDICE-US-FFLAGS.md) +- [Trazabilidad](./implementacion/TRACEABILITY.yml) + +## Dependencias + +### Modulos Requeridos + +- **MGN-004-tenants** - Contexto de clinica +- **MGN-017-plans** - Planes de suscripcion + +### Modulos Dependientes + +- Odontograma (feature: odontograma_digital) +- Radiografias (feature: radiografias_digitales) +- Ortodoncia (feature: ortodoncia_3d) +- IA (feature: asistente_ia_dental) +- WhatsApp (feature: whatsapp_pacientes) + +## Referencias + +- **Fuente:** [erp-core/MGN-019-feature-flags](../../../../../erp-core/docs/04-fase-saas/MGN-019-feature-flags/) +- **Plans:** [MGN-017-plans](../MGN-017-plans/) + +--- + +*Modulo MGN-019 - Feature Flags | Clinica Dental* +*Propagado desde erp-core via erp-clinicas* +*Actualizado: 2026-01-13* diff --git a/docs/04-fase-saas/MGN-019-feature-flags/_MAP.md b/docs/04-fase-saas/MGN-019-feature-flags/_MAP.md new file mode 100644 index 0000000..b5ab52c --- /dev/null +++ b/docs/04-fase-saas/MGN-019-feature-flags/_MAP.md @@ -0,0 +1,91 @@ +--- +id: MAP-MGN-019-feature-flags +title: Mapa de Navegacion - Feature Flags +type: NavigationMap +status: Draft +version: 1.0.0 +created_date: 2026-01-13 +updated_date: 2026-01-13 +--- + +# Mapa de Navegacion - MGN-019: Feature Flags Dental + +## Estructura del Modulo + +``` +MGN-019-feature-flags/ ++-- README.md <- Vision general ++-- _MAP.md <- ESTE ARCHIVO +| ++-- requerimientos/ +| +-- INDICE-RF-FFLAGS.md +| +-- RF-FFLAGS-001.md <- Boolean flags +| +-- RF-FFLAGS-002.md <- Plan-based flags +| +-- RF-FFLAGS-003.md <- Rollout gradual +| ++-- especificaciones/ +| +-- INDICE-ET-FFLAGS.md +| +-- ET-FFLAGS-DATABASE.md +| +-- ET-FFLAGS-BACKEND.md +| ++-- historias-usuario/ +| +-- INDICE-US-FFLAGS.md +| ++-- implementacion/ + +-- TRACEABILITY.yml +``` + +--- + +## Feature Flags Odontologicos + +| Flag | Consultorio | Clinica | Centro | +|------|:-----------:|:-------:|:------:| +| odontograma_digital | - | X | X | +| radiografias_digitales | - | X | X | +| ortodoncia_3d | - | - | X | +| asistente_ia_dental | - | - | X | +| whatsapp_pacientes | - | - | X | + +--- + +## Rollout Actual + +| Flag | % Rollout | Estado | +|------|-----------|--------| +| nuevo_odontograma_v2 | 25% | Beta | +| radiografia_ia | 10% | Alpha | +| agenda_inteligente | 50% | Beta | +| recordatorio_sms | 100% | GA | + +--- + +## Prioridad de Evaluacion + +1. Tenant Override (clinica especifica) +2. Plan Features (Consultorio/Clinica/Centro) +3. Global Flag (rollout %) + +--- + +## Indice de Documentos + +### Requerimientos + +| ID | Descripcion | Estado | +|----|-------------|--------| +| RF-FFLAGS-001 | Boolean flags | Draft | +| RF-FFLAGS-002 | Plan-based flags | Draft | +| RF-FFLAGS-003 | Rollout gradual | Draft | + +### Especificaciones + +| ID | Descripcion | Estado | +|----|-------------|--------| +| ET-FFLAGS-DATABASE | Modelo de datos | Draft | +| ET-FFLAGS-BACKEND | FeatureFlagService | Draft | + +--- + +*Mapa | MGN-019-feature-flags | Clinica Dental* +*Actualizado: 2026-01-13* diff --git a/docs/04-fase-saas/README.md b/docs/04-fase-saas/README.md new file mode 100644 index 0000000..f8a98d3 --- /dev/null +++ b/docs/04-fase-saas/README.md @@ -0,0 +1,104 @@ +--- +id: fase-04-saas +title: Fase 04 - Capacidades SaaS para Clinica Dental +type: PhaseOverview +status: Draft +version: 1.0.0 +created_date: 2026-01-13 +updated_date: 2026-01-13 +normativas: [NOM-013-SSA2-2015, COFEPRIS] +--- + +# Fase 04: Capacidades SaaS para Clinica Dental + +## Descripcion + +Esta fase implementa las capacidades de Software as a Service (SaaS) para la plataforma de gestion de clinicas dentales. Permite la monetizacion mediante suscripciones, la gestion de planes diferenciados por tipo de consultorio (individual, grupal, clinica), y la integracion con sistemas externos via webhooks. + +--- + +## Modulos de la Fase + +| ID | Modulo | Descripcion | Prioridad | +|----|--------|-------------|-----------| +| MGN-016 | [Billing](./MGN-016-billing/) | Facturacion y suscripciones con Stripe | P0 | +| MGN-017 | [Plans](./MGN-017-plans/) | Planes y Feature Gating para consultorios | P0 | +| MGN-018 | [Webhooks](./MGN-018-webhooks/) | Webhooks outbound para integraciones | P1 | +| MGN-019 | [Feature Flags](./MGN-019-feature-flags/) | Control granular de funcionalidades | P1 | + +--- + +## Planes Propuestos para Clinica Dental + +| Plan | Precio/mes | Sillones | Storage | Caracteristicas Clave | +|------|------------|----------|---------|----------------------| +| **Consultorio** | $499 MXN | 1 | 5 GB | Odontograma basico, Citas, Expedientes | +| **Clinica** | $1,499 MXN | 5 | 25 GB | + Ortodoncia, Radiografias digitales, Reportes | +| **Centro Dental** | $3,999 MXN | Ilimitado | 100 GB | + Multi-sucursal, IA, WhatsApp Business | + +--- + +## Normativas Aplicables + +### NOM-013-SSA2-2015 +Norma Oficial Mexicana para la prevencion y control de enfermedades bucales. Aplica a: +- Registro y trazabilidad de tratamientos +- Consentimiento informado digital +- Protocolos de atencion + +### COFEPRIS +Comision Federal para la Proteccion contra Riesgos Sanitarios: +- Registro de materiales y medicamentos +- Trazabilidad de insumos odontologicos +- Bitacora de procedimientos + +### Ley General de Proteccion de Datos Personales (LGPDP) +- Expediente clinico como dato sensible +- Consentimiento para almacenamiento en nube +- Derecho ARCO (Acceso, Rectificacion, Cancelacion, Oposicion) + +--- + +## Flujo de Suscripcion para Clinicas + +``` +1. Dentista registra clinica + | +2. Selecciona plan (Consultorio/Clinica/Centro) + | +3. Checkout con Stripe (tarjeta o OXXO) + | +4. Webhook confirma pago + | +5. Se activan features del plan + | +6. Clinica operativa con su odontograma +``` + +--- + +## Estructura de Directorios + +``` +04-fase-saas/ ++-- README.md <- ESTE ARCHIVO ++-- _MAP.md <- Indice de navegacion ++-- MGN-016-billing/ <- Facturacion y suscripciones ++-- MGN-017-plans/ <- Planes y cuotas ++-- MGN-018-webhooks/ <- Integraciones externas ++-- MGN-019-feature-flags/ <- Control de features +``` + +--- + +## Referencias + +- [ARQUITECTURA-SAAS.md](../00-vision-general/ARQUITECTURA-SAAS.md) - Arquitectura SaaS +- [erp-core/04-fase-saas](../../../../erp-core/docs/04-fase-saas/) - Documentacion origen +- [Stripe Docs](https://stripe.com/docs) - Integracion de pagos + +--- + +*Fase 04 - SaaS | Clinica Dental* +*Propagado desde erp-core via erp-clinicas* +*Actualizado: 2026-01-13* diff --git a/docs/04-fase-saas/_MAP.md b/docs/04-fase-saas/_MAP.md new file mode 100644 index 0000000..9992a4f --- /dev/null +++ b/docs/04-fase-saas/_MAP.md @@ -0,0 +1,101 @@ +--- +id: MAP-fase-04-saas +title: Mapa de Navegacion - Fase 04 SaaS +type: NavigationMap +status: Draft +version: 1.0.0 +created_date: 2026-01-13 +updated_date: 2026-01-13 +--- + +# Mapa de Navegacion - Fase 04: SaaS + +## Estructura de la Fase + +``` +04-fase-saas/ ++-- README.md <- Vision general de la fase ++-- _MAP.md <- ESTE ARCHIVO +| ++-- MGN-016-billing/ <- Facturacion dental +| +-- README.md <- Vision del modulo +| +-- _MAP.md <- Indice del modulo +| +-- requerimientos/ <- RFs de billing +| +-- especificaciones/ <- ETs tecnicas +| +-- historias-usuario/ <- User stories +| +-- implementacion/ <- Trazabilidad +| ++-- MGN-017-plans/ <- Planes de clinica +| +-- README.md <- Vision del modulo +| +-- _MAP.md <- Indice del modulo +| +-- ... <- Subdirectorios +| ++-- MGN-018-webhooks/ <- Integraciones +| +-- README.md <- Vision del modulo +| +-- _MAP.md <- Indice del modulo +| +-- ... <- Subdirectorios +| ++-- MGN-019-feature-flags/ <- Control features + +-- README.md <- Vision del modulo + +-- _MAP.md <- Indice del modulo + +-- ... <- Subdirectorios +``` + +--- + +## Indice de Modulos + +| Modulo | Descripcion | Estado | Prioridad | +|--------|-------------|--------|-----------| +| [MGN-016-billing](./MGN-016-billing/) | Suscripciones y facturacion para clinicas | Draft | P0 | +| [MGN-017-plans](./MGN-017-plans/) | Planes (Consultorio, Clinica, Centro) | Draft | P0 | +| [MGN-018-webhooks](./MGN-018-webhooks/) | Webhooks para integraciones externas | Draft | P1 | +| [MGN-019-feature-flags](./MGN-019-feature-flags/) | Feature flags para odontologia | Draft | P1 | + +--- + +## Flujo de Navegacion Recomendado + +### Para Entender la Fase + +``` +1. README.md -> Vision general SaaS +2. MGN-016-billing/README.md -> Sistema de facturacion +3. MGN-017-plans/README.md -> Planes disponibles +``` + +### Para Implementar + +``` +1. MGN-016-billing/ -> Configurar Stripe +2. MGN-017-plans/ -> Definir planes de clinica +3. MGN-019-feature-flags/ -> Configurar features por plan +4. MGN-018-webhooks/ -> Integraciones externas +``` + +--- + +## Adaptaciones al Dominio Odontologico + +| Aspecto | Adaptacion | +|---------|------------| +| Planes | Consultorio (1 sillon), Clinica (5), Centro (ilimitado) | +| Features | odontograma_digital, radiografias, ortodoncia_3d | +| Limites | Por numero de sillones, pacientes, tratamientos | +| Facturacion | CFDI 4.0, SAT, formato dental | +| Normativas | NOM-013-SSA2-2015, COFEPRIS | + +--- + +## Referencias Cruzadas + +| Documento | Ubicacion | Descripcion | +|-----------|-----------|-------------| +| Arquitectura SaaS | ../00-vision-general/ | Arquitectura general | +| Origen erp-core | erp-core/docs/04-fase-saas/ | Documentacion base | +| Herencia erp-clinicas | erp-clinicas/docs/ | Adaptaciones clinicas | + +--- + +*Mapa de Navegacion | Fase 04 SaaS | Clinica Dental* +*Actualizado: 2026-01-13* diff --git a/docs/05-fase-ia/MGN-020-ai-integration/README.md b/docs/05-fase-ia/MGN-020-ai-integration/README.md new file mode 100644 index 0000000..6902d26 --- /dev/null +++ b/docs/05-fase-ia/MGN-020-ai-integration/README.md @@ -0,0 +1,210 @@ +--- +id: MGN-020-ai-integration +title: Modulo AI Integration - Gateway LLM para Clinica Dental +type: Module +status: Draft +version: 1.0.0 +priority: P1 +phase: Fase IA +created_date: 2026-01-13 +updated_date: 2026-01-13 +source: erp-core/MGN-020-ai-integration +normativas: [NOM-013-SSA2-2015, LFPDPPP] +--- + +# MGN-020: AI Integration - Gateway LLM para Clinica Dental + +> Capa de abstraccion unificada para integracion con modelos de lenguaje especializados en odontologia + +## Resumen Ejecutivo + +El modulo AI Integration proporciona un gateway centralizado para consumir servicios de modelos de lenguaje (LLM) de multiples proveedores a traves de OpenRouter. Esta adaptado para el dominio odontologico, con conocimiento de nomenclatura dental FDI, tratamientos, y normativas mexicanas de salud bucal. + +--- + +## 1. Objetivos del Modulo + +| Objetivo | Descripcion | Prioridad | +|----------|-------------|-----------| +| Gateway unificado | API unica para multiples providers LLM | P0 | +| Fallback automatico | Cambio automatico a modelo backup | P0 | +| Cost tracking | Registro de costos por clinica | P0 | +| Streaming | Respuestas en tiempo real via SSE | P1 | +| Prompt templates dentales | Templates especializados en odontologia | P1 | +| Rate limiting | Limites por plan de suscripcion | P1 | + +--- + +## 2. System Prompt Especializado en Odontologia + +``` +Eres el asistente virtual de {{CLINICA_DENTAL}}, una clinica dental en Mexico. + +## Especialidades +- Odontologia general y preventiva +- Ortodoncia (brackets, alineadores, retenedores) +- Endodoncia (tratamientos de conductos) +- Periodoncia (enfermedad periodontal) +- Estetica dental (blanqueamiento, carillas) +- Cirugia oral (extracciones, implantes) + +## Conocimientos Tecnicos +- Nomenclatura dental FDI (sistema de dos digitos) +- Cuadrantes dentales: + * Cuadrante 1: Superior derecho (11-18) + * Cuadrante 2: Superior izquierdo (21-28) + * Cuadrante 3: Inferior izquierdo (31-38) + * Cuadrante 4: Inferior derecho (41-48) +- Piezas deciduas (temporales): + * 51-55, 61-65, 71-75, 81-85 +- Estados de piezas: Sano, Caries, Obturacion, Endodoncia, Corona, Ausente +- Caras dentales: Mesial, Distal, Oclusal, Vestibular, Lingual/Palatino + +## Normativas +- NOM-013-SSA2-2015: Prevencion y control de enfermedades bucales +- COFEPRIS: Regulacion de materiales e insumos +- NOM-004-SSA3-2012: Expediente clinico + +## Reglas de Comportamiento +1. Responde en espanol mexicano profesional pero calido +2. NUNCA des diagnosticos clinicos - siempre recomienda visita al odontologo +3. Explica procedimientos de forma clara y sin tecnicismos excesivos +4. Para citas, usa el sistema de agenda del consultorio +5. Respeta la confidencialidad del expediente clinico +6. No compartas informacion de un paciente con otro +7. Para urgencias (dolor intenso, trauma, sangrado), indica acudir de inmediato +``` + +--- + +## 3. Modelos Soportados + +### 3.1 Tabla de Modelos y Costos + +| Modelo | ID OpenRouter | Input/1M tokens | Output/1M tokens | Uso Dental | +|--------|---------------|----------------:|-----------------:|------------| +| Claude 3 Haiku | anthropic/claude-3-haiku | $0.25 | $1.25 | Chat rapido | +| Claude 3 Sonnet | anthropic/claude-3-sonnet | $3.00 | $15.00 | Consultas complejas | +| GPT-4 Turbo | openai/gpt-4-turbo | $10.00 | $30.00 | Analisis detallado | +| GPT-4o-mini | openai/gpt-4o-mini | $0.15 | $0.60 | Alto volumen | + +### 3.2 Recomendacion por Caso de Uso Dental + +| Caso de Uso | Modelo Recomendado | Justificacion | +|-------------|-------------------|---------------| +| Chat con pacientes | Claude 3 Haiku | Rapido y natural | +| Explicar tratamientos | Claude 3 Sonnet | Alta calidad | +| Analisis de caso | GPT-4 Turbo | Profundidad | +| Recordatorios masivos | GPT-4o-mini | Costo bajo | + +--- + +## 4. Rate Limits por Plan + +| Plan | Requests/dia | Tokens/dia | Max Tokens/Request | +|------|-------------:|-----------:|-------------------:| +| Consultorio | 0 | 0 | 0 (sin acceso) | +| Clinica | 0 | 0 | 0 (sin acceso) | +| Centro Dental | 500 | 100,000 | 2,000 | + +> Nota: La funcionalidad de IA solo esta disponible en el plan Centro Dental. + +--- + +## 5. Capacidades Principales + +### 5.1 Funcionalidades Core + +- **Chat con Pacientes**: Respuestas a dudas comunes sobre tratamientos +- **Explicacion de Procedimientos**: Descripcion detallada de tratamientos +- **Recomendaciones de Cuidado**: Instrucciones pre y post operatorias +- **Informacion de Precios**: Consulta de costos aproximados (via MCP) +- **Agendamiento**: Asistencia para agendar citas (via MCP) + +### 5.2 Seguridad y Normativas + +| Medida | Implementacion | +|--------|----------------| +| API key rotation | Secrets manager con encriptacion | +| Rate limiting | Por clinica segun plan | +| Content filtering | OpenRouter builtin | +| Cost caps | Limite mensual configurable | +| Audit trail | Log de todas las consultas | +| NOM-013-SSA2 | No diagnosticar, solo informar | +| LFPDPPP | No almacenar datos sensibles en prompts | + +--- + +## 6. Estructura del Modulo + +``` +MGN-020-ai-integration/ ++-- README.md <- Este archivo ++-- _MAP.md <- Indice y navegacion ++-- requerimientos/ +| +-- RF-AI-001.md <- Gateway LLM +| +-- RF-AI-002.md <- Streaming +| +-- RF-AI-003.md <- Cost tracking +| +-- RF-AI-004.md <- Prompt templates dentales +| +-- INDICE-RF-AI.md ++-- especificaciones/ +| +-- ET-AI-DATABASE.md <- Modelo de datos +| +-- ET-AI-BACKEND.md <- API y servicios +| +-- ET-AI-FRONTEND.md <- UI de chat +| +-- INDICE-ET-AI.md ++-- historias-usuario/ +| +-- INDICE-US-AI.md ++-- implementacion/ + +-- TRACEABILITY.yml +``` + +--- + +## 7. Dependencias + +### 7.1 Internas + +| Modulo | Relacion | +|--------|----------| +| MGN-004-tenants | Aislamiento por clinica | +| MGN-001-auth | Autenticacion JWT | +| MGN-017-plans | Feature gating (solo Centro Dental) | +| MGN-022-mcp-server | Herramientas de negocio | + +### 7.2 Externas + +| Servicio | Proposito | +|----------|-----------| +| OpenRouter API | Gateway multi-provider | +| Redis | Cache de configuraciones | + +--- + +## 8. Configuracion + +```bash +# OpenRouter +OPENROUTER_API_KEY=sk-or-xxx +OPENROUTER_SITE_URL=https://clinica.ejemplo.com +OPENROUTER_SITE_NAME=Clinica Dental Ejemplo + +# Defaults para odontologia +AI_DEFAULT_MODEL=anthropic/claude-3-haiku +AI_DEFAULT_TEMPERATURE=0.7 +AI_DEFAULT_MAX_TOKENS=1000 +AI_SYSTEM_PROMPT_TYPE=dental +``` + +--- + +## Referencias + +- **Fuente**: [erp-core/MGN-020-ai-integration](../../../../../erp-core/docs/05-fase-ia/MGN-020-ai-integration/) +- **MCP Server**: [MGN-022-mcp-server](../MGN-022-mcp-server/) +- **OpenRouter Docs**: https://openrouter.ai/docs + +--- + +*Modulo MGN-020 - AI Integration | Clinica Dental* +*Propagado desde erp-core via erp-clinicas* +*Actualizado: 2026-01-13* diff --git a/docs/05-fase-ia/MGN-020-ai-integration/_MAP.md b/docs/05-fase-ia/MGN-020-ai-integration/_MAP.md new file mode 100644 index 0000000..0df7321 --- /dev/null +++ b/docs/05-fase-ia/MGN-020-ai-integration/_MAP.md @@ -0,0 +1,95 @@ +--- +id: MAP-MGN-020-ai-integration +title: Mapa de Navegacion - AI Integration +type: NavigationMap +status: Draft +version: 1.0.0 +created_date: 2026-01-13 +updated_date: 2026-01-13 +--- + +# Mapa de Navegacion - MGN-020: AI Integration Dental + +## Estructura del Modulo + +``` +MGN-020-ai-integration/ ++-- README.md <- Vision general ++-- _MAP.md <- ESTE ARCHIVO +| ++-- requerimientos/ +| +-- INDICE-RF-AI.md +| +-- RF-AI-001.md <- Gateway LLM +| +-- RF-AI-002.md <- Streaming SSE +| +-- RF-AI-003.md <- Cost tracking +| +-- RF-AI-004.md <- Prompts dentales +| ++-- especificaciones/ +| +-- INDICE-ET-AI.md +| +-- ET-AI-DATABASE.md +| +-- ET-AI-BACKEND.md +| +-- ET-AI-FRONTEND.md +| ++-- historias-usuario/ +| +-- INDICE-US-AI.md +| ++-- implementacion/ + +-- TRACEABILITY.yml +``` + +--- + +## Modelos Recomendados + +| Caso de Uso | Modelo | Costo | +|-------------|--------|-------| +| Chat pacientes | Claude 3 Haiku | Bajo | +| Explicar tratamientos | Claude 3 Sonnet | Medio | +| Analisis complejo | GPT-4 Turbo | Alto | + +--- + +## Disponibilidad por Plan + +| Plan | Acceso IA | +|------|-----------| +| Consultorio | No | +| Clinica | No | +| Centro Dental | Si | + +--- + +## System Prompt Dental + +El asistente IA conoce: +- Nomenclatura FDI (11-48, 51-85) +- Estados de piezas dentales +- Tratamientos comunes +- Normativas NOM-013-SSA2-2015 +- COFEPRIS + +--- + +## Indice de Documentos + +### Requerimientos + +| ID | Descripcion | Estado | +|----|-------------|--------| +| RF-AI-001 | Gateway LLM multi-proveedor | Draft | +| RF-AI-002 | Streaming SSE | Draft | +| RF-AI-003 | Cost tracking por clinica | Draft | +| RF-AI-004 | Prompt templates dentales | Draft | + +### Especificaciones + +| ID | Descripcion | Estado | +|----|-------------|--------| +| ET-AI-DATABASE | Modelo de datos | Draft | +| ET-AI-BACKEND | API y servicios | Draft | +| ET-AI-FRONTEND | UI de chat | Draft | + +--- + +*Mapa | MGN-020-ai-integration | Clinica Dental* +*Actualizado: 2026-01-13* diff --git a/docs/05-fase-ia/MGN-021-whatsapp-business/README.md b/docs/05-fase-ia/MGN-021-whatsapp-business/README.md new file mode 100644 index 0000000..1b32457 --- /dev/null +++ b/docs/05-fase-ia/MGN-021-whatsapp-business/README.md @@ -0,0 +1,363 @@ +--- +id: MGN-021-whatsapp-business +title: Modulo WhatsApp Business con IA para Clinica Dental +type: Module +status: Draft +priority: P1 +phase: 05-fase-ia +version: 1.0.0 +created_date: 2026-01-13 +updated_date: 2026-01-13 +normativas: [NOM-013-SSA2-2015, LFPDPPP] +--- + +# MGN-021: WhatsApp Business con IA para Clinica Dental + +> Integracion de WhatsApp Business API con procesamiento inteligente para comunicacion con pacientes + +## Resumen Ejecutivo + +El modulo WhatsApp Business permite a las clinicas dentales comunicarse con sus pacientes a traves de WhatsApp, procesando mensajes entrantes con inteligencia artificial para proporcionar respuestas contextuales sobre citas, tratamientos, instrucciones de cuidado y ejecutar acciones de negocio automaticamente. + +--- + +## 1. Objetivos del Modulo + +### 1.1 Objetivos Principales + +- **Recepcion de mensajes**: Webhook para recibir mensajes de pacientes via Meta Cloud API +- **Procesamiento inteligente**: Analisis con LLM especializado en odontologia +- **Ejecucion de acciones**: Uso de herramientas MCP para consultar citas, odontogramas +- **Respuestas automaticas**: Generacion de respuestas en espanol mexicano profesional +- **Trazabilidad**: Registro completo de conversaciones y acciones + +### 1.2 Objetivos Secundarios + +- Soporte multi-clinica (un numero por clinica) +- Templates pre-aprobados por Meta +- Recordatorios automaticos de citas +- Dashboard de conversaciones +- Metricas de respuesta + +--- + +## 2. Alcance + +### 2.1 Incluido + +| Caracteristica | Descripcion | Prioridad | +|----------------|-------------|-----------| +| Recepcion mensajes | Webhook Meta + almacenamiento | P0 | +| Procesamiento LLM | Analisis con Claude/GPT | P0 | +| Herramientas MCP | Citas, Odontograma, Tratamientos | P0 | +| Envio respuestas | API Meta para texto | P0 | +| Templates dentales | Mensajes pre-aprobados | P1 | +| Audio (voz) | Transcripcion con Whisper | P1 | +| Imagenes | Recepcion de radiografias | P2 | +| UI Bandeja | Dashboard de conversaciones | P1 | + +### 2.2 Excluido (Futuro) + +- Chatbots de otras plataformas +- Llamadas de voz +- Pagos dentro de WhatsApp +- Envio de radiografias via WhatsApp + +--- + +## 3. Flujo de Mensaje Completo + +``` ++----------+ +----------+ +---------------+ +------------+ +| Paciente |---->| WhatsApp |---->| Meta API |---->| Webhook | +| (movil) | | (app) | | (Cloud API) | | (Backend) | ++----------+ +----------+ +---------------+ +------------+ + | + v + +------------------+ + | WhatsApp Service | + | 1. Verificar | + | 2. Extraer clinica| + | 3. Guardar msg | + +------------------+ + | + v + +------------------+ + | LLM Service | + | 1. Cargar ctx | + | 2. System prompt | + | (dental) | + | 3. Llamar modelo | + +------------------+ + | + v + +------------------+ + | MCP Server | + | Tools dentales: | + | - consultar_cita | + | - ver_odontograma| + | - agendar_cita | + +------------------+ + | + v + +------------------+ + | LLM Service | + | 4. Generar resp | + | en espanol | + +------------------+ + | + v ++----------+ +----------+ +---------------+ +------------+ +| Paciente |<----| WhatsApp |<----| Meta API |<----| WA Service | +| (movil) | | (app) | | (send msg) | | (responde) | ++----------+ +----------+ +---------------+ +------------+ +``` + +--- + +## 4. Templates WhatsApp para Clinica Dental + +### 4.1 Recordatorio de Cita (recordatorio_cita_dental) + +``` +Hola {{1}}, te recordamos tu cita en {{2}}: + +Fecha: {{3}} +Hora: {{4}} +Doctor(a): {{5}} +Tratamiento: {{6}} + +Por favor confirma tu asistencia respondiendo SI o reprogramar respondiendo CAMBIAR. + +Si tienes alguna duda, estamos para ayudarte. +``` + +Variables: +1. Nombre del paciente +2. Nombre de la clinica +3. Fecha (ej: "Miercoles 15 de enero") +4. Hora (ej: "10:00 AM") +5. Nombre del doctor +6. Tipo de tratamiento + +### 4.2 Confirmacion de Tratamiento (confirmacion_tratamiento) + +``` +{{1}}, tu tratamiento ha sido registrado: + +Procedimiento: {{2}} +Pieza(s) dental(es): {{3}} +Doctor(a): {{4}} +Fecha: {{5}} + +Proxima cita: {{6}} + +{{7}} + +Cualquier duda sobre los cuidados, escribenos. +Clinica {{8}} +``` + +Variables: +1. Nombre del paciente +2. Nombre del procedimiento +3. Piezas tratadas (ej: "16, 17") +4. Nombre del doctor +5. Fecha del tratamiento +6. Proxima cita o "Pendiente de agendar" +7. Instrucciones breves de cuidado +8. Nombre de la clinica + +### 4.3 Instrucciones Postoperatorio (instrucciones_postoperatorio) + +``` +{{1}}, instrucciones despues de tu {{2}}: + +{{3}} + +Medicamentos: +{{4}} + +IMPORTANTE: Si presentas {{5}}, acude de inmediato o llama a {{6}}. + +Recuerda tu cita de seguimiento el {{7}}. + +Clinica {{8}} - Cuidamos tu sonrisa +``` + +Variables: +1. Nombre del paciente +2. Tipo de procedimiento +3. Lista de instrucciones de cuidado +4. Medicamentos recetados +5. Sintomas de alerta +6. Telefono de emergencias +7. Fecha de seguimiento +8. Nombre de la clinica + +--- + +## 5. Integracion con MCP Dental + +### 5.1 Herramientas Disponibles + +El LLM tiene acceso a herramientas especializadas en odontologia: + +| Herramienta | Descripcion | Uso | +|-------------|-------------|-----| +| `consultar_odontograma` | Ver estado de piezas dentales | Cuando paciente pregunta sobre dientes | +| `consultar_historial_dental` | Historial de tratamientos | Preguntas sobre tratamientos previos | +| `agendar_cita_dental` | Programar nueva cita | Solicitudes de cita | +| `verificar_disponibilidad` | Horarios disponibles | Antes de agendar | +| `consultar_cita_proxima` | Proxima cita del paciente | Preguntas sobre citas | +| `cancelar_reprogramar_cita` | Modificar cita existente | Cambios de cita | + +### 5.2 Ejemplo de Interaccion + +``` +Paciente: "Hola, necesito saber cuando es mi proxima cita" + +LLM piensa: Necesito consultar las citas del paciente +LLM llama: consultar_cita_proxima({ paciente_telefono: "+521234567890" }) +MCP retorna: { + "fecha": "2026-01-15", + "hora": "10:00", + "doctor": "Dra. Garcia", + "tratamiento": "Limpieza dental", + "sillon": 2 +} + +LLM responde: "Hola! Tu proxima cita es el miercoles 15 de enero a las 10:00 AM +con la Dra. Garcia para una limpieza dental. Te esperamos!" +``` + +--- + +## 6. System Prompts Dentales + +### 6.1 Para Pacientes + +``` +Eres el asistente virtual de {{CLINICA_DENTAL}}, una clinica dental en Mexico. + +Ayudas a los pacientes con: +- Informacion sobre tratamientos dentales +- Agendar, confirmar o reprogramar citas +- Consultar proximas citas +- Dudas sobre cuidados bucales +- Instrucciones pre y post operatorias + +Reglas: +1. Responde en espanol mexicano profesional pero calido +2. Se breve y claro +3. NUNCA diagnostiques - recomienda siempre visita al odontologo +4. Para urgencias (dolor intenso, sangrado, trauma), indica acudir de inmediato +5. Usa las herramientas MCP para consultar informacion real +6. No inventes datos de citas o tratamientos +7. Respeta la confidencialidad del expediente +8. Si no puedes ayudar, ofrece comunicar con recepcion +``` + +### 6.2 Para Staff de Clinica + +``` +Eres el asistente de {{CLINICA_DENTAL}} para el equipo de trabajo. + +Ayudas al staff con: +- Consulta rapida de agenda +- Estado de citas del dia +- Recordatorios pendientes +- Busqueda de pacientes + +Se directo, profesional y eficiente. +Proporciona informacion precisa usando las herramientas MCP. +``` + +--- + +## 7. Estructura del Modulo + +``` +docs/05-fase-ia/MGN-021-whatsapp-business/ ++-- README.md <- Este archivo ++-- _MAP.md <- Indice del modulo ++-- requerimientos/ +| +-- INDICE-RF-WHATSAPP.md +| +-- RF-WHATSAPP-001.md <- Recepcion de mensajes +| +-- RF-WHATSAPP-002.md <- Procesamiento con LLM +| +-- RF-WHATSAPP-003.md <- Templates dentales ++-- especificaciones/ +| +-- INDICE-ET-WHATSAPP.md +| +-- ET-WHATSAPP-DATABASE.md <- Modelo de datos +| +-- ET-WHATSAPP-BACKEND.md <- Servicios y webhook +| +-- ET-WHATSAPP-FRONTEND.md <- UI de conversaciones ++-- historias-usuario/ +| +-- INDICE-US-WHATSAPP.md ++-- implementacion/ + +-- TRACEABILITY.yml +``` + +--- + +## 8. Dependencias + +### 8.1 Internas + +- `MGN-022-mcp-server` - Herramientas MCP dentales +- `MGN-020-ai-integration` - Gateway LLM +- `MGN-017-plans` - Feature gating (solo Centro Dental) + +### 8.2 Externas + +- Meta Cloud API (WhatsApp Business) +- OpenRouter (Gateway LLM) +- Whisper API (transcripcion de audio) + +--- + +## 9. Normativas y Privacidad + +### 9.1 NOM-013-SSA2-2015 + +- No proporcionar diagnosticos via WhatsApp +- Registrar interacciones relacionadas con tratamientos +- Mantener trazabilidad de comunicaciones + +### 9.2 LFPDPPP (Datos Personales) + +- Expediente clinico es dato sensible +- Requerir consentimiento para comunicacion via WhatsApp +- No almacenar radiografias recibidas sin cifrar +- Anonimizar logs para analytics + +### 9.3 Reglas de Confidencialidad + +- No compartir informacion de un paciente con otro +- No enviar resultados de estudios sin confirmar identidad +- Mensajes deben ser leidos solo por destinatario + +--- + +## 10. Metricas de Exito + +| Metrica | Target | Medicion | +|---------|--------|----------| +| Tiempo de respuesta | < 5 segundos | P95 latencia | +| Tasa de resolucion | > 70% | Mensajes resueltos sin staff | +| Satisfaccion | > 4.0/5.0 | Encuestas post-chat | +| Costo por mensaje | < $0.02 USD | Tokens LLM + API Meta | +| Citas agendadas via WA | > 30% | Del total de citas | + +--- + +## Referencias + +- [ARQUITECTURA-IA.md](../../00-vision-general/ARQUITECTURA-IA.md) +- [erp-core/MGN-021-whatsapp](../../../../../erp-core/docs/05-fase-ia/MGN-021-whatsapp-business/) +- [Meta Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api) + +--- + +*Modulo MGN-021 - WhatsApp Business | Clinica Dental* +*Propagado desde erp-core via erp-clinicas* +*Actualizado: 2026-01-13* diff --git a/docs/05-fase-ia/MGN-021-whatsapp-business/_MAP.md b/docs/05-fase-ia/MGN-021-whatsapp-business/_MAP.md new file mode 100644 index 0000000..0f146fe --- /dev/null +++ b/docs/05-fase-ia/MGN-021-whatsapp-business/_MAP.md @@ -0,0 +1,126 @@ +--- +id: MAP-MGN-021-whatsapp-business +title: Mapa de Navegacion - WhatsApp Business +type: NavigationMap +status: Draft +version: 1.0.0 +created_date: 2026-01-13 +updated_date: 2026-01-13 +--- + +# Mapa de Navegacion - MGN-021: WhatsApp Business Dental + +## Estructura del Modulo + +``` +MGN-021-whatsapp-business/ ++-- README.md <- Vision general ++-- _MAP.md <- ESTE ARCHIVO +| ++-- requerimientos/ +| +-- INDICE-RF-WHATSAPP.md +| +-- RF-WHATSAPP-001.md <- Recepcion mensajes +| +-- RF-WHATSAPP-002.md <- Procesamiento LLM +| +-- RF-WHATSAPP-003.md <- Templates dentales +| ++-- especificaciones/ +| +-- INDICE-ET-WHATSAPP.md +| +-- ET-WHATSAPP-DATABASE.md +| +-- ET-WHATSAPP-BACKEND.md +| +-- ET-WHATSAPP-FRONTEND.md +| ++-- historias-usuario/ +| +-- INDICE-US-WHATSAPP.md +| ++-- implementacion/ + +-- TRACEABILITY.yml +``` + +--- + +## Templates WhatsApp Dentales + +| Template | Uso | Aprobado Meta | +|----------|-----|---------------| +| recordatorio_cita_dental | 24h antes de cita | Pendiente | +| confirmacion_tratamiento | Post-procedimiento | Pendiente | +| instrucciones_postoperatorio | Cuidados especiales | Pendiente | + +--- + +## Herramientas MCP Disponibles + +| Tool | Descripcion | +|------|-------------| +| consultar_odontograma | Ver piezas dentales | +| consultar_historial_dental | Tratamientos previos | +| agendar_cita_dental | Programar cita | +| verificar_disponibilidad | Horarios libres | +| consultar_cita_proxima | Proxima cita | +| cancelar_reprogramar_cita | Modificar cita | + +--- + +## Flujo de Mensaje + +``` +Paciente envia mensaje + | + v + Webhook recibe + | + v + LLM procesa (system prompt dental) + | + v + MCP ejecuta tools + | + v + LLM genera respuesta + | + v + Paciente recibe +``` + +--- + +## Disponibilidad por Plan + +| Plan | Acceso WhatsApp IA | +|------|-------------------| +| Consultorio | No | +| Clinica | No | +| Centro Dental | Si | + +--- + +## Indice de Documentos + +### Requerimientos + +| ID | Descripcion | Estado | +|----|-------------|--------| +| RF-WHATSAPP-001 | Recepcion de mensajes | Draft | +| RF-WHATSAPP-002 | Procesamiento LLM | Draft | +| RF-WHATSAPP-003 | Templates dentales | Draft | + +### Especificaciones + +| ID | Descripcion | Estado | +|----|-------------|--------| +| ET-WHATSAPP-DATABASE | Modelo de datos | Draft | +| ET-WHATSAPP-BACKEND | Webhook y servicios | Draft | +| ET-WHATSAPP-FRONTEND | UI bandeja | Draft | + +--- + +## Normativas + +- NOM-013-SSA2-2015: No diagnosticar +- LFPDPPP: Expediente es dato sensible +- Consentimiento WhatsApp requerido + +--- + +*Mapa | MGN-021-whatsapp-business | Clinica Dental* +*Actualizado: 2026-01-13* diff --git a/docs/05-fase-ia/MGN-022-mcp-server/README.md b/docs/05-fase-ia/MGN-022-mcp-server/README.md new file mode 100644 index 0000000..60f9c37 --- /dev/null +++ b/docs/05-fase-ia/MGN-022-mcp-server/README.md @@ -0,0 +1,316 @@ +--- +id: MGN-022-mcp-server +title: MCP Server para Clinica Dental +type: Module +status: Draft +priority: P0 +phase: 05-fase-ia +version: 1.0.0 +created_date: 2026-01-13 +updated_date: 2026-01-13 +normativas: [NOM-013-SSA2-2015, NOM-004-SSA3-2012, COFEPRIS] +--- + +# MGN-022: MCP Server para Clinica Dental + +**Modulo:** MGN-022 +**Nombre:** MCP Server (Model Context Protocol) Dental +**Fase:** 05 - Inteligencia Artificial +**Story Points:** 55 SP +**Estado:** En Diseno +**Ultima actualizacion:** 2026-01-13 + +--- + +## Descripcion + +Modulo que implementa un servidor MCP (Model Context Protocol) siguiendo el estandar de Anthropic, especializado en odontologia. Expone herramientas (tools) de negocio dental a los modelos de lenguaje de manera estandarizada, permitiendo que agentes IA interactuen con el sistema para consultar odontogramas, gestionar citas, registrar tratamientos y administrar presupuestos dentales. + +--- + +## Funcionalidades Principales + +1. **Odontograma Tools** - Consulta y actualizacion de odontogramas usando nomenclatura FDI +2. **Tratamientos Tools** - Registro y consulta de tratamientos dentales +3. **Citas Tools** - Gestion completa de citas dentales +4. **Pacientes Tools** - Busqueda y consulta de pacientes +5. **Presupuestos Tools** - Generacion y consulta de presupuestos +6. **Historial Tools** - Consulta de historial clinico dental +7. **MCP Resources** - Recursos expuestos (catalogo tratamientos, precios) +8. **Tool Call Logging** - Registro de llamadas para auditoria (NOM-004) + +--- + +## Herramientas MCP Odontologicas + +### Odontograma Tools (4 herramientas) + +| Tool | Descripcion | Parametros | +|------|-------------|------------| +| `consultar_odontograma` | Ver estado completo de piezas dentales | paciente_id | +| `consultar_pieza_dental` | Detalle de una pieza especifica | paciente_id, pieza (ej: "16") | +| `registrar_estado_pieza` | Actualizar estado de pieza | paciente_id, pieza, estado, cara?, notas? | +| `historial_pieza` | Tratamientos previos en pieza | paciente_id, pieza | + +**Estados de Pieza Soportados:** +- `sano` - Sin patologia +- `caries` - Caries activa +- `obturacion_resina` - Obturacion con resina +- `obturacion_amalgama` - Obturacion con amalgama +- `endodoncia` - Tratamiento de conducto +- `corona` - Protesis fija +- `puente_pilar` - Pilar de puente +- `puente_pontico` - Pontico de puente +- `implante` - Implante dental +- `ausente` - Pieza ausente +- `extraccion_indicada` - Extraccion planificada + +**Caras Dentales (parametro cara):** +- `M` - Mesial +- `D` - Distal +- `O` - Oclusal (molares/premolares) +- `I` - Incisal (incisivos/caninos) +- `V` - Vestibular +- `L` - Lingual +- `P` - Palatino + +### Tratamientos Tools (4 herramientas) + +| Tool | Descripcion | Parametros | +|------|-------------|------------| +| `registrar_tratamiento` | Documentar tratamiento realizado | paciente_id, tipo, piezas[], doctor_id, notas? | +| `consultar_tratamiento` | Detalle de un tratamiento | tratamiento_id | +| `listar_tratamientos_paciente` | Historial de tratamientos | paciente_id, desde?, hasta? | +| `catalogo_tratamientos` | Lista de tratamientos disponibles | categoria? | + +**Categorias de Tratamiento:** +- `preventivo` - Limpiezas, selladores, fluor +- `restaurador` - Resinas, amalgamas, incrustaciones +- `endodoncia` - Tratamientos de conducto +- `periodoncia` - Raspados, cirugia periodontal +- `cirugia` - Extracciones, implantes +- `ortodoncia` - Brackets, alineadores +- `protesis` - Coronas, puentes, dentaduras +- `estetica` - Blanqueamiento, carillas + +### Citas Tools (5 herramientas) + +| Tool | Descripcion | Parametros | +|------|-------------|------------| +| `agendar_cita_dental` | Crear nueva cita | paciente_id, fecha, hora, tratamiento_tipo, doctor_id?, sillon? | +| `consultar_cita` | Detalle de cita | cita_id | +| `consultar_citas_paciente` | Citas de un paciente | paciente_id, estado? | +| `verificar_disponibilidad_sillon` | Horarios libres | fecha, sillon?, doctor_id? | +| `cancelar_reprogramar_cita` | Modificar cita | cita_id, accion, nueva_fecha?, nueva_hora? | + +### Pacientes Tools (3 herramientas) + +| Tool | Descripcion | Parametros | +|------|-------------|------------| +| `buscar_paciente` | Buscar por nombre/telefono | query, limit? | +| `consultar_paciente` | Datos completos del paciente | paciente_id | +| `consultar_historial_dental` | Historial clinico completo | paciente_id | + +### Presupuestos Tools (3 herramientas) + +| Tool | Descripcion | Parametros | +|------|-------------|------------| +| `generar_presupuesto_dental` | Crear presupuesto | paciente_id, tratamientos[], descuento? | +| `consultar_presupuesto` | Detalle de presupuesto | presupuesto_id | +| `aprobar_rechazar_presupuesto` | Cambiar estado | presupuesto_id, decision, notas? | + +--- + +## Recursos MCP Dentales + +| URI | Descripcion | Retorna | +|-----|-------------|---------| +| `dental://catalogo/tratamientos` | Catalogo de tratamientos con precios | Array de tratamientos | +| `dental://catalogo/materiales` | Materiales dentales disponibles | Array de materiales | +| `dental://config/clinica` | Configuracion de la clinica | Nombre, horarios, sillones | +| `dental://config/doctores` | Lista de doctores | Array de doctores y especialidades | +| `dental://nomenclatura/fdi` | Referencia nomenclatura FDI | Cuadrantes y piezas | + +--- + +## Endpoints API + +| Metodo | Endpoint | Descripcion | +|--------|----------|-------------| +| POST | /api/v1/mcp/tools/call | Ejecutar una herramienta MCP | +| GET | /api/v1/mcp/tools | Listar herramientas disponibles | +| GET | /api/v1/mcp/tools/:name | Obtener definicion de herramienta | +| GET | /api/v1/mcp/resources | Listar recursos disponibles | +| GET | /api/v1/mcp/resources/:uri | Obtener recurso | +| GET | /api/v1/mcp/tool-calls | Historial de llamadas (auditoria) | +| GET | /api/v1/mcp/tool-calls/:id | Detalle de una llamada | + +--- + +## Ejemplos de Uso + +### Consultar Odontograma + +```json +// Request +{ + "tool": "consultar_odontograma", + "parameters": { + "paciente_id": "pac_123" + } +} + +// Response +{ + "paciente": "Maria Garcia", + "fecha_actualizacion": "2026-01-13", + "piezas": [ + { "numero": "11", "estado": "sano" }, + { "numero": "16", "estado": "obturacion_resina", "caras": ["O", "M"], "fecha": "2025-06-15" }, + { "numero": "36", "estado": "endodoncia", "fecha": "2024-03-20" }, + { "numero": "46", "estado": "caries", "caras": ["O"], "notas": "Caries oclusal, indicada resina" } + ], + "piezas_ausentes": ["18", "28", "38", "48"], + "tratamientos_pendientes": [ + { "pieza": "46", "tratamiento": "Resina compuesta" } + ] +} +``` + +### Agendar Cita Dental + +```json +// Request +{ + "tool": "agendar_cita_dental", + "parameters": { + "paciente_id": "pac_123", + "fecha": "2026-01-20", + "hora": "10:00", + "tratamiento_tipo": "resina", + "doctor_id": "doc_456", + "sillon": 2 + } +} + +// Response +{ + "cita_id": "cita_789", + "confirmada": true, + "fecha": "2026-01-20", + "hora": "10:00", + "duracion_minutos": 45, + "doctor": "Dra. Rodriguez", + "sillon": 2, + "tratamiento": "Resina compuesta", + "recordatorio_programado": true +} +``` + +--- + +## Dependencias + +**Este modulo depende de:** +- MGN-001 Auth (autenticacion, clinica_id) +- MGN-004 Tenants (multi-tenant, aislamiento por clinica) +- DENTAL-001 Odontograma (consulta/actualizacion) +- DENTAL-002 Tratamientos (registro/consulta) +- Citas (agendamiento) +- Pacientes (busqueda/consulta) + +**Modulos que dependen de este:** +- MGN-021 WhatsApp Business (chatbots con herramientas MCP) +- MGN-020 AI Integration (agentes IA) + +--- + +## Arquitectura + +``` + +-------------------+ + | Clientes MCP | + +-------------------+ + | AI Agents | + | WhatsApp Service | + | API Externa | + +---------+---------+ + | + v + +-------------------+ + | MCP Server | + +-------------------+ + | MCP Controller | + | Tool Registry | + | Tool Executor | + | Audit Logger | + +---------+---------+ + | + +---------------------+---------------------+ + | | | | | + v v v v v ++------------+ +--------+ +--------+ +----------+ +--------+ +| Odontograma| | Citas | | Tratam.| | Pacientes| | Presup.| +| Tools | | Tools | | Tools | | Tools | | Tools | ++------------+ +--------+ +--------+ +----------+ +--------+ + | | | | | + v v v v v ++------------+ +--------+ +--------+ +----------+ +--------+ +| Odontograma| | Citas | | Tratam.| | Pacientes| | Presup.| +| Service | | Service| | Service| | Service | | Service| ++------------+ +--------+ +--------+ +----------+ +--------+ +``` + +--- + +## Seguridad y Normativas + +### Seguridad General + +- Todas las herramientas requieren autenticacion JWT +- Aislamiento por clinica (RLS) +- Rate limiting por clinica +- Sanitizacion de inputs +- Validacion de permisos por herramienta + +### NOM-004-SSA3-2012 (Expediente Clinico) + +- Registro completo de todas las llamadas a herramientas +- Trazabilidad de consultas y modificaciones +- Almacenamiento seguro de logs + +### NOM-013-SSA2-2015 (Salud Bucal) + +- Uso correcto de nomenclatura FDI +- Registro adecuado de tratamientos +- Protocolos de atencion + +### COFEPRIS + +- Registro de materiales utilizados +- Trazabilidad de insumos +- Bitacora de procedimientos + +--- + +## Documentacion + +- [Mapa del Modulo](./_MAP.md) +- [Requerimientos](./requerimientos/) +- [Especificaciones](./especificaciones/) +- [Historias de Usuario](./historias-usuario/) +- [Trazabilidad](./implementacion/TRACEABILITY.yml) + +--- + +## Referencias + +- **Fuente:** [erp-core/MGN-022-mcp-server](../../../../../erp-core/docs/05-fase-ia/MGN-022-mcp-server/) +- **MCP Spec:** [Model Context Protocol](https://modelcontextprotocol.io/) +- **Anthropic MCP:** [Anthropic MCP Docs](https://docs.anthropic.com/en/docs/mcp) + +--- + +*Modulo MGN-022 - MCP Server | Clinica Dental* +*Propagado desde erp-core via erp-clinicas* +*Actualizado: 2026-01-13* diff --git a/docs/05-fase-ia/MGN-022-mcp-server/_MAP.md b/docs/05-fase-ia/MGN-022-mcp-server/_MAP.md new file mode 100644 index 0000000..6c1c346 --- /dev/null +++ b/docs/05-fase-ia/MGN-022-mcp-server/_MAP.md @@ -0,0 +1,167 @@ +--- +id: MAP-MGN-022-mcp-server +title: Mapa de Navegacion - MCP Server +type: NavigationMap +status: Draft +version: 1.0.0 +created_date: 2026-01-13 +updated_date: 2026-01-13 +--- + +# Mapa de Navegacion - MGN-022: MCP Server Dental + +## Estructura del Modulo + +``` +MGN-022-mcp-server/ ++-- README.md <- Vision general ++-- _MAP.md <- ESTE ARCHIVO +| ++-- requerimientos/ +| +-- INDICE-RF-MCP.md +| +-- RF-MCP-001.md <- Odontograma Tools +| +-- RF-MCP-002.md <- Tratamientos Tools +| +-- RF-MCP-003.md <- Citas Tools +| +-- RF-MCP-004.md <- Auditoria NOM-004 +| ++-- especificaciones/ +| +-- INDICE-ET-MCP.md +| +-- ET-MCP-DATABASE.md +| +-- ET-MCP-BACKEND.md +| +-- ET-MCP-TOOLS.md <- Definicion de herramientas +| ++-- historias-usuario/ +| +-- INDICE-US-MCP.md +| ++-- implementacion/ + +-- TRACEABILITY.yml +``` + +--- + +## Herramientas MCP Dentales + +### Odontograma (4 tools) + +| Tool | Descripcion | +|------|-------------| +| consultar_odontograma | Estado completo de piezas | +| consultar_pieza_dental | Detalle de una pieza | +| registrar_estado_pieza | Actualizar estado | +| historial_pieza | Tratamientos en pieza | + +### Tratamientos (4 tools) + +| Tool | Descripcion | +|------|-------------| +| registrar_tratamiento | Documentar tratamiento | +| consultar_tratamiento | Detalle de tratamiento | +| listar_tratamientos_paciente | Historial | +| catalogo_tratamientos | Catalogo disponible | + +### Citas (5 tools) + +| Tool | Descripcion | +|------|-------------| +| agendar_cita_dental | Crear cita | +| consultar_cita | Detalle de cita | +| consultar_citas_paciente | Citas del paciente | +| verificar_disponibilidad_sillon | Horarios libres | +| cancelar_reprogramar_cita | Modificar cita | + +### Pacientes (3 tools) + +| Tool | Descripcion | +|------|-------------| +| buscar_paciente | Buscar por nombre/telefono | +| consultar_paciente | Datos del paciente | +| consultar_historial_dental | Historial completo | + +### Presupuestos (3 tools) + +| Tool | Descripcion | +|------|-------------| +| generar_presupuesto_dental | Crear presupuesto | +| consultar_presupuesto | Ver presupuesto | +| aprobar_rechazar_presupuesto | Cambiar estado | + +--- + +## Recursos MCP + +| URI | Descripcion | +|-----|-------------| +| dental://catalogo/tratamientos | Catalogo con precios | +| dental://catalogo/materiales | Materiales disponibles | +| dental://config/clinica | Config de clinica | +| dental://config/doctores | Lista de doctores | +| dental://nomenclatura/fdi | Referencia FDI | + +--- + +## Nomenclatura FDI + +### Cuadrantes + +| Cuadrante | Descripcion | Piezas | +|-----------|-------------|--------| +| 1 | Superior derecho | 11-18 | +| 2 | Superior izquierdo | 21-28 | +| 3 | Inferior izquierdo | 31-38 | +| 4 | Inferior derecho | 41-48 | + +### Piezas Deciduas + +| Cuadrante | Piezas | +|-----------|--------| +| 5 | 51-55 | +| 6 | 61-65 | +| 7 | 71-75 | +| 8 | 81-85 | + +--- + +## Estados de Pieza + +- `sano` - Sin patologia +- `caries` - Caries activa +- `obturacion_resina` - Resina +- `obturacion_amalgama` - Amalgama +- `endodoncia` - Tratamiento de conducto +- `corona` - Protesis fija +- `implante` - Implante dental +- `ausente` - Pieza ausente + +--- + +## Normativas + +- **NOM-004-SSA3-2012**: Auditoria de llamadas +- **NOM-013-SSA2-2015**: Nomenclatura FDI +- **COFEPRIS**: Registro de materiales + +--- + +## Indice de Documentos + +### Requerimientos + +| ID | Descripcion | Estado | +|----|-------------|--------| +| RF-MCP-001 | Odontograma Tools | Draft | +| RF-MCP-002 | Tratamientos Tools | Draft | +| RF-MCP-003 | Citas Tools | Draft | +| RF-MCP-004 | Auditoria NOM-004 | Draft | + +### Especificaciones + +| ID | Descripcion | Estado | +|----|-------------|--------| +| ET-MCP-DATABASE | Modelo de datos | Draft | +| ET-MCP-BACKEND | API y servicios | Draft | +| ET-MCP-TOOLS | Definicion de tools | Draft | + +--- + +*Mapa | MGN-022-mcp-server | Clinica Dental* +*Actualizado: 2026-01-13* diff --git a/docs/05-fase-ia/README.md b/docs/05-fase-ia/README.md new file mode 100644 index 0000000..a74039e --- /dev/null +++ b/docs/05-fase-ia/README.md @@ -0,0 +1,172 @@ +--- +id: fase-05-ia +title: Fase 05 - Inteligencia Artificial para Clinica Dental +type: PhaseOverview +status: Draft +version: 1.0.0 +created_date: 2026-01-13 +updated_date: 2026-01-13 +normativas: [NOM-013-SSA2-2015, COFEPRIS, LFPDPPP] +--- + +# Fase 05: Inteligencia Artificial para Clinica Dental + +## Descripcion + +Esta fase implementa capacidades de Inteligencia Artificial especializadas para el dominio odontologico. Incluye un gateway LLM multi-proveedor, integracion con WhatsApp Business para comunicacion con pacientes, y un servidor MCP con herramientas especificas para consultar odontogramas, registrar tratamientos y gestionar citas dentales. + +--- + +## Modulos de la Fase + +| ID | Modulo | Descripcion | Prioridad | +|----|--------|-------------|-----------| +| MGN-020 | [AI Integration](./MGN-020-ai-integration/) | Gateway LLM multi-proveedor | P1 | +| MGN-021 | [WhatsApp Business](./MGN-021-whatsapp-business/) | Comunicacion IA con pacientes | P1 | +| MGN-022 | [MCP Server](./MGN-022-mcp-server/) | Herramientas MCP odontologicas | P0 | + +--- + +## Capacidades IA Especializadas + +### Asistente Dental Virtual + +El asistente IA esta especializado en: +- Consulta de odontogramas y estado de piezas dentales +- Explicacion de tratamientos y procedimientos +- Recordatorios de citas y seguimiento de tratamientos +- Instrucciones postoperatorias personalizadas +- Respuesta a dudas sobre higiene bucal + +### System Prompt Especializado + +``` +Eres el asistente virtual de {{CLINICA_DENTAL}}, una clinica dental en Mexico. + +Especialidades: +- Odontologia general y preventiva +- Ortodoncia y alineadores +- Endodoncia y tratamientos de conductos +- Periodoncia y cirugia +- Estetica dental + +Conocimientos: +- Nomenclatura dental FDI (sistema de dos digitos) +- Cuadrantes: 1-Superior derecho, 2-Superior izq, 3-Inferior izq, 4-Inferior der +- Piezas permanentes: 11-18, 21-28, 31-38, 41-48 +- Piezas deciduas: 51-55, 61-65, 71-75, 81-85 + +Reglas: +1. Responde en espanol mexicano profesional pero calido +2. Nunca des diagnosticos, siempre recomienda visita al odontologo +3. Explica procedimientos de forma clara y sin tecnicismos excesivos +4. Para citas, usa el calendario del consultorio +5. Respeta la confidencialidad del expediente clinico +6. Cumple con NOM-013-SSA2-2015 y normativas COFEPRIS +``` + +--- + +## Herramientas MCP Odontologicas + +| Herramienta | Descripcion | Categoria | +|-------------|-------------|-----------| +| `consultar_odontograma` | Ver estado completo de piezas dentales | Diagnostico | +| `registrar_tratamiento` | Registrar procedimiento realizado | Tratamientos | +| `agendar_cita_dental` | Programar cita con disponibilidad | Citas | +| `consultar_historial_dental` | Ver historial de tratamientos | Expediente | +| `verificar_disponibilidad_sillon` | Consultar agenda por sillon | Citas | +| `generar_presupuesto_dental` | Crear presupuesto de tratamiento | Facturacion | + +--- + +## WhatsApp Templates Dentales + +### Recordatorio de Cita +``` +Hola {{NOMBRE}}, te recordamos tu cita dental: + +Fecha: {{FECHA}} +Hora: {{HORA}} +Doctor(a): {{DOCTOR}} +Tratamiento: {{TRATAMIENTO}} + +Clinica Dental {{CLINICA_DENTAL}} +Confirma tu asistencia respondiendo SI o NO. +``` + +### Confirmacion de Tratamiento +``` +{{NOMBRE}}, tu tratamiento ha sido registrado: + +Pieza(s): {{PIEZAS}} +Procedimiento: {{PROCEDIMIENTO}} +Proxima cita: {{PROXIMA_CITA}} + +Instrucciones de cuidado: +{{INSTRUCCIONES}} + +Cualquier duda, contactanos. +``` + +### Instrucciones Postoperatorio +``` +{{NOMBRE}}, instrucciones post-{{PROCEDIMIENTO}}: + +1. {{INSTRUCCION_1}} +2. {{INSTRUCCION_2}} +3. {{INSTRUCCION_3}} + +Medicamentos recetados: +{{MEDICAMENTOS}} + +Si presentas {{SINTOMAS_ALERTA}}, acude de inmediato. +Tel. emergencias: {{TELEFONO}} +``` + +--- + +## Normativas y Privacidad + +### NOM-013-SSA2-2015 +- Trazabilidad de tratamientos +- Registros de procedimientos +- Protocolos de atencion + +### COFEPRIS +- Registro de materiales dentales +- Trazabilidad de insumos +- Bitacora de procedimientos + +### LFPDPPP (Datos Personales) +- Expediente clinico como dato sensible +- Consentimiento para uso de IA +- No almacenar datos biometricos sin autorizacion + +--- + +## Estructura de Directorios + +``` +05-fase-ia/ ++-- README.md <- ESTE ARCHIVO ++-- _MAP.md <- Indice de navegacion ++-- MGN-020-ai-integration/ <- Gateway LLM ++-- MGN-021-whatsapp-business/ <- Comunicacion pacientes ++-- MGN-022-mcp-server/ <- Herramientas MCP dentales +``` + +--- + +## Referencias + +- [ARQUITECTURA-IA.md](../00-vision-general/ARQUITECTURA-IA.md) - Arquitectura IA +- [erp-core/05-fase-ia](../../../../erp-core/docs/05-fase-ia/) - Documentacion origen +- [OpenRouter Docs](https://openrouter.ai/docs) - Gateway LLM +- [Meta WhatsApp Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api) + +--- + +*Fase 05 - IA | Clinica Dental* +*Propagado desde erp-core via erp-clinicas* +*Actualizado: 2026-01-13* diff --git a/docs/05-fase-ia/_MAP.md b/docs/05-fase-ia/_MAP.md new file mode 100644 index 0000000..e00d775 --- /dev/null +++ b/docs/05-fase-ia/_MAP.md @@ -0,0 +1,115 @@ +--- +id: MAP-fase-05-ia +title: Mapa de Navegacion - Fase 05 IA +type: NavigationMap +status: Draft +version: 1.0.0 +created_date: 2026-01-13 +updated_date: 2026-01-13 +--- + +# Mapa de Navegacion - Fase 05: Inteligencia Artificial + +## Estructura de la Fase + +``` +05-fase-ia/ ++-- README.md <- Vision general de la fase ++-- _MAP.md <- ESTE ARCHIVO +| ++-- MGN-020-ai-integration/ <- Gateway LLM +| +-- README.md <- Vision del modulo +| +-- _MAP.md <- Indice del modulo +| +-- requerimientos/ <- RFs de AI +| +-- especificaciones/ <- ETs tecnicas +| +-- historias-usuario/ <- User stories +| +-- implementacion/ <- Trazabilidad +| ++-- MGN-021-whatsapp-business/ <- WhatsApp + IA +| +-- README.md <- Vision del modulo +| +-- _MAP.md <- Indice del modulo +| +-- ... <- Subdirectorios +| ++-- MGN-022-mcp-server/ <- Herramientas MCP + +-- README.md <- Vision del modulo + +-- _MAP.md <- Indice del modulo + +-- ... <- Subdirectorios +``` + +--- + +## Indice de Modulos + +| Modulo | Descripcion | Estado | Prioridad | +|--------|-------------|--------|-----------| +| [MGN-020-ai-integration](./MGN-020-ai-integration/) | Gateway LLM multi-proveedor | Draft | P1 | +| [MGN-021-whatsapp-business](./MGN-021-whatsapp-business/) | Comunicacion IA con pacientes | Draft | P1 | +| [MGN-022-mcp-server](./MGN-022-mcp-server/) | Herramientas MCP odontologicas | Draft | P0 | + +--- + +## Flujo de Navegacion Recomendado + +### Para Entender la Fase + +``` +1. README.md -> Vision general IA +2. MGN-022-mcp-server/README.md -> Herramientas disponibles +3. MGN-020-ai-integration/README.md -> Gateway LLM +4. MGN-021-whatsapp-business/README.md -> WhatsApp +``` + +### Para Implementar + +``` +1. MGN-020-ai-integration/ -> Configurar OpenRouter +2. MGN-022-mcp-server/ -> Implementar tools dentales +3. MGN-021-whatsapp-business/ -> Configurar Meta API +``` + +--- + +## Herramientas MCP Odontologicas + +| Tool | Categoria | Descripcion | +|------|-----------|-------------| +| `consultar_odontograma` | Diagnostico | Ver piezas dentales y estados | +| `registrar_tratamiento` | Tratamiento | Documentar procedimiento | +| `agendar_cita_dental` | Citas | Programar con disponibilidad | +| `consultar_historial_dental` | Expediente | Historial del paciente | +| `verificar_disponibilidad` | Citas | Agenda de sillones | +| `generar_presupuesto` | Facturacion | Cotizacion de tratamiento | + +--- + +## Templates WhatsApp Dentales + +| Template | Uso | +|----------|-----| +| `recordatorio_cita_dental` | 24h antes de cita | +| `confirmacion_tratamiento` | Post-procedimiento | +| `instrucciones_postoperatorio` | Cuidados especiales | + +--- + +## Privacidad y Normativas + +- **NOM-013-SSA2-2015**: Registros de tratamientos +- **COFEPRIS**: Materiales y procedimientos +- **LFPDPPP**: Expediente clinico como dato sensible +- **Consentimiento IA**: Requerido para procesamiento + +--- + +## Referencias Cruzadas + +| Documento | Ubicacion | Descripcion | +|-----------|-----------|-------------| +| Arquitectura IA | ../00-vision-general/ | Arquitectura general | +| Origen erp-core | erp-core/docs/05-fase-ia/ | Documentacion base | +| OpenRouter | openrouter.ai/docs | Gateway LLM | + +--- + +*Mapa de Navegacion | Fase 05 IA | Clinica Dental* +*Actualizado: 2026-01-13* diff --git a/docs/_MAP.md b/docs/_MAP.md index c3390a1..980641d 100644 --- a/docs/_MAP.md +++ b/docs/_MAP.md @@ -2,8 +2,8 @@ **Proyecto:** clinica-dental **Tipo:** ERP Especializado (hereda de erp-clinicas) -**Fecha:** 2026-01-07 -**Estado:** Fase 0 - Preparacion +**Fecha:** 2026-01-13 +**Estado:** Fase 0 - Preparacion + Fases SaaS/IA Propagadas --- @@ -11,27 +11,42 @@ ``` docs/ -├── _MAP.md <- ESTE ARCHIVO -├── 00-vision-general/ -│ ├── README.md <- Indice de vision -│ └── VISION.md <- Vision estrategica [PENDIENTE] -│ -├── 02-definicion-modulos/ -│ ├── _MAP.md <- Indice de modulos [PENDIENTE] -│ ├── modulo-odontograma.md <- Odontograma digital [PENDIENTE] -│ ├── modulo-tratamientos.md <- Tratamientos dentales [PENDIENTE] -│ ├── modulo-ortodoncia.md <- Control ortodoncia [PENDIENTE] -│ ├── modulo-protesis.md <- Trabajos protesicos [PENDIENTE] -│ ├── modulo-endodoncia.md <- Tratamientos conductos [PENDIENTE] -│ ├── modulo-periodoncia.md <- Enfermedad periodontal [PENDIENTE] -│ ├── modulo-prevencion.md <- Profilaxis, selladores [PENDIENTE] -│ └── modulo-estetica.md <- Blanqueamiento, carillas [PENDIENTE] -│ -├── 03-especificaciones/ -│ └── ... (futuras especificaciones tecnicas) -│ -└── 90-transversal/ - └── ... (documentacion transversal) ++-- _MAP.md <- ESTE ARCHIVO ++-- 00-vision-general/ +| +-- README.md <- Indice de vision +| +-- VISION.md <- Vision estrategica [PENDIENTE] +| ++-- 02-definicion-modulos/ +| +-- _MAP.md <- Indice de modulos [PENDIENTE] +| +-- modulo-odontograma.md <- Odontograma digital [PENDIENTE] +| +-- modulo-tratamientos.md <- Tratamientos dentales [PENDIENTE] +| +-- modulo-ortodoncia.md <- Control ortodoncia [PENDIENTE] +| +-- modulo-protesis.md <- Trabajos protesicos [PENDIENTE] +| +-- modulo-endodoncia.md <- Tratamientos conductos [PENDIENTE] +| +-- modulo-periodoncia.md <- Enfermedad periodontal [PENDIENTE] +| +-- modulo-prevencion.md <- Profilaxis, selladores [PENDIENTE] +| +-- modulo-estetica.md <- Blanqueamiento, carillas [PENDIENTE] +| ++-- 04-fase-saas/ <- NUEVO: Capacidades SaaS +| +-- README.md <- Vision de fase SaaS +| +-- _MAP.md <- Indice de modulos SaaS +| +-- MGN-016-billing/ <- Facturacion y suscripciones +| +-- MGN-017-plans/ <- Planes dentales (Consultorio/Clinica/Centro) +| +-- MGN-018-webhooks/ <- Integraciones externas +| +-- MGN-019-feature-flags/ <- Control de features odontologicas +| ++-- 05-fase-ia/ <- NUEVO: Inteligencia Artificial +| +-- README.md <- Vision de fase IA +| +-- _MAP.md <- Indice de modulos IA +| +-- MGN-020-ai-integration/ <- Gateway LLM dental +| +-- MGN-021-whatsapp-business/ <- WhatsApp IA para pacientes +| +-- MGN-022-mcp-server/ <- Herramientas MCP odontologicas +| ++-- 03-especificaciones/ +| +-- ... (futuras especificaciones tecnicas) +| ++-- 90-transversal/ + +-- ... (documentacion transversal) ``` --- @@ -124,14 +139,76 @@ Nomenclatura FDI: --- +## Fase 04: Capacidades SaaS (Propagada desde erp-core) + +Modulos de monetizacion y suscripciones adaptados al dominio odontologico. + +| Modulo | Descripcion | Estado | +|--------|-------------|--------| +| [MGN-016-billing](./04-fase-saas/MGN-016-billing/) | Facturacion y suscripciones con Stripe | Propagado | +| [MGN-017-plans](./04-fase-saas/MGN-017-plans/) | Planes: Consultorio, Clinica, Centro Dental | Propagado | +| [MGN-018-webhooks](./04-fase-saas/MGN-018-webhooks/) | Webhooks para integraciones externas | Propagado | +| [MGN-019-feature-flags](./04-fase-saas/MGN-019-feature-flags/) | Feature flags odontologicos | Propagado | + +### Planes Dentales + +| Plan | Precio/mes | Sillones | Features Clave | +|------|------------|----------|----------------| +| Consultorio | $499 MXN | 1 | Odontograma basico | +| Clinica | $1,499 MXN | 5 | + Ortodoncia, Radiografias | +| Centro Dental | $3,999 MXN | Ilimitado | + IA, WhatsApp, Multi-sucursal | + +--- + +## Fase 05: Inteligencia Artificial (Propagada desde erp-core) + +Modulos de IA especializados en odontologia con herramientas MCP dentales. + +| Modulo | Descripcion | Estado | +|--------|-------------|--------| +| [MGN-020-ai-integration](./05-fase-ia/MGN-020-ai-integration/) | Gateway LLM con system prompt dental | Propagado | +| [MGN-021-whatsapp-business](./05-fase-ia/MGN-021-whatsapp-business/) | WhatsApp IA para comunicacion con pacientes | Propagado | +| [MGN-022-mcp-server](./05-fase-ia/MGN-022-mcp-server/) | Herramientas MCP: odontograma, citas, tratamientos | Propagado | + +### Herramientas MCP Odontologicas + +- `consultar_odontograma` - Ver estado de piezas dentales +- `registrar_tratamiento` - Documentar procedimiento +- `agendar_cita_dental` - Programar cita +- `consultar_historial_dental` - Historial del paciente +- `generar_presupuesto_dental` - Cotizacion de tratamiento + +### Templates WhatsApp Dentales + +- `recordatorio_cita_dental` - 24h antes de cita +- `confirmacion_tratamiento` - Post-procedimiento +- `instrucciones_postoperatorio` - Cuidados especiales + +--- + +## Normativas Aplicables + +| Normativa | Descripcion | Estado | +|-----------|-------------|--------| +| NOM-013-SSA2-2015 | Prevencion y control enfermedades bucales | Pendiente | +| NOM-004-SSA3-2012 | Expediente clinico | Pendiente | +| COFEPRIS | Regulacion sanitaria | Pendiente | +| LFPDPPP | Proteccion de datos personales | Pendiente | + +--- + ## Referencias - [CONTEXTO-PROYECTO.md](../orchestration/00-guidelines/CONTEXTO-PROYECTO.md) - [HERENCIA-ERP-CLINICAS.md](../orchestration/00-guidelines/HERENCIA-ERP-CLINICAS.md) - [PROXIMA-ACCION.md](../orchestration/PROXIMA-ACCION.md) - [CONTEXT-MAP.yml](../orchestration/CONTEXT-MAP.yml) +- [04-fase-saas/README.md](./04-fase-saas/README.md) - Vision SaaS +- [05-fase-ia/README.md](./05-fase-ia/README.md) - Vision IA +- [PROPAGATION-STATUS.yml](../../shared/mirrors/clinica-dental/PROPAGATION-STATUS.yml) - Estado de propagacion --- -**Ultima actualizacion:** 2026-01-07 -**Version:** 1.0.0 +**Ultima actualizacion:** 2026-01-13 +**Version:** 1.1.0 +**Propagacion:** PROP-CDT-002 (Fases SaaS + IA desde erp-core via erp-clinicas)