# Desglose de Tareas: Portal de Beneficios, Convenios y Control de Acceso QR (SDD-012) ## Tareas de Implementación - [x] **Tarea 1: Modelos de Persistencia SQLAlchemy (`InstitutionalBenefit` y `AccessLogQR`)** - **Estimación**: 25 min - **Acciones**: - Crear `backend/models/institutional_benefit.py` con campos de título, comercio, categoría, descuento, términos, roles objetivo, fechas de vigencia y switch de estado activo. - Crear `backend/models/access_log_qr.py` para trazabilidad de ingresos escaneados por sede y personal de recepción. - Importar y registrar los modelos en `backend/models/__init__.py`. - **Hecho cuando**: Las tablas se crean correctamente en PostgreSQL/SQLite sin errores de clave foránea ni regresiones de inicialización. - [x] **Tarea 2: DTOs Pydantic v2 y Endpoints RESTful de Beneficios (`routers/benefits.py`)** - **Estimación**: 30 min - **Acciones**: - Crear `backend/schemas/benefit_dto.py` con validaciones de campos (`min_length`, fechas, roles). - Crear `backend/routers/benefits.py` con operaciones CRUD (`GET /`, `GET /{id}`, `POST /`, `PUT /{id}`, `PATCH /{id}/toggle-status`, `DELETE /{id}`). - Proteger rutas de escritura exigiendo roles `ADMIN` o `BEDELIA`. - Registrar el router en `backend/main.py`. - **Hecho cuando**: Peticiones a `/api/v1/benefits` responden con códigos HTTP semánticos (200, 201, 204, 403, 404, 422) y aparecen en OpenAPI Swagger UI (`/docs`). - [x] **Tarea 3: Servicio de Seguridad QR y Endpoints de Recepción (`routers/reception.py`)** - **Estimación**: 30 min - **Acciones**: - Crear `backend/app/services/qr_security_service.py` para generar y verificar tokens de credencial firmados con HMAC-SHA256 institucional. - Crear `backend/schemas/reception_dto.py` para los contratos de verificación de acceso. - Crear `backend/routers/reception.py` con `/api/v1/reception/verify-qr` y `/api/v1/reception/recent-logs`. - Integrar la búsqueda de clases presenciales del día para mostrar el aula y piso asignado al momento de ingresar. - Registrar el router en `backend/main.py`. - **Hecho cuando**: Un escaneo de QR válido responde con `status: AUTORIZADO`, datos del alumno y sus aulas asignadas del día en < 300 ms. - [x] **Tarea 4: Integración de Convenios en el Motor Conversacional de UdeCi** - **Estimación**: 20 min - **Acciones**: - Modificar `backend/app/services/live_context_service.py` para inyectar los convenios vigentes en el contexto en vivo de UdeCi. - Actualizar las reglas del System Prompt en `backend/routers/ai_chat.py` para responder consultas sobre descuentos en cafeterías, librerías y beneficios institucionales reales. - **Hecho cuando**: Al consultar a UdeCi *"¿Qué descuentos hay en cafetería?"*, responde citando comercios, porcentaje y condiciones reales de la base de datos. - [x] **Tarea 5: Panel de Gestión de Convenios para Bedelía y Admin (Frontend BFF)** - **Estimación**: 30 min - **Acciones**: - Crear controlador `frontend/src/routes/benefits.js` y vista `frontend/views/benefits/manage.html`. - Implementar tabla de convenios con badges de categoría, switches de activación rápida y modal de alta/edición. - Incorporar el enlace en el menú lateral de Bedelía y Administración (`sidebar.html`). - **Hecho cuando**: Bedelía puede dar de alta un convenio con descuento, fechas y sede desde la interfaz web con feedback visual inmediato. - [x] **Tarea 6: Catálogo de Beneficios y Credencial Digital QR para Alumnos y Docentes** - **Estimación**: 30 min - **Acciones**: - Crear vista `frontend/views/benefits/catalog.html` con tarjetas estilo marketplace, buscador interactivo y filtro por categoría (Cafetería, Librería, etc.). - Crear vista `frontend/views/credential/card.html` ("Mi Credencial Digital") mostrando foto, datos institucionales y código QR dinámico. - Añadir accesos en el menú de Estudiante y Docente. - **Hecho cuando**: Un estudiante puede explorar los convenios vigentes, abrir el cupón y visualizar su Credencial QR en su teléfono. - [x] **Tarea 7: Consola de Escáner de Recepción y Control de Acceso en Vivo** - **Estimación**: 30 min - **Acciones**: - Crear vista `frontend/views/reception/scanner.html` con lector de cámara (`html5-qrcode`) y soporte para pistola de código de barras USB. - Integrar modal/tarjeta de validación instantánea con indicadores visuales (verde/rojo) y cronograma de clases de hoy con sede, aula y piso. - Configurar permisos en el BFF para el rol `RECEPCION` y administradores. - **Hecho cuando**: Al escanear un QR con la cámara, la pantalla muestra de inmediato la foto, el estado de matrícula y el aula donde cursa hoy. - [x] **Tarea 8: Suite de Pruebas Automatizadas Backend y Cobertura E2E** - **Estimación**: 20 min - **Acciones**: - Crear `backend/tests/test_benefits_and_reception.py` cubriendo: - CRUD de beneficios y restricciones de roles. - Validación de vigencia de fechas. - Generación y verificación de tokens QR. - Registro de logs de acceso. - Respuestas de UdeCi sobre beneficios en vivo. - Ejecutar `pytest tests/ -v` asegurando 100% de tests pasando. - **Hecho cuando**: Todos los tests de la suite pasan exitosamente sin fallos ni warnings no controlados. - [x] **Tarea 9: Bump de Versión, Git Push y Despliegue Continuo en Producción (LXC 10.0.0.217)** - **Estimación**: 20 min - **Acciones**: - Incrementar versión semántica en `package.json`, `app.js`, `__init__.py`, `setup.py`, `CHANGELOG.md` y `MEMORY.md`. - Ejecutar `git push origin dev`. - Desplegar en el contenedor de producción (`10.0.0.217`) y validar HTTP 200 en `/version`. - **Hecho cuando**: Producción corre la nueva versión con los módulos de beneficios y recepción operativos.