clinica-veterinaria/docs/02-definicion-modulos/modulo-vacunacion.md

# Modulo Vacunacion

**Proyecto:** clinica-veterinaria
**Modulo:** VET-002
**Prioridad:** P1 - Core
**Estado:** Especificacion
**Fecha:** 2026-01-07

---

## 1. DESCRIPCION GENERAL

El modulo de Vacunacion gestiona la cartilla digital de vacunas de cada mascota, incluyendo esquemas por especie/edad, recordatorios automaticos, control de lotes y generacion de certificados para SENASICA.

### Proposito
- Registro de vacunas aplicadas
- Esquemas automaticos por especie
- Alertas de proximas vacunas
- Control de lotes y caducidad
- Certificados oficiales
- Reporte a SENASICA (rabia)

### Alcance
- Todas las especies con vacunas
- Esquemas personalizables
- Recordatorios multicanal (email, SMS, push)
- Integracion con SENASICA
- Historial completo de inmunizaciones

---

## 2. ENTIDADES

### 2.1 vacuna (catalogo)

```yaml
tabla: veterinaria.vacunas
descripcion: "Catalogo de vacunas disponibles"

campos:
  - nombre: id
    tipo: UUID
    pk: true

  - nombre: tenant_id
    tipo: UUID
    not_null: true
    descripcion: "Null para vacunas globales"

  - nombre: codigo
    tipo: VARCHAR(20)
    unique: true
    descripcion: "Codigo interno"

  - nombre: nombre
    tipo: VARCHAR(200)
    not_null: true
    descripcion: "Nombre comercial"

  - nombre: nombre_generico
    tipo: VARCHAR(200)
    descripcion: "Nombre generico/principio activo"

  - nombre: fabricante
    tipo: VARCHAR(100)

  - nombre: especies_aplicables
    tipo: UUID[]
    descripcion: "Array de IDs de especies"

  - nombre: enfermedades_previene
    tipo: TEXT[]
    descripcion: "Enfermedades que previene"

  - nombre: via_administracion
    tipo: ENUM
    valores: ['subcutanea', 'intramuscular', 'intranasal', 'oral']

  - nombre: dosis_ml
    tipo: DECIMAL(4,2)
    descripcion: "Dosis estandar en ml"

  - nombre: requiere_refuerzo
    tipo: BOOLEAN
    default: true

  - nombre: intervalo_refuerzo_dias
    tipo: INTEGER
    descripcion: "Dias entre aplicaciones"

  - nombre: intervalo_anual_dias
    tipo: INTEGER
    default: 365
    descripcion: "Frecuencia de refuerzo anual"

  - nombre: edad_minima_semanas
    tipo: INTEGER
    descripcion: "Edad minima para aplicar"

  - nombre: obligatoria
    tipo: BOOLEAN
    default: false
    descripcion: "Si es obligatoria por ley"

  - nombre: reportar_senasica
    tipo: BOOLEAN
    default: false
    descripcion: "Si debe reportarse a SENASICA"

  - nombre: precio_sugerido
    tipo: DECIMAL(10,2)

  - nombre: activo
    tipo: BOOLEAN
    default: true

indices:
  - nombre: idx_vacuna_especies
    tipo: GIN
    campos: [especies_aplicables]
  - nombre: idx_vacuna_senasica
    campos: [reportar_senasica]
    where: "reportar_senasica = true"

seeds:
  # Caninos
  - {codigo: 'PARVO', nombre: 'Parvovirus Canino', especies: ['CAN'], obligatoria: false}
  - {codigo: 'MOQUILLO', nombre: 'Moquillo Canino', especies: ['CAN'], obligatoria: false}
  - {codigo: 'QUINTUPLE', nombre: 'Quintuple Canina', especies: ['CAN'], obligatoria: false}
  - {codigo: 'RABIA_CAN', nombre: 'Rabia Canina', especies: ['CAN'], obligatoria: true, reportar_senasica: true}
  - {codigo: 'BORDETELLA', nombre: 'Bordetella (Tos de Perrera)', especies: ['CAN'], obligatoria: false}

  # Felinos
  - {codigo: 'TRIPLE_FEL', nombre: 'Triple Felina', especies: ['FEL'], obligatoria: false}
  - {codigo: 'LEUCEMIA', nombre: 'Leucemia Felina', especies: ['FEL'], obligatoria: false}
  - {codigo: 'RABIA_FEL', nombre: 'Rabia Felina', especies: ['FEL'], obligatoria: true, reportar_senasica: true}
```

