Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/camiloivcode/biblioteca-la-palabra/llms.txt

Use this file to discover all available pages before exploring further.

El módulo de préstamos es el núcleo operativo del sistema. Gestiona el ciclo de vida completo de cada préstamo: desde la creación hasta la devolución, aplicando de forma automática todas las reglas de negocio de la biblioteca. El sistema verifica el estado del socio, controla el límite de préstamos simultáneos, gestiona el stock del material y marca automáticamente los préstamos vencidos como morosos, todo dentro de transacciones de base de datos para garantizar consistencia.

​
Reglas de negocio

Cada socio puede tener como máximo 3 préstamos activos de forma simultánea. El sistema cuenta los préstamos en estado ACTIVO o MORA al momento de crear un nuevo préstamo. Si el socio ya tiene 3 o más, la operación se rechaza con un error 409 Conflict.
// prestamo.service.js
const MAX_PRESTAMOS_ACTIVOS = 3;

const prestamosActivos = await prisma.prestamo.count({
  where: { socioId: parseInt(socioId), estado: { in: ['ACTIVO', 'MORA'] } },
});
if (prestamosActivos >= MAX_PRESTAMOS_ACTIVOS) {
  throw new AppError(
    `El socio ya tiene ${MAX_PRESTAMOS_ACTIVOS} préstamos activos (máximo permitido)`,
    409
  );
}
Antes de crear un préstamo, el sistema verifica el estado del socio. Si su estado es MOROSO o SUSPENDIDO, la operación se rechaza con un error 409 Conflict y un mensaje descriptivo.
// prestamo.service.js
if (socio.estado === 'MOROSO') {
  throw new AppError(
    'El socio tiene préstamos en mora. No puede realizar nuevos préstamos',
    409
  );
}
if (socio.estado === 'SUSPENDIDO') {
  throw new AppError('El socio está suspendido', 409);
}
Para desbloquear un socio moroso, se deben devolver todos sus préstamos en estado MORA. El sistema restaura el estado a ACTIVO automáticamente al completar la última devolución pendiente.
Los préstamos tienen un plazo de 30 días (DIAS_PRESTAMO = 30). Al llamar a PATCH /api/prestamos/actualizar-mora, el sistema busca todos los préstamos con estado ACTIVO cuya fechaDevolucion sea anterior a la fecha actual y los marca como MORA. Simultáneamente, actualiza el estado de los socios involucrados a MOROSO.Este endpoint no se ejecuta de forma automática en segundo plano; debe invocarse explícitamente desde el frontend (por ejemplo, al cargar la página de préstamos o al pulsar el botón “Actualizar Mora” en la interfaz).
// prestamo.service.js — actualizarMora()
await prisma.$transaction([
  prisma.prestamo.updateMany({
    where: { id: { in: prestamoIds } },
    data: { estado: 'MORA' },
  }),
  prisma.socio.updateMany({
    where: { id: { in: socioIds } },
    data: { estado: 'MOROSO' },
  }),
]);
Al crear un préstamo, el sistema verifica que el material tenga estado DISPONIBLE y que el número de préstamos activos simultáneos no supere el stock registrado. Si tras el nuevo préstamo todos los ejemplares quedan en circulación, el estado del material se actualiza a PRESTADO.Al registrar una devolución, el estado del material vuelve a DISPONIBLE automáticamente. Ambas operaciones se ejecutan dentro de la misma transacción que crea o cierra el préstamo.

​
Campos del préstamo

CampoTipoDescripción
socioIdintegerID del socio que solicita el préstamo
materialIdintegerID del material a prestar
fechaPrestamodatetimeAsignada automáticamente al momento de creación
fechaDevoluciondatetimeAsignada automáticamente: fechaPrestamo + 30 días
fechaDevRealdatetimeFecha real de devolución; se registra al ejecutar PATCH /api/prestamos/:id/devolver
estadoenumEstado del préstamo: ACTIVO, DEVUELTO o MORA
observacionesstringNotas opcionales sobre el préstamo

​
Flujo de un préstamo

1

Crear el préstamo

El personal selecciona un socio y un material en el formulario y envía POST /api/prestamos con socioId, materialId y, opcionalmente, observaciones.
POST /api/prestamos
Authorization: Bearer <token>
Content-Type: application/json

{
  "socioId": 14,
  "materialId": 37,
  "observaciones": "Ejemplar en buen estado"
}
2

Validación de reglas de negocio

El servicio ejecuta las siguientes verificaciones en orden:
  1. El socio existe y su estado no es MOROSO ni SUSPENDIDO
  2. El socio no supera el límite de 3 préstamos activos (ACTIVO o MORA)
  3. El material existe y su estado es DISPONIBLE
  4. El número de préstamos activos del material no supera su stock
Si alguna verificación falla, se devuelve 409 Conflict con un mensaje descriptivo. No se realiza ninguna modificación en la base de datos.
3

Registro del préstamo y actualización del stock

Dentro de una transacción, el sistema crea el registro del préstamo con fechaDevolucion = hoy + 30 días y, si corresponde, actualiza el estado del material a PRESTADO. La respuesta incluye los datos del socio y el material asociados.
4

Registrar la devolución

Cuando el socio devuelve el material, el personal ejecuta PATCH /api/prestamos/:id/devolver.
PATCH /api/prestamos/88/devolver
Authorization: Bearer <token>
5

Cierre del ciclo

En una sola transacción, el sistema:
  • Actualiza el estado del préstamo a DEVUELTO y registra fechaDevReal
  • Actualiza el estado del material a DISPONIBLE
  • Verifica si el socio tiene más préstamos en MORA; si no tiene, restaura su estado a ACTIVO

​
Actualización de mora

El endpoint PATCH /api/prestamos/actualizar-mora recorre todos los préstamos con estado ACTIVO cuya fechaDevolucion sea anterior a la fecha y hora actuales, y los marca como MORA. En la misma operación, actualiza el estado de los socios afectados a MOROSO. 
PATCH /api/prestamos/actualizar-mora
Authorization: Bearer <token>
Respuesta exitosa: 
{
  "data": {
    "actualizados": 4,
    "message": "4 préstamo(s) actualizados a mora"
  }
}
Si no hay préstamos vencidos, el sistema responde con { "actualizados": 0, "message": "No hay préstamos en mora" } sin realizar ninguna modificación. Este endpoint es invocado desde el frontend al cargar la página de préstamos y también está disponible como acción manual mediante el botón “Actualizar Mora” de la interfaz.

​
Operaciones

MétodoEndpointDescripción
GET/api/prestamosLista paginada de préstamos; filtra por estado, socioId y materialId
GET/api/prestamos/:idDetalle de un préstamo con socio y material completos
POST/api/prestamosCrea un nuevo préstamo aplicando todas las reglas de negocio
PATCH/api/prestamos/:id/devolverRegistra la devolución y actualiza stock y estado del socio
PATCH/api/prestamos/actualizar-moraMarca como MORA todos los préstamos activos vencidos
La acción de devolución (PATCH /api/prestamos/:id/devolver) es irreversible. Una vez registrada, el préstamo queda en estado DEVUELTO de forma permanente y el sistema rechazará cualquier intento de volver a devolver ese mismo préstamo con un error 409 Conflict: "Este préstamo ya fue devuelto". Verifica la identidad del préstamo antes de confirmar la operación.
Para la referencia completa del endpoint de préstamos, consulta la documentación de /api/prestamos.

Build docs developers (and LLMs) love

Get started for freeTalk to us