# Vetiquín `Vetiquín` es el módulo de medicamentos veterinarios de Animal Charlie. Usa la integración normalizada de CIMAVet y guarda enlaces operativos con clientes, explotaciones e informes. ## Qué datos aporta CIMAVet El adaptador interno de CIMAVet expone capacidades clínicas útiles para el veterinario: | Capacidad | Uso en Vetiquín | | --- | --- | | `veterinary_medicines.search` | Búsqueda por nombre, especie, principio activo, número de registro, código nacional, estado, vía, forma farmacéutica o comercialización. | | `veterinary_medicines.get` | Ficha normalizada del medicamento: estado, comercialización, prescripción, titular, principios activos, excipientes, especies destino, vías, ATC y documentos. | | `veterinary_presentations.search` | Presentaciones y códigos nacionales disponibles para seleccionar el formato correcto. | | `veterinary_safety_notes.search` | Notas de seguridad o informativas por número de registro cuando CIMAVet las devuelve. | | `veterinary_change_log.search` | Registro de altas, bajas y modificaciones desde una fecha. Sirve para revisar cambios recientes en medicamentos usados. | | `veterinary_master_data.*` | Catálogos de especies, vías, formas, principios activos y estados para filtros futuros. | La UI no muestra el JSON crudo. Resume lo que importa en trabajo diario: estado, comercialización, si requiere receta, si es antibiótico, documentos, presentaciones, principios activos y avisos. ## Vista de trabajo Vetiquín se organiza como una pantalla ERP de cuatro submenús: - `Consulta`: buscador CIMAVet y ficha clínica del medicamento seleccionado. - `Receta`: ficha seleccionada más formulario de enlace operativo con cliente, explotación, informe y pauta. - `Histórico`: recetas enlazadas, acciones de editar, duplicar o archivar tratamientos, y consulta puntual del registro de cambios CIMAVet. - `Retiradas`: agenda calculada de leche/carne desde `Fin` y las esperas guardadas, con filtros de atención, hoy, próximas 72 h, programadas, liberadas e incompletas. El resumen superior es una línea de contexto, no un bloque de tarjetas. Las acciones auxiliares (`Charlie`, documentación y actualizar datos) quedan dentro del menú `Más` para no cargar la pantalla principal. El histórico incluye una cola de revisión operativa. Puede filtrar todas las recetas, solo las que requieren revisión, avisos CIMAVet, antibióticos, recetas sin número de registro o recetas vinculadas a informes. La revisión se activa cuando la receta está en estado `draft`/`review`, tiene aviso `warning`/`alert`, contiene antibiótico en el payload CIMAVet, todavía no tiene número de registro o no conserva tiempos de espera. Encima del listado, Vetiquín muestra un triage de revisión con prioridad `Alta`, `Media` o `Baja`. El panel explica los motivos detectados (por ejemplo, aviso CIMAVet, antibiótico, ausencia de número de registro o falta de esperas) y propone el siguiente paso documental. Cada prioridad incluye acceso directo a la ficha CIMAVet: si la receta tiene número de registro o código nacional, abre el detalle normalizado; si solo conserva el nombre, lanza la búsqueda para completar la ficha. Cuando la receta ya conserva número de registro y algún tiempo de espera, el histórico permite marcarla como revisada. La acción no archiva el tratamiento: guarda en `metadata` `reviewedAt`, `reviewedBy`, `reviewStatus` y un resumen de revisión, conserva el origen y la metadata existente, cambia el estado operativo a `active`, saca la receta de la cola de revisión y recalcula la bandeja ambiental de Charlie para que el contador de pendientes no quede obsoleto. Si faltan registro o esperas, Vetiquín abre el editor para completar esos campos. Las alertas `alert` de CIMAVet no se cierran desde esta acción rápida y siguen visibles hasta resolverlas clínicamente o archivar la receta. La vista `Retiradas` consume la agenda calculada por el servidor. Cada fila parte de la fecha de fin y de los campos `withdrawal_milk`/`withdrawal_meat`: si la espera es interpretable, muestra la fecha estimada de liberación; si falta fecha o espera, la deja en estado incompleto para completar la receta antes de liberar leche o carne. El filtro inicial muestra solo lo que requiere atención (`incomplete`, `today` o `soon`), permite saltar a hoy, próximas 72 h, incompletas, programadas, liberadas o todas, y el buscador local cruza medicamento, cliente, explotación, lote, motivo, fecha de liberación y texto de retirada. ## Avisos Vetiquín clasifica cada medicamento con `ok`, `warning` o `alert`: - `alert`: CIMAVet indica autorización revocada o suspendida, notas de seguridad/informativas en la ficha, o notas reales devueltas por la consulta de notas. - `warning`: no consta como comercializado, es antibiótico, estupefaciente o psicótropo. - `ok`: no se detectan avisos relevantes en los datos normalizados consultados. La condición de prescripción se muestra siempre, pero no convierte por sí sola el medicamento en problema; sirve para recordar trazabilidad documental. ## Charlie en Vetiquín Charlie puede consultar Vetiquín con cuatro acciones seguras: - `search_medicines`: busca en CIMAVet por nombre, especie, principio activo, número de registro o código nacional. - `recommend_medicines`: devuelve recomendaciones operativas basadas en estado, comercialización, avisos, antibióticos y documentación disponible. - `medicine_review_queue`: prioriza recetas que requieren revisión por estado, aviso, antibiótico, ausencia de número de registro o falta de tiempos de espera, excluyendo las revisiones documentadas cuando no quedan campos obligatorios abiertos. - `medicine_withdrawal_watchlist`: calcula una agenda de retiradas de leche/carne desde `end_date` y los tiempos de espera guardados, marcando liberaciones de hoy, próximas e incompletas. La recomendación de Charlie no sustituye la decisión veterinaria. El servidor le fuerza a usar datos CIMAVet normalizados y a no inventar dosis, vías ni tiempos de espera. Para cerrar una pauta hay que abrir la ficha técnica, confirmar especie destino, indicación y restricciones, y después guardar la receta/tratamiento vinculada. Ejemplos útiles: ```text busca en Vetiquín amoxicilina para bovino recomienda medicamentos con principio activo amoxicilina para bovino busca medicamentos con avisos CIMAVet para porcino ``` ## Datos guardados Las recetas o tratamientos vinculados se guardan en `medicine_prescriptions`: - cliente (`customer_id`), explotación (`farm_id`) e informe (`report_id`); - nombre, número de registro, código nacional y presentación; - principios activos normalizados; - motivo, animales/lote, dosis, vía, fechas y tiempos de espera; - referencia de receta/albarán, veterinario y notas internas; - payload CIMAVet normalizado y notas de seguridad; - nivel y resumen de aviso. Además se crea un enlace en `module_links` para que otros módulos puedan referenciar el tratamiento sin duplicar datos. Desde el histórico se puede abrir la ficha CIMAVet asociada, marcar la revisión documental como cerrada (`PUT /api/medicines/prescriptions/{id}`), reabrir una receta en el editor, duplicarla como una receta nueva reutilizando la ficha CIMAVet, o archivarla (`DELETE /api/medicines/prescriptions/{id}`). Archivar no borra la fila: cambia su estado para que deje de aparecer en los listados activos y preserva la trazabilidad. ## Integración con informes El formulario de informes incluye el campo `Medicamentos prescritos o recomendados`. Al guardar el informe: 1. Animal Charlie lee `formData.prescribedMedicines`. 2. Divide el texto por líneas o punto y coma. 3. Crea recetas en estado `draft` ligadas al informe. 4. Marca el aviso como `warning` con el texto `pendiente de validar con CIMAVet`. 5. Crea `module_links` desde `reports/report` hacia `medicines/medicine_prescription`. Cuando el veterinario entra en Vetiquín puede buscar el medicamento en CIMAVet, seleccionar la ficha real y completar dosis, lote, fechas o tiempos de espera. ## Integración con otros módulos Los módulos no deben llamarse entre sí por tablas privadas. La regla es: - datos compartidos por cliente/explotación: usar `customer_id`, `farm_id` y, cuando proceda, `report_id`; - relación explícita entre entidades: usar `module_links`; - datos externos materializados por explotación: usar el patrón de Almacén Lechero (`client_data_*`); - datos externos puntuales de medicamentos: guardar el payload normalizado CIMAVet dentro de `medicine_prescriptions`. Ejemplos esperados: - Un informe receta un medicamento: `reports -> medicines` con `link_type=prescribes`. - Una explotación tiene tratamientos activos: `clients/farm -> medicines` con `link_type=uses_medicine`. - Un análisis de leche sugiere revisar un tratamiento: el Almacén Lechero mantiene el dato por explotación y un módulo clínico puede crear una acción o enlace posterior sin copiar métricas. ## Endpoints internos ```http GET /api/medicines GET /api/medicines/search?q=eq-zona GET /api/medicines/detail?registrationNumber=1173%20ESP GET /api/medicines/changes?dateFrom=01%2F05%2F2026 GET /api/medicines/withdrawals POST /api/medicines/prescriptions PUT /api/medicines/prescriptions/{id} DELETE /api/medicines/prescriptions/{id} POST /api/charlie/message POST /api/charlie/execute ``` Los endpoints requieren sesión de Animal Charlie. La lectura (`GET /api/medicines`, busqueda, ficha y cambios) acepta `medicines.read` o `medicines.write`; crear, actualizar o archivar recetas/enlaces exige `medicines.write`. Los módulos consumidores deben usar estos endpoints o `/api/integrations/query`; no deben llamar directamente a CIMAVet desde el navegador.