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

Modulo Mascotas

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

---

1. DESCRIPCION GENERAL

El modulo de Mascotas es el nucleo del sistema veterinario. Gestiona el registro de pacientes animales, su vinculacion con propietarios, datos clinicos basicos y seguimiento de peso/estado.

Proposito

• Registro completo de datos de cada mascota
• Vinculacion con propietarios (1 o multiples)
• Historial de pesos y mediciones
• Identificacion por microchip
• Base para expediente clinico

Alcance

• Multiples especies (canino, felino, aves, exoticos)
• Razas por especie
• Datos de identificacion (microchip)
• Estado reproductivo (esterilizado/entero)
• Fotos de identificacion
• Estados (activo, fallecido, perdido)

---

2. ENTIDADES

2.1 especie

tabla: veterinaria.especies
descripcion: "Catalogo de especies soportadas"

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

  - nombre: codigo
    tipo: VARCHAR(10)
    unique: true
    not_null: true
    descripcion: "CAN, FEL, AVE, REP, ROE, PEZ, EXO"

  - nombre: nombre
    tipo: VARCHAR(100)
    not_null: true
    descripcion: "Canino, Felino, Ave, etc"

  - nombre: nombre_cientifico
    tipo: VARCHAR(200)
    descripcion: "Nombre cientifico"

  - nombre: tiene_vacunas
    tipo: BOOLEAN
    default: true
    descripcion: "Si tiene esquema de vacunacion"

  - nombre: activo
    tipo: BOOLEAN
    default: true

seeds:
  - {codigo: 'CAN', nombre: 'Canino (Perro)', tiene_vacunas: true}
  - {codigo: 'FEL', nombre: 'Felino (Gato)', tiene_vacunas: true}
  - {codigo: 'AVE', nombre: 'Ave', tiene_vacunas: true}
  - {codigo: 'REP', nombre: 'Reptil', tiene_vacunas: false}
  - {codigo: 'ROE', nombre: 'Roedor', tiene_vacunas: false}
  - {codigo: 'PEZ', nombre: 'Pez', tiene_vacunas: false}
  - {codigo: 'EXO', nombre: 'Exotico', tiene_vacunas: true}

2.2 raza

tabla: veterinaria.razas
descripcion: "Catalogo de razas por especie"

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: "Nombre de la raza"

  - nombre: tamano
    tipo: ENUM
    valores: ['miniatura', 'pequeno', 'mediano', 'grande', 'gigante']
    descripcion: "Tamano tipico de la raza"

  - nombre: peso_promedio_kg
    tipo: DECIMAL(5,2)
    descripcion: "Peso promedio adulto"

  - nombre: esperanza_vida_anos
    tipo: INTEGER
    descripcion: "Anos de vida promedio"

  - nombre: activo
    tipo: BOOLEAN
    default: true

indices:
  - nombre: idx_raza_especie
    campos: [especie_id]
  - nombre: uk_raza_especie_nombre
    campos: [especie_id, nombre]
    unique: true

seeds_caninos:
  - {nombre: 'Labrador Retriever', tamano: 'grande', peso_promedio: 30}
  - {nombre: 'Pastor Aleman', tamano: 'grande', peso_promedio: 35}
  - {nombre: 'Golden Retriever', tamano: 'grande', peso_promedio: 32}
  - {nombre: 'Chihuahua', tamano: 'miniatura', peso_promedio: 2}
  - {nombre: 'Bulldog Frances', tamano: 'pequeno', peso_promedio: 12}
  - {nombre: 'Poodle', tamano: 'mediano', peso_promedio: 20}
  - {nombre: 'Mestizo', tamano: 'mediano', peso_promedio: 15}

seeds_felinos:
  - {nombre: 'Persa', tamano: 'mediano', peso_promedio: 5}
  - {nombre: 'Siames', tamano: 'mediano', peso_promedio: 4}
  - {nombre: 'Maine Coon', tamano: 'grande', peso_promedio: 8}
  - {nombre: 'Comun Europeo', tamano: 'mediano', peso_promedio: 4}
  - {nombre: 'Mestizo', tamano: 'mediano', peso_promedio: 4}

2.3 mascota