### 2.2 esquema_vacunacion

```yaml
tabla: veterinaria.esquemas_vacunacion
descripcion: "Esquemas de vacunacion por especie/edad"

campos:
  - nombre: id
    tipo: UUID
    pk: true

  - nombre: especie_id
    tipo: UUID
    fk: veterinaria.especies(id)
    not_null: true

  - nombre: nombre
    tipo: VARCHAR(100)
    not_null: true
    descripcion: "Ej: Cachorro, Adulto, Senior"

  - nombre: edad_inicio_semanas
    tipo: INTEGER
    descripcion: "Edad minima en semanas"

  - nombre: edad_fin_semanas
    tipo: INTEGER
    descripcion: "Edad maxima en semanas (null = sin limite)"

  - nombre: descripcion
    tipo: TEXT

  - nombre: activo
    tipo: BOOLEAN
    default: true

seeds:
  - {especie: 'CAN', nombre: 'Cachorro (0-16 sem)', edad_inicio: 0, edad_fin: 16}
  - {especie: 'CAN', nombre: 'Adulto (16+ sem)', edad_inicio: 16, edad_fin: null}
  - {especie: 'FEL', nombre: 'Gatito (0-16 sem)', edad_inicio: 0, edad_fin: 16}
  - {especie: 'FEL', nombre: 'Adulto (16+ sem)', edad_inicio: 16, edad_fin: null}
```

### 2.3 esquema_vacuna_detalle

```yaml
tabla: veterinaria.esquema_vacuna_detalle
descripcion: "Vacunas incluidas en cada esquema"

campos:
  - nombre: id
    tipo: UUID
    pk: true

  - nombre: esquema_id
    tipo: UUID
    fk: veterinaria.esquemas_vacunacion(id)
    not_null: true
    on_delete: CASCADE

  - nombre: vacuna_id
    tipo: UUID
    fk: veterinaria.vacunas(id)
    not_null: true

  - nombre: semana_aplicacion
    tipo: INTEGER
    descripcion: "Semana de edad para aplicar"

  - nombre: orden
    tipo: INTEGER
    descripcion: "Orden de prioridad"

  - nombre: es_refuerzo
    tipo: BOOLEAN
    default: false
    descripcion: "Si es refuerzo de aplicacion anterior"

indices:
  - nombre: uk_esquema_vacuna
    campos: [esquema_id, vacuna_id, semana_aplicacion]
    unique: true

seeds_cachorro:
  # Esquema cachorro canino
  - {esquema: 'Cachorro', vacuna: 'PARVO', semana: 6, orden: 1}
  - {esquema: 'Cachorro', vacuna: 'QUINTUPLE', semana: 8, orden: 2}
  - {esquema: 'Cachorro', vacuna: 'QUINTUPLE', semana: 12, orden: 3, es_refuerzo: true}
  - {esquema: 'Cachorro', vacuna: 'RABIA_CAN', semana: 16, orden: 4}
```

### 2.4 vacunacion (aplicacion)

