Saltar al contenido principal

REQ-ADM-03 — Administración web del módulo de veterinaria «sean-pets»

· 5 min de lectura
Yovany Suárez Silva
Software Engineer - FullStack Developer

Implementación del requerimiento REQ-ADM-03 (Administración web del módulo de veterinaria «sean-pets»), dentro de Administración y con prioridad Media. La clínica operaba con la app móvil sean-pets, pero su administración (usuarios, catálogo, precios, inventario y bajas) exigía un celular y un rol dentro de la app. Ahora esa administración vive en el marco de almacén, sobre la misma base MongoDB, sin duplicar datos y sin afectar a la app.


📋 Alcance​

Criterio de aceptaciónEntregable
CA1 — Inventario funcional del ambiente móvilSpec docs/mejoras/req-adm-03-administracion-veterinaria-sean-pets.md: roles, 16 colecciones, módulos de la app y su tratamiento
CA2 — Implementación conforme a la arquitectura del almacénDominio veterinaria en ccf-almacen-api (8 controladores, 9 servicios, DTOs, auditoría) y nueve pantallas en ccf-almacen-web
CA3 — Conexión a la base MongoDB de sean-petsSeanMongoService (driver oficial, cliente por proceso, 503 accionable) + npm run verificar:veterinaria
CA4 — Roles, usuarios y menús integradosRoles Veterinario y Auxiliar veterinaria, grupo de menú Veterinaria (clave 99, sin submenú) y migraciones 046, 047 y 048
CA5 — sean-pets sigue operando soloSin cambios en su código ni en su esquema; una sola base; autenticaciones separadas
CA6 — Acceso desde el menú según el rolGET /api/menu filtra por rol; catálogo y personal solo Administrador
Fuera de alcanceHistoria clínica (consultas/cirugías), reserva del cliente final, pagos en línea, fidelización, WhatsApp y móvil del almacén

⚙️ Cómo funciona​

  • Una sola fuente de verdad. El API del almacén abre un cliente MongoDB contra la base de la clínica (SEAN_MONGO_URI + SEAN_MONGO_DB) y lee/escribe los mismos documentos que sean-api. No hay ETL ni tablas espejo en PostgreSQL.
  • Degradación aislada. Si la base no está configurada o no responde, solo el módulo de veterinaria responde 503 con el motivo; el almacén sigue operativo.
  • Paridad de reglas. Se replican las reglas del móvil: fechas en America/Bogota, semáforo de stock, reparto FIFO de abonos, próximo servicio sugerido, solape de agenda por duración, precio inteligente (talla + peso), lista de precios versionada y penalización por inasistencia.
  • RBAC del almacén. @Roles(Administrador, Veterinario, Auxiliar veterinaria); catálogo, personal y bajas de clientes, solo Administrador. Toda acción sensible queda en logs_operacion (módulo veterinaria).
  • Contraseñas temporales. El alta de clientes y funcionarios devuelve la credencial temporal y un enlace de WhatsApp; el passwordHash nunca sale de la API.
  • Menú dirigido por datos. Los accesos de veterinaria se siembran con la migración 046 y se aplanan con la 047; se pueden reordenar o reasignar desde Gestión de menú.
  • Un solo módulo de veterinaria (ajuste posterior). El árbol dejó de ser un contenedor con nueve hijos: el módulo Veterinaria abre el tablero y Agenda, Clientes y mascotas, Servicios y precios, Inventario, Cartera, Calificaciones y NPS, Sanidad y Personal son módulos hermanos de primer nivel. Se eliminó 99-tablero (repetía la página del contenedor) y la sección muestra los nueve accesos sin desplegable.
  • Estilo del menú. Las filas son tarjetas compactas con borde suave, esquinas redondeadas, 4 px equidistantes y 36 px de alto uniforme (encabezados, módulos e hijos de submenú). El encabezado de sección es la fila más ancha; todas las filas de módulo comparten el mismo ancho. Las secciones funcionan como acordeón: solo una abierta a la vez (o ninguna) para que el menú no crezca en alto. El icono de Veterinaria es PawPrint (huella, alias de lucide-react), migración 048, en lugar del corazón genérico.

🗂️ Pantallas añadidas​

MenúRutaQué hace
Veterinaria (tablero)/veterinariaKPIs del negocio, próximas citas, alertas sanitarias y NPS
Agenda/veterinaria-agendaAlta de citas, estados, anulación y reprogramación
Clientes y mascotas/veterinaria-pacientesDirectorio, altas, bajas inteligentes y fichas
Servicios y precios/veterinaria-catalogoTipos, opciones y lista de precios versionada
Inventario/veterinaria-inventarioStock, vencimientos, movimientos y kardex
Cartera/veterinaria-carteraSaldos FIFO, cobros de servicio y abonos
Calificaciones y NPS/veterinaria-calificacionesNPS global/por médico/por servicio y respuestas
Sanidad/veterinaria-sanidadCarnets de vacunas y antiparasitarios
Personal/veterinaria-personalAuxiliares, médicos y administradores

🔌 Configuración​

# API (.env)
SEAN_MONGO_URI=mongodb://127.0.0.1:27017
SEAN_MONGO_DB=seanpets
SEAN_MONGO_TIMEOUT_MS=5000

# Política de citas (opcional; por defecto, la misma de la app)
VETERINARIA_CANCELACION_UMBRAL_HORAS=4
VETERINARIA_PENALIZACION_PORCENTAJE=30
VETERINARIA_PENALIZACION_MONTO_FIJO=20000
VETERINARIA_PENALIZACION_VENCIMIENTO_DIAS=15
VETERINARIA_DIAS_ALERTA_VENCIMIENTO=30

Pasos de puesta en marcha:

cd ccf-almacen-api
npm run verificar:veterinaria # solo lectura: valida conexión, colecciones y campos
npm run migration:run # aplica 046 (roles+menú), 047 (menú plano) y 048 (icono)

Después, en Usuarios, asigna el rol Veterinario o Auxiliar veterinaria a las cuentas del almacén que deban operar la clínica.

✅ Verificación​

  • ccf-almacen-api: tsc --noEmit sin errores, eslint sin errores y 45 pruebas nuevas del dominio (utilidades, reglas y servicios).
  • ccf-almacen-web: tsc --noEmit sin errores, eslint sin errores y 9 pruebas de la integración del menú y del registro de componentes.
  • Conexión real verificada contra la base seanpets (6 usuarios, 30 citas, 18 cortes, 17 pagos…) y agregaciones de citas, deuda, reseñas y precios ejecutadas sin error.

📚 Documentación​