tabla: veterinaria.mascotas
descripcion: "Registro de pacientes animales"

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

  - nombre: tenant_id
    tipo: UUID
    not_null: true
    descripcion: "Multi-tenant"

  - nombre: nombre
    tipo: VARCHAR(100)
    not_null: true
    descripcion: "Nombre de la mascota"

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

  - nombre: raza_id
    tipo: UUID
    fk: veterinaria.razas(id)
    descripcion: "Raza (opcional si es mestizo)"

  - nombre: sexo
    tipo: ENUM
    valores: ['macho', 'hembra']
    not_null: true

  - nombre: fecha_nacimiento
    tipo: DATE
    descripcion: "Fecha exacta o aproximada"

  - nombre: fecha_nacimiento_aproximada
    tipo: BOOLEAN
    default: false
    descripcion: "Si la fecha es aproximada"

  - nombre: color
    tipo: VARCHAR(100)
    descripcion: "Color de pelaje/plumaje"

  - nombre: peso_actual_kg
    tipo: DECIMAL(6,2)
    descripcion: "Ultimo peso registrado"

  - nombre: peso_fecha
    tipo: DATE
    descripcion: "Fecha del ultimo peso"

  - nombre: microchip
    tipo: VARCHAR(50)
    unique: true
    descripcion: "Numero de microchip"

  - nombre: microchip_fecha
    tipo: DATE
    descripcion: "Fecha de colocacion"

  - nombre: esterilizado
    tipo: BOOLEAN
    default: false

  - nombre: fecha_esterilizacion
    tipo: DATE

  - nombre: foto_url
    tipo: VARCHAR(500)
    descripcion: "URL de foto principal"

  - nombre: caracteristicas_especiales
    tipo: TEXT
    descripcion: "Marcas, cicatrices, etc"

  - nombre: alergias
    tipo: TEXT[]
    descripcion: "Lista de alergias conocidas"

  - nombre: condiciones_cronicas
    tipo: TEXT[]
    descripcion: "Enfermedades cronicas"

  - nombre: estado
    tipo: ENUM
    valores: ['activo', 'fallecido', 'perdido', 'dado_de_baja', 'referido']
    default: 'activo'

  - nombre: fecha_fallecimiento
    tipo: DATE

  - nombre: causa_fallecimiento
    tipo: TEXT

  - nombre: notas
    tipo: TEXT
    descripcion: "Observaciones generales"

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

  - nombre: updated_at
    tipo: TIMESTAMP

indices:
  - nombre: idx_mascota_tenant
    campos: [tenant_id]
  - nombre: idx_mascota_especie
    campos: [especie_id]
  - nombre: idx_mascota_microchip
    campos: [microchip]
    where: "microchip IS NOT NULL"
  - nombre: idx_mascota_nombre
    campos: [tenant_id, nombre]

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

2.4 mascota_propietario

tabla: veterinaria.mascotas_propietarios
descripcion: "Relacion N:M entre mascotas y propietarios"

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

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

  - nombre: propietario_id
    tipo: UUID
    fk: veterinaria.propietarios(id)
    not_null: true
    on_delete: CASCADE

  - nombre: es_principal
    tipo: BOOLEAN
    default: false
    descripcion: "Si es el propietario principal"

  - nombre: parentesco
    tipo: VARCHAR(50)
    descripcion: "Relacion: dueno, familiar, cuidador"

  - nombre: fecha_desde
    tipo: DATE
    default: CURRENT_DATE

  - nombre: fecha_hasta
    tipo: DATE
    descripcion: "Si dejo de ser propietario"

  - nombre: activo
    tipo: BOOLEAN
    default: true

indices:
  - nombre: uk_mascota_propietario
    campos: [mascota_id, propietario_id]
    unique: true
  - nombre: idx_mp_propietario
    campos: [propietario_id]

2.5 historial_peso

tabla: veterinaria.historial_pesos
descripcion: "Registro historico de pesos"

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

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

  - nombre: peso_kg
    tipo: DECIMAL(6,2)
    not_null: true

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

  - nombre: registrado_por
    tipo: UUID
    fk: core.usuarios(id)

  - nombre: notas
    tipo: TEXT
    descripcion: "Observaciones (dieta, enfermedad, etc)"