```yaml
tabla: veterinaria.vacunaciones
descripcion: "Registro de vacunas aplicadas"

campos:
  - nombre: id
    tipo: UUID
    pk: true

  - nombre: tenant_id
    tipo: UUID
    not_null: true

  - nombre: mascota_id
    tipo: UUID
    fk: veterinaria.mascotas(id)
    not_null: true

  - nombre: vacuna_id
    tipo: UUID
    fk: veterinaria.vacunas(id)
    not_null: true

  - nombre: fecha_aplicacion
    tipo: DATE
    not_null: true

  - nombre: fecha_proxima
    tipo: DATE
    descripcion: "Fecha sugerida de proxima aplicacion"

  - nombre: lote
    tipo: VARCHAR(50)
    descripcion: "Numero de lote"

  - nombre: fecha_caducidad_lote
    tipo: DATE
    descripcion: "Caducidad del lote usado"

  - nombre: fabricante
    tipo: VARCHAR(100)

  - nombre: veterinario_id
    tipo: UUID
    fk: core.usuarios(id)
    not_null: true
    descripcion: "Quien aplico"

  - nombre: cedula_veterinario
    tipo: VARCHAR(20)
    descripcion: "Cedula profesional (para certificados)"

  - nombre: consulta_id
    tipo: UUID
    fk: veterinaria.consultas(id)
    descripcion: "Consulta donde se aplico (si aplica)"

  - nombre: dosis_aplicada_ml
    tipo: DECIMAL(4,2)

  - nombre: via_administracion
    tipo: ENUM
    valores: ['subcutanea', 'intramuscular', 'intranasal', 'oral']

  - nombre: sitio_aplicacion
    tipo: VARCHAR(50)
    descripcion: "Ej: muslo derecho, escapula"

  - nombre: reaccion_adversa
    tipo: BOOLEAN
    default: false

  - nombre: descripcion_reaccion
    tipo: TEXT

  - nombre: costo
    tipo: DECIMAL(10,2)

  - nombre: certificado_generado
    tipo: BOOLEAN
    default: false

  - nombre: certificado_url
    tipo: VARCHAR(500)

  - nombre: reportado_senasica
    tipo: BOOLEAN
    default: false

  - nombre: fecha_reporte_senasica
    tipo: TIMESTAMP

  - nombre: notas
    tipo: TEXT

  - nombre: created_at
    tipo: TIMESTAMP
    default: NOW()

indices:
  - nombre: idx_vacunacion_mascota
    campos: [mascota_id]
  - nombre: idx_vacunacion_fecha
    campos: [fecha_aplicacion DESC]
  - nombre: idx_vacunacion_proxima
    campos: [fecha_proxima]
    where: "fecha_proxima IS NOT NULL"
  - nombre: idx_vacunacion_senasica
    campos: [reportado_senasica, fecha_aplicacion]
    where: "reportado_senasica = false"

rls:
  - policy: "tenant_isolation"
    using: "tenant_id = current_tenant_id()"
```

### 2.5 recordatorio_vacuna

```yaml
tabla: veterinaria.recordatorios_vacunas
descripcion: "Recordatorios programados"

campos:
  - nombre: id
    tipo: UUID
    pk: true

  - nombre: vacunacion_id
    tipo: UUID
    fk: veterinaria.vacunaciones(id)
    not_null: true
    on_delete: CASCADE
    descripcion: "Vacunacion de referencia"

  - nombre: fecha_recordatorio
    tipo: DATE
    not_null: true
    descripcion: "Fecha para enviar recordatorio"

  - nombre: tipo
    tipo: ENUM
    valores: ['7_dias_antes', '3_dias_antes', '1_dia_antes', 'dia_programado', 'vencido']

  - nombre: canal
    tipo: ENUM
    valores: ['email', 'sms', 'push', 'whatsapp']

  - nombre: enviado
    tipo: BOOLEAN
    default: false

  - nombre: fecha_envio
    tipo: TIMESTAMP

  - nombre: error_envio
    tipo: TEXT

indices:
  - nombre: idx_recordatorio_fecha
    campos: [fecha_recordatorio]
    where: "enviado = false"
```

---

## 3. ESQUEMAS DE VACUNACION

### 3.1 Caninos (Perros)

```yaml
cachorro_canino:
  - semana_6:
      vacuna: "Parvovirus"
      nota: "Primera vacuna"
  - semana_8:
      vacuna: "Quintuple (Parvovirus, Moquillo, Hepatitis, Parainfluenza, Leptospirosis)"
      nota: "Inicio de esquema completo"
  - semana_12:
      vacuna: "Quintuple (Refuerzo)"
      nota: "Refuerzo obligatorio"
  - semana_16:
      vacuna: "Rabia"
      nota: "Obligatoria por ley"
      reportar_senasica: true
  - semana_16:
      vacuna: "Bordetella (opcional)"
      nota: "Recomendada para perros en contacto con otros"

adulto_canino:
  - anual:
      vacunas: ["Quintuple", "Rabia"]
      nota: "Refuerzos anuales"
  - cada_6_meses:
      vacuna: "Bordetella (opcional)"
      nota: "Para perros sociales"
```

