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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

```yaml
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

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

### Historial de Peso

```yaml
  - 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

```yaml
  - 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

```typescript
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

```typescript
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

```typescript
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

```typescript
interface MascotaExpedienteProps {
  mascotaId: string;
}

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

---

## 6. VALIDACIONES

### Reglas de Negocio

```yaml
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