indices:
  - nombre: idx_historial_peso_mascota
    campos: [mascota_id]
  - nombre: idx_historial_peso_fecha
    campos: [mascota_id, fecha_registro DESC]

---

3. API ENDPOINTS

Mascotas

endpoints:
  - method: GET
    path: /api/v1/mascotas
    descripcion: "Listar mascotas del tenant"
    query:
      especie: string (filtro)
      estado: string (filtro)
      propietario_id: string (filtro)
      search: string (nombre, microchip)
      page: number
      limit: number
    response: PaginatedResponse<Mascota>

  - method: GET
    path: /api/v1/mascotas/{id}
    descripcion: "Obtener mascota por ID"
    response: Mascota con propietarios y ultimo peso

  - method: POST
    path: /api/v1/mascotas
    descripcion: "Registrar nueva mascota"
    body:
      nombre: string (requerido)
      especie_id: string (requerido)
      raza_id: string (opcional)
      sexo: string (requerido)
      fecha_nacimiento: date (opcional)
      color: string
      peso_kg: number
      microchip: string
      esterilizado: boolean
      propietario_id: string (requerido, al menos uno)
      foto_url: string
      notas: string
    response: Mascota creada

  - method: PUT
    path: /api/v1/mascotas/{id}
    descripcion: "Actualizar datos de mascota"
    body: Campos actualizables
    response: Mascota actualizada

  - method: PATCH
    path: /api/v1/mascotas/{id}/estado
    descripcion: "Cambiar estado (fallecido, perdido, etc)"
    body:
      estado: string
      fecha: date
      motivo: string
    response: Mascota actualizada

  - method: DELETE
    path: /api/v1/mascotas/{id}
    descripcion: "Dar de baja mascota (soft delete)"
    response: 204 No Content

Busqueda por Microchip

  - method: GET
    path: /api/v1/mascotas/microchip/{numero}
    descripcion: "Buscar por numero de microchip"
    response: Mascota o 404

Historial de Peso

  - method: GET
    path: /api/v1/mascotas/{id}/pesos
    descripcion: "Historial de pesos"
    query:
      desde: date
      hasta: date
    response: Array de registros de peso

  - method: POST
    path: /api/v1/mascotas/{id}/pesos
    descripcion: "Registrar nuevo peso"
    body:
      peso_kg: number (requerido)
      notas: string
    response: Registro de peso + mascota actualizada

Propietarios de Mascota

  - method: GET
    path: /api/v1/mascotas/{id}/propietarios
    descripcion: "Propietarios vinculados"
    response: Array de propietarios

  - method: POST
    path: /api/v1/mascotas/{id}/propietarios
    descripcion: "Vincular propietario adicional"
    body:
      propietario_id: string
      es_principal: boolean
      parentesco: string
    response: Relacion creada

  - method: DELETE
    path: /api/v1/mascotas/{id}/propietarios/{propietarioId}
    descripcion: "Desvincular propietario"
    response: 204 No Content

---

4. FLUJOS DE USUARIO

4.1 Registro de Nueva Mascota

1. Recepcionista busca propietario existente o lo crea
2. Click en "Nueva Mascota"
3. Formulario de datos basicos:
   - Nombre
   - Especie (dropdown)
   - Raza (dropdown filtrado por especie)
   - Sexo
   - Fecha nacimiento (con checkbox "aproximada")
   - Color
   - Peso actual
4. Datos de identificacion:
   - Microchip (si tiene)
   - Esterilizado (si/no + fecha)
5. Foto (opcional)
6. Notas adicionales
7. Guardar
8. Sistema vincula con propietario automaticamente

4.2 Busqueda de Mascota

1. Campo de busqueda en header
2. Escribir nombre, microchip o nombre de propietario
3. Resultados en tiempo real
4. Click en resultado para abrir expediente
5. Alternativa: Escanear codigo de microchip

4.3 Registro de Peso en Consulta

1. Al iniciar consulta, sistema pide peso
2. Auxiliar pesa a la mascota
3. Ingresa peso en sistema
4. Sistema muestra grafica de historico
5. Alerta si hay variacion significativa (>10%)
6. Peso se asocia a la consulta

4.4 Fallecimiento de Mascota