### 3.2 Felinos (Gatos)

```yaml
gatito_felino:
  - semana_8:
      vacuna: "Triple Felina (Rinotraqueitis, Calicivirus, Panleucopenia)"
      nota: "Primera vacuna"
  - semana_12:
      vacuna: "Triple Felina (Refuerzo)"
      nota: "Refuerzo"
  - semana_12:
      vacuna: "Leucemia Felina"
      nota: "Segun riesgo"
  - semana_16:
      vacuna: "Rabia"
      nota: "Obligatoria"
      reportar_senasica: true

adulto_felino:
  - anual:
      vacunas: ["Triple Felina", "Rabia"]
  - anual_riesgo:
      vacuna: "Leucemia Felina"
      nota: "Solo gatos de exterior o conviviendo con positivos"
```

---

## 4. API ENDPOINTS

### Vacunaciones

```yaml
endpoints:
  - method: GET
    path: /api/v1/mascotas/{mascotaId}/vacunaciones
    descripcion: "Historial de vacunas de una mascota"
    query:
      desde: date
      hasta: date
    response: Array de vacunaciones con detalles

  - method: GET
    path: /api/v1/mascotas/{mascotaId}/vacunaciones/pendientes
    descripcion: "Vacunas pendientes segun esquema"
    response: Array de vacunas sugeridas con fecha

  - method: POST
    path: /api/v1/mascotas/{mascotaId}/vacunaciones
    descripcion: "Registrar aplicacion de vacuna"
    body:
      vacuna_id: string (requerido)
      fecha_aplicacion: date (requerido)
      lote: string
      fabricante: string
      via_administracion: string
      sitio_aplicacion: string
      dosis_ml: number
      costo: number
      notas: string
    response: Vacunacion registrada + proxima fecha

  - method: GET
    path: /api/v1/vacunaciones/{id}
    descripcion: "Detalle de una vacunacion"
    response: Vacunacion completa

  - method: PATCH
    path: /api/v1/vacunaciones/{id}/reaccion
    descripcion: "Registrar reaccion adversa"
    body:
      reaccion_adversa: boolean
      descripcion_reaccion: string
    response: Vacunacion actualizada
```

### Certificados

```yaml
  - method: GET
    path: /api/v1/vacunaciones/{id}/certificado
    descripcion: "Generar certificado PDF"
    response: PDF file

  - method: POST
    path: /api/v1/mascotas/{mascotaId}/cartilla
    descripcion: "Generar cartilla completa PDF"
    body:
      incluir_proximas: boolean
    response: PDF file
```

### Recordatorios

```yaml
  - method: GET
    path: /api/v1/recordatorios/pendientes
    descripcion: "Recordatorios pendientes de envio"
    query:
      fecha: date (default: hoy)
    response: Array de recordatorios

  - method: POST
    path: /api/v1/recordatorios/enviar
    descripcion: "Procesar y enviar recordatorios"
    body:
      fecha: date
    response: Resumen de envios
```

### SENASICA

```yaml
  - method: GET
    path: /api/v1/senasica/pendientes
    descripcion: "Vacunas de rabia pendientes de reportar"
    query:
      desde: date
      hasta: date
    response: Array de vacunaciones

  - method: POST
    path: /api/v1/senasica/reportar
    descripcion: "Generar reporte mensual SENASICA"
    body:
      mes: number
      anio: number
    response: Archivo de reporte + resumen
```

---

## 5. FLUJOS DE USUARIO

### 5.1 Aplicar Vacuna

```
1. Veterinario abre expediente de mascota
2. Ir a seccion "Vacunas"
3. Click "Nueva Vacunacion"
4. Sistema muestra:
   - Vacunas sugeridas segun edad/especie
   - Vacunas vencidas (alertas)
5. Seleccionar vacuna del catalogo
6. Completar datos:
   - Lote
   - Fabricante
   - Via de administracion
   - Sitio de aplicacion
7. Guardar
8. Sistema:
   - Calcula proxima fecha
   - Programa recordatorios
   - Si es rabia, marca para SENASICA
9. Ofrecer generar certificado
```

