# Ampliar el sistema del edificio: reservas y registro de lobby

Actúa como ingeniero de software senior dentro de este repositorio. Tu tarea es implementar una ampliación incremental del producto, siguiendo su arquitectura y convenciones. No te limites a proponer una solución: inspecciona el código, implementa lo viable, añade pruebas y verifica el resultado.

## 1. Contexto y objetivo

Tenemos un sistema para gestionar operaciones dentro de un edificio. Actualmente cuenta con un módulo de **gating**, encargado de los vehículos que ingresan y salen del estacionamiento.

Queremos incorporar dos módulos conectados al sistema existente:

1. **Reservas de áreas comunes:** disponibilidad, creación y cancelación de reservas, y administración de los espacios.
2. **Registro de lobby:** registro manual de personas que ingresan y salen, consulta de quienes figuran dentro e historial de movimientos.

El resultado debe sentirse como una ampliación del mismo producto, no como dos aplicaciones separadas. El funcionamiento actual de gating debe conservarse.

No conocemos de antemano el stack, los modelos, los roles ni la estructura del repositorio. Descúbrelos antes de diseñar o modificar código. No inventes rutas, tablas, servicios ni funcionalidades existentes.

## 2. Inspección inicial obligatoria

Antes de modificar archivos:

- Lee las instrucciones del proyecto, incluyendo `AGENTS.md`, `README`, documentación y convenciones disponibles.
- Revisa el estado de Git. Preserva cambios ajenos y no ejecutes operaciones destructivas.
- Identifica stack, estructura, comandos de desarrollo, pruebas y migraciones.
- Localiza el flujo de gating y sus dependencias: autenticación, permisos, edificios, unidades/departamentos, residentes, vehículos y registros de acceso, cuando existan.
- Identifica componentes, validaciones, utilidades de fechas, auditoría y patrones reutilizables.
- Determina si este repositorio contiene frontend, backend o ambos. Implementa lo que corresponde aquí; no inventes aplicaciones externas para completar partes ausentes.

Presenta un diagnóstico breve con rutas reales y un plan de implementación. Diferencia lo encontrado de tus supuestos. Después continúa con el trabajo; no te detengas únicamente en el diagnóstico.

## 3. Reglas de integración y seguridad

- Reutiliza stack, autenticación, modelos y componentes. Evita reescrituras, duplicación de usuarios y dependencias innecesarias.
- Mantén compatibles los contratos y flujos existentes de gating.
- Reutiliza edificio y unidad si existen. Si faltan entidades necesarias, introduce solo la estructura mínima y explica la decisión; no construyas un sistema multiempresa completo sin necesidad.
- Respeta la separación de datos entre edificios cuando corresponda. Valida permisos y pertenencia en el servidor, no solo en la interfaz.
- No confíes en identificadores de usuario, edificio o unidad enviados por el cliente sin comprobar autorización.
- Usa migraciones incrementales y compatibles. No borres datos ni reescribas migraciones aplicadas.
- No leas ni muestres secretos innecesariamente. No incluyas credenciales o datos personales reales en código, pruebas, capturas o logs.
- No ejecutes migraciones contra producción, ni contactes hardware o servicios reales. Trabaja con recursos locales o de prueba identificados como seguros.
- No hagas commits, pushes, despliegues ni cambios de infraestructura sin autorización expresa.

Si una operación necesita acceso o una decisión que no puedes resolver de forma segura, deja esa parte pendiente, explica el bloqueo y continúa con lo independiente. No simules integraciones terminadas.

## 4. Módulo de reservas de áreas comunes

### Funciones del MVP

**Administración de espacios**

Permite crear, editar y activar/desactivar áreas comunes. Cada espacio tendrá nombre, descripción opcional, edificio cuando aplique, capacidad opcional y horarios de disponibilidad. Reutiliza cualquier configuración o modelo equivalente existente.

Desactivar un espacio debe impedir nuevas reservas sin borrar su historial. Si tiene reservas futuras, advierte al administrador y no las canceles silenciosamente.

