# Especificación de Requisitos de Software (SDD-012) ## Módulo: Portal de Beneficios, Convenios Comerciales y Control de Acceso por QR con IA (UdeCi) y Rol Recepción **ID de Especificación**: SDD-012 **Estado**: Planificado / Aprobación de Arquitectura **Fecha**: 2026-10-27 **Autores**: Coordinador de Arquitectura, Bedelía y Tutoría Virtual UniCABA --- ### 1. Visión General y Propósito El presente requerimiento expande el ecosistema institucional de **Admin Edu-Space (UniCABA)** agregando valor tangible en la vida diaria de estudiantes, docentes y personal de Bedelía/Recepción, a través de dos ejes estratégicos interconectados con la inteligencia artificial **UdeCi**: 1. **Club de Beneficios y Convenios Institucionales**: - Una herramienta centralizada para que Bedelía y el Administrador carguen, administren y publiquen promociones, convenios y descuentos comerciales (cafeterías, librerías, tecnología, transporte, salud y cultura). - Un catálogo visual y responsive para estudiantes y docentes donde consultar beneficios y generar cupones o validar su pertenencia universitaria. - Integración nativa con **UdeCi** (IA RAG y Live Context): los alumnos y docentes pueden consultar en lenguaje natural los beneficios disponibles, promociones cercanas a su sede y condiciones de canje. UdeCi asiste a Bedelía en la redacción y auditoría de vencimientos de convenios. 2. **Perfil de Recepción y Control de Acceso Ágil por Código QR**: - Incorporación del rol institucional **`RECEPCION`** (personal de mesa de entrada, seguridad y torniquetes). - **Credencial Digital QR** accesible desde el portal móvil del alumno y docente, con código QR seguro y dinámico. - **Consola de Recepción con Escáner de Alta Velocidad**: al escanear el QR, la pantalla de recepción valida la matrícula en tiempo real, registra el ingreso (*check-in*) y muestra de forma inmediata las clases y aulas físicas asignadas para el día de hoy, permitiendo orientar al alumno en segundos. --- ### 2. Requisitos del Sistema en Sintaxis EARS (Español) #### 2.1 Requisitos Ubicuos (Ubiquitous Requirements) - **REQ-UBI-01**: EL SISTEMA registrará en `AuditLog` toda creación, edición o cambio de estado de un convenio comercial y todo registro de ingreso institucional escaneado. - **REQ-UBI-02**: EL SISTEMA mantendrá el aislamiento de roles en el catálogo de beneficios: solo se mostrarán promociones vigentes dirigidas al rol específico del usuario (`ALUMNO`, `DOCENTE`, `TODOS`). - **REQ-UBI-03**: EL SISTEMA incorporará los convenios vigentes en la base de contexto en vivo de **UdeCi**, respondiendo consultas en tiempo real sobre promociones sin inventar datos mock. - **REQ-UBI-04**: EL SISTEMA garantizará que el Código QR de la Credencial Digital contenga un token verificable con firma o clave criptográfica institucional para impedir falsificaciones o clonaciones estáticas. #### 2.2 Requisitos Basados en Eventos (Event-driven Requirements) - **REQ-EVT-01**: CUANDO un operador con rol `BEDELIA` o `ADMIN` guarde un nuevo convenio con fecha de inicio, fecha de fin, porcentaje de descuento y sede aplicable, EL SISTEMA validará los datos, persistirá el registro en `InstitutionalBenefit` y retornará código `201 Created`. - **REQ-EVT-02**: CUANDO un estudiante o docente consulte a UdeCi sobre descuentos (ej: *"¿Qué promociones hay en cafetería hoy?"* o *"¿Tengo descuento en librerías?"*), EL SISTEMA consultará la tabla de beneficios activos y responderá con los comercios adheridos, descuentos y pasos de canje. - **REQ-EVT-03**: CUANDO un operador de Bedelía solicite a UdeCi asistencia en la redacción de un convenio, EL SISTEMA generará una propuesta con cláusulas claras, términos y condiciones y etiquetas de descuento optimizadas. - **REQ-EVT-04**: CUANDO un alumno o docente acceda a la sección "Mi Credencial", EL SISTEMA generará su credencial virtual con foto, nombre, DNI, carrera/rol y su código QR institucional interactivo. - **REQ-EVT-05**: CUANDO el personal de `RECEPCION` escanee el código QR desde la cámara del dispositivo o lector óptico USB, EL SISTEMA validará la identidad en menos de 300 ms, registrará el evento en `AccessLogQR` y desplegará en verde la foto, estado del alumno y el cronograma áulico del día (aula física, sede, piso y horario). #### 2.3 Requisitos de Estado (State-driven Requirements) - **REQ-STA-01**: MIENTRAS un convenio se encuentre fuera del rango de fechas de vigencia (`valid_until < fecha_actual`), EL SISTEMA marcará automáticamente su estado como vencido y lo ocultará del catálogo general de alumnos y docentes. - **REQ-STA-02**: MIENTRAS el personal opere en el perfil `RECEPCION`, EL SISTEMA presentará una interfaz minimalista optimizada para pantalla táctil o kiosco de acceso, bloqueando la navegación a paneles sensibles de notas o configuración. #### 2.4 Requisitos de Situaciones No Deseadas (Unwanted Behaviour Requirements) - **REQ-NO-01**: SI el código QR escaneado por Recepción es inválido, manipulado o corresponde a un usuario suspendido o inactivo, ENTONCES EL SISTEMA emitirá una alerta visual roja y sonora de "Acceso Denegado / Verificar en Bedelía", registrando el intento fallido. - **REQ-NO-02**: SI un usuario con rol Alumno intenta acceder al panel de gestión y alta de convenios (`/benefits/manage`), ENTONCES EL SISTEMA denegará el acceso retornando error `403 Forbidden` y redirigiéndolo a su catálogo de beneficios. - **REQ-NO-03**: SI el comercio o sede asociada al convenio se encuentra inactiva, ENTONCES EL SISTEMA suspenderá la visualización del beneficio hasta su regularización. #### 2.5 Requisitos Opcionales (Optional Features) - **REQ-OPC-01**: DONDE el convenio comercial cuente con un código o cupón de descuento alfanumérico (ej: `UNICABA-CAFE-20`), EL SISTEMA mostrará un botón interactivo de "Copiar Cupón" y un código de barras / QR específico para mostrar en la caja del comercio. - **REQ-OPC-02**: DONDE el alumno escanee su ingreso y tenga clase en los próximos 15 minutos, EL SISTEMA podrá orientar con un aviso en pantalla: *"¡Bienvenido a Sede Central! Tu clase comienza a las 18:30 en Aula 102 (1º Piso)"*. --- ### 3. Modelo de Dominio y Persistencia Propuesta #### 3.1 Entidad `InstitutionalBenefit` (Tabla `institutional_benefits`) - `id` (Integer, PK) - `title` (String 150): Nombre de la promoción o convenio (ej: "20% en Cafetería La Estación"). - `partner_name` (String 120): Empresa o comercio asociado (ej: "Café Martínez Central"). - `category` (String 50): Categoría (`GASTRONOMIA`, `LIBRERIA`, `TECNOLOGIA`, `SALUD_DEPORTE`, `IDIOMAS`, `CULTURA`, `SERVICIOS`). - `discount_label` (String 80): Etiqueta destacada (ej: "20% OFF", "2x1", "$1.500 de ahorro"). - `description` (Text): Descripción detallada del convenio. - `terms_conditions` (Text): Cláusulas, días de validez y restricciones. - `target_roles` (String 50): Perfiles habilitados (`ALL`, `ALUMNO`, `DOCENTE`, `BEDELIA`). - `building_id` (Integer FK nullable -> `buildings.id`): Sede aplicable o `None` para todas. - `coupon_code` (String 50, nullable): Código promocional alfanumérico. - `valid_from` (Date): Inicio de vigencia. - `valid_until` (Date, nullable): Fin de vigencia. - `is_active` (Boolean, default True): Switch de publicación inmediata. - `image_url` (String 255, nullable): Imagen o logotipo representativo. - `created_by_user_id` (Integer FK -> `users.id`): Usuario responsable del alta. - `created_at`, `updated_at` (DateTime): Timestamps de auditoría. #### 3.2 Entidad `AccessLogQR` (Tabla `access_logs_qr`) - `id` (Integer, PK) - `user_id` (Integer FK -> `users.id`): Alumno o docente que ingresó. - `building_id` (Integer FK -> `buildings.id`): Sede donde se realizó el escaneo. - `scanned_by_user_id` (Integer FK -> `users.id`): Personal de recepción que escaneó. - `scanned_at` (DateTime): Momento exacto del ingreso. - `status` (String 20): `AUTORIZADO`, `DENEGADO`, `RESTRINGIDO`. - `reason` (String 150, nullable): Causa del rechazo o notas operativas. --- ### 4. Criterios de Aceptación y Validación 1. **ABM Bedelía y Admin**: Capacidad de crear, editar, pausar y eliminar beneficios con validación de fechas y roles. 2. **Catálogo para Alumnos y Docentes**: Navegación fluida por tarjetas con filtros por categoría y búsqueda en tiempo real. 3. **Integración UdeCi**: Respuestas en lenguaje natural sobre convenios basadas en los datos reales cargados. 4. **Credencial QR**: Generación dinámica en el portal del usuario. 5. **Consola Recepción**: Escaneo con cámara y visualización en tiempo real de identidad y aulas de cursada del día.