### 5.2 Verificar Esquema

```
1. Abrir expediente de mascota
2. Ir a seccion "Vacunas"
3. Vista de timeline muestra:
   - Vacunas aplicadas (verde)
   - Vacunas pendientes segun esquema (amarillo)
   - Vacunas vencidas (rojo)
4. Click en pendiente para aplicar
5. Click en aplicada para ver detalle/certificado
```

### 5.3 Procesar Recordatorios Diarios

```
1. Cron job diario (8am)
2. Sistema busca recordatorios con fecha = hoy
3. Por cada recordatorio:
   - Obtener datos de mascota y propietario
   - Preparar mensaje personalizado
   - Enviar por canal configurado
   - Marcar como enviado
4. Generar log de envios
5. Alertar errores a administrador
```

### 5.4 Generar Reporte SENASICA

```
1. Admin accede a seccion SENASICA
2. Selecciona mes/ano
3. Sistema genera reporte con:
   - Total vacunas de rabia aplicadas
   - Por especie (canino/felino)
   - Por municipio
   - Datos de veterinarios
4. Descargar en formato requerido
5. Marcar vacunaciones como reportadas
```

---

## 6. CERTIFICADO DE VACUNACION

### Contenido del Certificado

```yaml
certificado_vacunacion:
  encabezado:
    - Logo de clinica
    - Nombre de clinica
    - Direccion
    - Telefono
    - RFC

  datos_mascota:
    - Nombre
    - Especie y raza
    - Sexo
    - Edad
    - Color
    - Microchip (si tiene)
    - Foto

  datos_propietario:
    - Nombre completo
    - Direccion
    - Telefono

  datos_vacunacion:
    - Vacuna aplicada
    - Fecha de aplicacion
    - Lote
    - Fabricante
    - Fecha de proxima aplicacion
    - Via y sitio de administracion

  datos_veterinario:
    - Nombre completo
    - Cedula profesional
    - Firma digital

  pie:
    - Numero de folio
    - Fecha de emision
    - QR de verificacion
```

---

## 7. INTEGRACION SENASICA

### Requerimientos del Reporte

```yaml
reporte_senasica:
  frecuencia: "Mensual"
  plazo: "Primeros 5 dias del mes siguiente"

  datos_requeridos:
    - Numero de vacunas de rabia aplicadas
    - Desglose por especie (canino/felino)
    - Municipio de aplicacion
    - Clave de establecimiento
    - Datos del MVZ responsable

  formato:
    - Excel con plantilla oficial
    - O captura en sistema web SENASICA
```

---

## 8. VALIDACIONES

```yaml
validaciones:
  - regla: "Vacuna debe ser aplicable a la especie"
    condicion: vacuna.especies_aplicables NOT CONTAINS mascota.especie_id
    error: "Esta vacuna no aplica para esta especie"

  - regla: "Edad minima para aplicar"
    condicion: mascota.edad_semanas < vacuna.edad_minima_semanas
    error: "La mascota no tiene la edad minima para esta vacuna"

  - regla: "Lote no caducado"
    condicion: fecha_aplicacion > fecha_caducidad_lote
    error: "El lote de vacuna esta caducado"

  - regla: "Veterinario con cedula para rabia"
    condicion: vacuna.reportar_senasica AND NOT veterinario.cedula
    error: "Se requiere cedula profesional para vacunas de rabia"

  - regla: "No duplicar vacuna en mismo dia"
    condicion: EXISTS vacunacion con misma vacuna y fecha
    warning: "Ya existe una aplicacion de esta vacuna en la misma fecha"
```

---

## 9. DEPENDENCIAS

### Depende de
- `veterinaria.mascotas` - Paciente a vacunar
- `veterinaria.propietarios` - Para recordatorios
- `core.usuarios` - Veterinario que aplica
- `notificaciones` - Envio de recordatorios

### Dependientes
- `veterinaria.consultas` - Vinculo con consulta
- `reportes` - Estadisticas de vacunacion
- `facturacion` - Cobro de vacunas

---

**Documento creado:** 2026-01-07
**Autor:** Agente Orquestador Workspace
**Version:** 1.0.0