**Consulta de disponibilidad**

Permite consultar espacios y disponibilidad por fecha. Usa calendario o listado según los componentes existentes; prioriza una experiencia clara sobre una visualización compleja. Los residentes deben poder identificar horarios ocupados sin acceder a datos personales de otros residentes.

**Crear y cancelar reservas**

Una reserva debe relacionar espacio, usuario responsable, unidad cuando corresponda, inicio, fin y estado. Incluye número de asistentes solo si se necesita para validar capacidad.

Para el MVP, utiliza confirmación automática al cumplir las reglas, salvo que el sistema ya tenga un flujo de aprobación aplicable. Conserva el historial de cancelación y quién la realizó. No elimines físicamente las reservas canceladas.

El residente podrá ver y cancelar sus propias reservas; el administrador podrá consultar y gestionar las de su ámbito autorizado.

### Reglas de negocio

- Inicio y fin válidos, fin posterior al inicio y sin nuevas reservas en el pasado.
- Espacio activo y reserva completamente dentro de su horario disponible.
- Capacidad respetada cuando esté configurada.
- Por defecto, cada espacio se reserva de forma exclusiva por intervalo. No implementes reservas compartidas por aforo salvo que el producto ya las requiera.
- Impide solapamientos entre reservas vigentes del mismo espacio, incluso con solicitudes simultáneas. Una comprobación en frontend o un `SELECT` seguido de un `INSERT` sin protección no son suficientes: utiliza la garantía transaccional, restricción o bloqueo apropiado para la base de datos real.
- Dos reservas contiguas pueden coexistir si una termina exactamente cuando empieza la otra, salvo que exista un margen entre reservas configurado.
- Cancelar una reserva libera su intervalo; repetir la cancelación no debe corromper el estado.
- Usa la zona horaria configurada para el edificio o la aplicación. Maneja almacenamiento y presentación de fechas de manera consistente con el repositorio, sin cambiar el comportamiento temporal de gating.
- No inventes límites por departamento, cobros, anticipación máxima o penalidades. Reutiliza las reglas existentes; cuando no existan, documenta el comportamiento mínimo elegido.

## 5. Módulo de registro de lobby

### Funciones del MVP

**Registrar ingreso**

Permite a recepción o al administrador registrar la entrada de una persona. Considera residentes, visitantes, proveedores y personal, reutilizando las categorías existentes o una clasificación mínima documentada.

Registra la información necesaria: referencia a la persona si ya existe o nombre de la persona externa, categoría, edificio cuando aplique, unidad/persona de destino cuando corresponda, hora de ingreso y operador responsable. Motivo y observaciones serán opcionales.

Reutiliza residentes existentes: no crees una segunda base de residentes. No exijas teléfono, documento de identidad, fotografía o información sensible salvo que un requisito existente lo justifique.

**Registrar salida**

Permite cerrar un ingreso activo guardando hora de salida y operador responsable. No permitas una salida anterior al ingreso ni cerrar dos veces el mismo registro. Evita duplicados por doble clic o solicitudes repetidas y protege también las actualizaciones concurrentes.

**Personas registradas dentro**

Muestra los registros con ingreso y sin salida, con búsqueda, filtros por categoría y destino, y una acción rápida para registrar salida. El contador debe describirse como personas *registradas dentro*, no como una medición garantizada de ocupación física.

**Historial**

Permite consultar ingresos y salidas con filtros por fecha, persona, categoría, unidad y estado, usando paginación cuando corresponda. Conserva trazabilidad de quién registró cada acción. No habilites borrado definitivo desde la interfaz.

### Reglas de negocio

