Files

8.5 KiB

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.