feat(benefits-reception): add institutional benefits, QR digital card & reception access control (SDD-012 v3.8.39)
This commit is contained in:
@@ -0,0 +1,93 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user