- Una persona y un ingreso son entidades distintas: una persona puede tener múltiples ingresos en diferentes momentos.
- No utilices el nombre como identificador único; dos personas pueden llamarse igual.
- Deriva el estado «dentro/finalizado» del ciclo de ingreso y salida, o garantiza su consistencia si lo almacenas.
- No cierres automáticamente el ingreso de una persona cuando sale un vehículo, ni a la inversa. Gating y lobby registran eventos distintos.
- Relaciona registros peatonales y vehiculares solo cuando exista una asociación explícita y segura; no es indispensable para este MVP.
- Registrar una entrada en lobby no debe activar puertas, barreras ni permisos físicos automáticamente.

## 6. Permisos e interfaz

Mapea estos perfiles conceptuales a los roles reales, sin duplicar el sistema de permisos:

- **Administrador:** configura espacios, gestiona reservas y consulta registros del lobby dentro de su ámbito.
- **Recepción/seguridad:** registra ingresos y salidas y consulta el lobby. No obtiene por defecto permisos de administración de espacios o reservas.
- **Residente:** consulta disponibilidad y crea, consulta y cancela sus propias reservas. No accede al registro general de personas del edificio.

Si no existe autenticación o autorización suficiente, no publiques endpoints abiertos como solución provisional: documenta la dependencia y protege las funciones antes de habilitarlas.

Cuando haya frontend, integra las secciones «Áreas comunes» y «Lobby» en la navegación existente. Mantén diseño, componentes e internacionalización del proyecto, con textos en español cuando corresponda. Incluye estados de carga, vacío, error y éxito, formularios claros y confirmación de cancelación. Prioriza rapidez de uso para recepción y funcionamiento en móvil.

Cuando solo haya backend, entrega contratos y ejemplos de uso compatibles con su documentación, e identifica por separado el trabajo pendiente de interfaz.

## 7. Pruebas y verificación

Usa las herramientas del proyecto. Añade pruebas que cubran como mínimo:

- Gating: comprobaciones de regresión de los flujos existentes afectados por la integración.
- Reservas: creación válida, cancelación y liberación del horario, solapamiento, dos solicitudes concurrentes para el mismo intervalo, horarios inválidos, reservas contiguas y fechas en la zona horaria configurada.
- Lobby: ingreso, salida, listado de registros activos, historial, solicitudes duplicadas, cierres concurrentes y personas diferentes con el mismo nombre.
- Autorización: acceso denegado por rol y acceso a datos ajenos, incluyendo otro edificio cuando exista esa estructura.

Verifica que las migraciones pueden aplicarse en un entorno aislado y que el esquema anterior se conserva. Ejecuta las pruebas, lint, verificación de tipos y build disponibles y pertinentes. Distingue fallos preexistentes de los introducidos por tus cambios.

No afirmes que algo funciona o que una prueba pasó si no lo verificaste. Informa los comandos ejecutados y sus resultados. Si faltan servicios o dependencias, señala exactamente qué quedó sin comprobar.

## 8. Alcance y entrega

No incluyas por iniciativa propia pagos, multas, WhatsApp, reconocimiento facial, biometría, QR, integración con cerraduras ni hardware nuevo. Tampoco conviertas este trabajo en un rediseño completo del producto.

Trabaja en incrementos pequeños: inspección, modelo y migraciones, lógica y permisos, interfaz cuando aplique, pruebas y documentación. Mantén breves actualizaciones de progreso.

Al finalizar, entrega:

1. Resumen de lo implementado y cómo probar cada flujo.
2. Archivos principales modificados, migraciones nuevas y dependencias añadidas, con su justificación.
3. Supuestos de negocio adoptados y permisos resultantes.
4. Comandos reales para instalar, ejecutar, migrar y probar en un entorno local seguro.
5. Resultados de verificación, bloqueos y limitaciones pendientes, sin presentarlos como terminados.

Actualiza la documentación del repositorio siguiendo sus convenciones. Usa datos sintéticos únicamente en pruebas o ejemplos locales, nunca como datos de producción.

Comienza inspeccionando el repositorio y continúa con la implementación del MVP. Prioriza preservar gating, proteger los datos y completar ambos flujos con la menor complejidad necesaria.