1. Abrir expediente de mascota
2. Menu: "Cambiar estado" > "Fallecido"
3. Formulario:
   - Fecha de fallecimiento
   - Causa (libre o catalogo)
   - Lugar (clinica, domicilio, otro)
   - Notas
4. Confirmacion con mensaje de condolencias
5. Sistema actualiza estado
6. Mascota aparece en seccion "Inactivos"

---

5. COMPONENTES UI

5.1 MascotaCard

interface MascotaCardProps {
  mascota: Mascota;
  showPropietario?: boolean;
  onClick?: () => void;
}

// Muestra foto, nombre, especie, raza, edad
// Badge de estado (activo, fallecido, etc)
// Iconos de vacunas, alergias si aplica

5.2 MascotaForm

interface MascotaFormProps {
  mascota?: Mascota; // Para edicion
  propietarioId?: string; // Precarga propietario
  onSave: (mascota: Mascota) => void;
  onCancel: () => void;
}

// Wizard de pasos o formulario largo
// Validaciones en tiempo real
// Preview de foto

5.3 PesoChart

interface PesoChartProps {
  mascotaId: string;
  periodoMeses?: number;
}

// Grafica de linea con historico de peso
// Linea de peso ideal segun raza
// Tooltips con fechas y valores

5.4 MascotaExpediente

interface MascotaExpedienteProps {
  mascotaId: string;
}

// Vista completa del expediente
// Tabs: Datos, Vacunas, Consultas, Hospitalizaciones
// Timeline de eventos

---

6. VALIDACIONES

Reglas de Negocio

validaciones:
  - regla: "Microchip unico en el tenant"
    condicion: microchip duplicado
    error: "Este numero de microchip ya esta registrado"

  - regla: "Raza debe corresponder a especie"
    condicion: raza.especie_id != mascota.especie_id
    error: "La raza seleccionada no corresponde a la especie"

  - regla: "Fecha nacimiento no puede ser futura"
    condicion: fecha_nacimiento > today()
    error: "La fecha de nacimiento no puede ser en el futuro"

  - regla: "Peso debe ser positivo"
    condicion: peso_kg <= 0
    error: "El peso debe ser mayor a 0"

  - regla: "Al menos un propietario"
    condicion: propietarios.length == 0
    error: "La mascota debe tener al menos un propietario"

  - regla: "Solo un propietario principal"
    condicion: propietarios.filter(p => p.es_principal).length > 1
    error: "Solo puede haber un propietario principal"

---

7. CASOS DE USO

CU-VET-001: Registro de Mascota Nueva

Actor: Recepcionista / Veterinario Precondición: Propietario registrado en sistema Flujo:

1. Seleccionar propietario
2. Click "Nueva Mascota"
3. Completar datos obligatorios
4. Agregar foto (opcional)
5. Guardar Postcondición: Mascota registrada, vinculada a propietario

CU-VET-002: Busqueda por Microchip

Actor: Cualquier usuario Precondición: Mascota con microchip registrado Flujo:

1. Escanear o ingresar numero de microchip
2. Sistema busca en base de datos
3. Mostrar mascota encontrada Postcondición: Acceso rapido al expediente

CU-VET-003: Actualizacion de Peso

Actor: Auxiliar / Veterinario Precondición: Mascota en consulta Flujo:

1. Pesar mascota
2. Ingresar peso en sistema
3. Sistema calcula diferencia vs anterior
4. Mostrar alerta si variacion > 10%
5. Guardar con notas si aplica Postcondición: Peso registrado, historial actualizado

---

8. DEPENDENCIAS

Depende de

• veterinaria.propietarios - Duenos de mascotas
• core.usuarios - Quien registra
• core.tenants - Multi-tenant

Dependientes

• veterinaria.vacunaciones - Cartilla de vacunas
• veterinaria.consultas - Historia clinica
• veterinaria.hospitalizaciones - Ingresos
• veterinaria.facturas - Facturacion

---

9. METRICAS

Metrica	Descripcion	Query
Total mascotas	Mascotas activas	WHERE estado = 'activo'
Por especie	Distribucion	GROUP BY especie_id
Nuevas/mes	Registros mensuales	WHERE created_at >= ?
Tasa mortalidad	Fallecidos / total	Calculo

---

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