feat(benefits-reception): add institutional benefits, QR digital card & reception access control (SDD-012 v3.8.39)

This commit is contained in:
2026-10-27 23:34:57 -03:00
parent e45eb972dd
commit e5e6bfa094
30 changed files with 2994 additions and 11 deletions
+1 -1
View File
@@ -7,7 +7,7 @@ from typing import Any
from database import db, get_db, engine, SessionLocal, session
from config.config import Config
__version__ = "3.8.38"
__version__ = "3.8.39"
class DummyContext:
def __enter__(self):
+5 -1
View File
@@ -14,6 +14,8 @@ from .setting import SystemSetting
from .grade import MilestoneGrade
from .sync_task import MoodleSyncTask
from .knowledge_chunk import KnowledgeChunk
from .institutional_benefit import InstitutionalBenefit
from .access_log_qr import AccessLogQR
__all__ = [
'User',
@@ -40,5 +42,7 @@ __all__ = [
'SystemSetting',
'MilestoneGrade',
'MoodleSyncTask',
'KnowledgeChunk'
'KnowledgeChunk',
'InstitutionalBenefit',
'AccessLogQR'
]
+50
View File
@@ -0,0 +1,50 @@
from app import db
from datetime import datetime, timezone
from typing import Dict, Any
class AccessLogQR(db.Model):
"""
Registro y trazabilidad de ingresos escaneados por código QR en Recepción (SDD-012).
Permite auditar el ingreso físico de alumnos y docentes a las sedes institucionales.
"""
__tablename__ = 'access_logs_qr'
__allow_unmapped__ = True
id = db.Column(db.Integer, primary_key=True)
user_id = db.Column(db.Integer, db.ForeignKey('users.id', ondelete='CASCADE'), nullable=False, index=True)
building_id = db.Column(db.Integer, db.ForeignKey('buildings.id', ondelete='SET NULL'), nullable=True, index=True)
scanned_by_user_id = db.Column(db.Integer, db.ForeignKey('users.id', ondelete='SET NULL'), nullable=True)
scanned_at = db.Column(
db.DateTime,
default=lambda: datetime.now(timezone.utc).replace(tzinfo=None),
nullable=False,
index=True
)
status = db.Column(db.String(20), default='AUTORIZADO', nullable=False) # AUTORIZADO, DENEGADO, RESTRINGIDO
reason = db.Column(db.String(150), nullable=True)
# Relaciones
user = db.relationship('User', foreign_keys=[user_id], backref=db.backref('qr_access_logs', lazy='dynamic'))
building = db.relationship('Building', foreign_keys=[building_id])
scanned_by = db.relationship('User', foreign_keys=[scanned_by_user_id])
def __init__(self, **kwargs):
super().__init__(**kwargs)
def to_dict(self) -> Dict[str, Any]:
"""Serializa el registro de acceso a diccionario JSON."""
return {
'id': self.id,
'user_id': self.user_id,
'user_name': self.user.name if self.user else 'Desconocido',
'user_dni': self.user.document_number if self.user else None,
'user_role': self.user.role if self.user else None,
'building_id': self.building_id,
'building_name': self.building.name if self.building else 'Sede Desconocida',
'scanned_by_user_id': self.scanned_by_user_id,
'scanned_by_name': self.scanned_by.name if self.scanned_by else 'Sistema',
'scanned_at': self.scanned_at.isoformat() if self.scanned_at else None,
'status': self.status,
'reason': self.reason
}
@@ -0,0 +1,94 @@
from app import db
from datetime import datetime, timezone, date
from typing import Optional, Dict, Any
class InstitutionalBenefit(db.Model):
"""
Modelo de Beneficios y Convenios Comerciales Institucionales para UniCABA (SDD-012).
Permite a Bedelía y Administradores cargar promociones, descuentos y convenios
con comercios (cafeterías, librerías, tecnología, salud) para alumnos y docentes.
"""
__tablename__ = 'institutional_benefits'
__allow_unmapped__ = True
id = db.Column(db.Integer, primary_key=True)
title = db.Column(db.String(150), nullable=False, index=True)
partner_name = db.Column(db.String(120), nullable=False, index=True)
category = db.Column(db.String(50), nullable=False, default='GENERAL', index=True)
discount_label = db.Column(db.String(80), nullable=False)
description = db.Column(db.Text, nullable=True)
terms_conditions = db.Column(db.Text, nullable=True)
target_roles = db.Column(db.String(100), nullable=False, default='ALL')
building_id = db.Column(db.Integer, db.ForeignKey('buildings.id', ondelete='SET NULL'), nullable=True, index=True)
coupon_code = db.Column(db.String(50), nullable=True)
valid_from = db.Column(db.Date, nullable=False, default=date.today)
valid_until = db.Column(db.Date, nullable=True)
is_active = db.Column(db.Boolean, default=True, nullable=False, index=True)
image_url = db.Column(db.String(255), nullable=True)
created_by_user_id = db.Column(db.Integer, db.ForeignKey('users.id', ondelete='SET NULL'), nullable=True)
created_at = db.Column(db.DateTime, default=lambda: datetime.now(timezone.utc).replace(tzinfo=None))
updated_at = db.Column(
db.DateTime,
default=lambda: datetime.now(timezone.utc).replace(tzinfo=None),
onupdate=lambda: datetime.now(timezone.utc).replace(tzinfo=None)
)
# Relaciones
building = db.relationship('Building', backref=db.backref('institutional_benefits', lazy='dynamic'))
creator = db.relationship('User', foreign_keys=[created_by_user_id])
def __init__(self, **kwargs):
super().__init__(**kwargs)
@property
def is_currently_valid(self) -> bool:
"""Determina si el convenio está activo y dentro de su rango de vigencia."""
if not self.is_active:
return False
today = date.today()
if self.valid_from and self.valid_from > today:
return False
if self.valid_until and self.valid_until < today:
return False
return True
def applies_to_role(self, role: str) -> bool:
"""Verifica si el beneficio aplica al rol indicado (alumno, docente, bedelia, admin)."""
if not role:
return False
target = (self.target_roles or 'ALL').upper()
if 'ALL' in target or 'TODOS' in target:
return True
r = role.strip().upper()
if r in target:
return True
if r in ['ESTUDIANTE', 'ALUMNO'] and ('ALUMNO' in target or 'ESTUDIANTE' in target):
return True
if r in ['DOCENTE', 'PROFESOR', 'TEACHER'] and ('DOCENTE' in target or 'PROFESOR' in target):
return True
return False
def to_dict(self) -> Dict[str, Any]:
"""Serializa la entidad a diccionario compatible con JSON."""
return {
'id': self.id,
'title': self.title,
'partner_name': self.partner_name,
'category': self.category,
'discount_label': self.discount_label,
'description': self.description,
'terms_conditions': self.terms_conditions,
'target_roles': self.target_roles,
'building_id': self.building_id,
'building_name': self.building.name if self.building else 'Todas las Sedes',
'coupon_code': self.coupon_code,
'valid_from': self.valid_from.isoformat() if self.valid_from else None,
'valid_until': self.valid_until.isoformat() if self.valid_until else None,
'is_active': self.is_active,
'is_currently_valid': self.is_currently_valid,
'image_url': self.image_url,
'created_by_user_id': self.created_by_user_id,
'created_at': self.created_at.isoformat() if self.created_at else None,
'updated_at': self.updated_at.isoformat() if self.updated_at else None,
}
@@ -18,6 +18,7 @@ from app.models.reservation import Reservation
from app.models.enrollment import StudentEnrollment
from app.models.milestone import AcademicMilestone, MilestoneType
from app.models.grade import MilestoneGrade
from app.models.institutional_benefit import InstitutionalBenefit
from app import db
from app.models.user import User
from app.services.gradebook_service import GradebookService
@@ -621,6 +622,39 @@ class LiveContextService:
for rm in matched_rooms:
cap = rm.capacity_display
lines.append(f"• Aula {rm.code_display} (Piso: {rm.floor_display}, Capacidad: {cap})")
# E. Búsqueda de Convenios y Beneficios Institucionales
benefit_keywords = [
'convenio', 'convenios', 'beneficio', 'beneficios', 'descuento', 'descuentos',
'promocion', 'promociones', 'promo', 'cafeteria', 'cafe', 'comida', 'almuerzo',
'libreria', 'fotocopia', 'deporte', 'gimnasio', 'salud', 'cupon'
]
if any(bk in q_lower for bk in benefit_keywords):
from datetime import date
today_b = date.today()
active_b = (
InstitutionalBenefit.query
.filter(
InstitutionalBenefit.is_active.is_(True),
InstitutionalBenefit.valid_from <= today_b,
or_(
InstitutionalBenefit.valid_until.is_(None),
InstitutionalBenefit.valid_until >= today_b
)
)
.order_by(InstitutionalBenefit.title.asc())
.limit(8)
.all()
)
matching_b = [b for b in active_b if b.applies_to_role(role)]
if matching_b:
lines.append("\nCONVENIOS Y BENEFICIOS INSTITUCIONALES ACTIVOS:")
for ben in matching_b:
bld_str = f"en {ben.building.name}" if ben.building else "en Todas las Sedes"
coupon_str = f" | Código Cupón: {ben.coupon_code}" if ben.coupon_code else ""
lines.append(f"• {ben.title}: {ben.discount_label} en {ben.partner_name} ({ben.category} {bld_str}){coupon_str}. {ben.description or ''}")
else:
lines.append("\nCONVENIOS Y BENEFICIOS: No se encontraron promociones activas registradas para la consulta.")
except Exception:
pass
+185
View File
@@ -0,0 +1,185 @@
import hmac
import hashlib
import json
import base64
import uuid
from datetime import datetime, timedelta, timezone, date
from typing import Dict, Any, Optional, Tuple, List
import jwt
from config.config import Config
from app import db
from app.models.user import User
from app.models.reservation import Reservation
from app.models.classroom import Classroom
from app.models.building import Building
from app.models.enrollment import StudentEnrollment
from app.models.subject import Commission, Subject
from schemas.reception_dto import TodayClassDTO
class QRSecurityService:
"""
Servicio de emisión, validación criptográfica y resolución académica para
la Credencial Digital y el Control de Acceso por QR en Recepción (SDD-012).
"""
QR_TOKEN_TYPE = "credential_qr"
DEFAULT_VALID_HOURS = 72
@classmethod
def _get_secret(cls) -> str:
return getattr(Config, 'SECRET_KEY', 'unicaba-secret-qr-key')
@classmethod
def generate_qr_token(cls, user: User, hours_valid: int = DEFAULT_VALID_HOURS) -> str:
"""
Emite un token JWT firmado de credencial institucional para el usuario.
Contiene identificación, rol, DNI y tiempo de expiración.
"""
now = datetime.now(timezone.utc)
payload = {
"sub": str(user.id),
"dni": user.document_number or "",
"name": user.name or "",
"role": (user.role or "ALUMNO").upper(),
"type": cls.QR_TOKEN_TYPE,
"jti": str(uuid.uuid4())[:8],
"iat": now,
"exp": now + timedelta(hours=hours_valid)
}
return jwt.encode(payload, cls._get_secret(), algorithm="HS256")
@classmethod
def decode_and_resolve_user(cls, raw_input: str) -> Tuple[Optional[User], str, str]:
"""
Decodifica y valida el token escaneado. Soporta:
1. Token JWT firmado institucional.
2. Formato prefijado 'UNICABA:QR:<token>'.
3. Formato fallback por DNI 'DNI:<documento>' o número de documento directo.
Retorna: (User or None, status: 'AUTORIZADO' | 'DENEGADO' | 'RESTRINGIDO', reason: str)
"""
if not raw_input or not raw_input.strip():
return None, "DENEGADO", "El código escaneado está vacío."
clean = raw_input.strip()
# Si viene con prefijo UNICABA:QR:
if clean.startswith("UNICABA:QR:"):
clean = clean[len("UNICABA:QR:"):].strip()
# 1. Intentar validar como JWT institucional
if clean.count(".") == 2:
try:
payload = jwt.decode(
clean,
cls._get_secret(),
algorithms=["HS256"],
options={"verify_exp": True}
)
if payload.get("type") != cls.QR_TOKEN_TYPE:
return None, "DENEGADO", "El token no corresponde a una credencial institucional válida."
user_id = payload.get("sub")
user = User.query.get(int(user_id)) if user_id else None
if not user:
return None, "DENEGADO", "Usuario no encontrado en la base de datos."
if not user.is_active:
return user, "RESTRINGIDO", "La cuenta del usuario se encuentra inactiva o suspendida."
return user, "AUTORIZADO", "Credencial institucional válida y activa."
except jwt.ExpiredSignatureError:
return None, "DENEGADO", "La credencial digital ha expirado. El alumno debe abrir su app para renovarla."
except jwt.PyJWTError as e:
return None, "DENEGADO", f"Firma criptográfica inválida: {str(e)}"
# 2. Fallback: Lectura de pistola óptica o documento directo (ej: 'DNI:12345678' o '12345678')
doc_num = clean
if doc_num.upper().startswith("DNI:"):
doc_num = doc_num[4:].strip()
user = User.query.filter_by(document_number=doc_num).first()
if user:
if not user.is_active:
return user, "RESTRINGIDO", "Usuario inactivo en el sistema institucional."
return user, "AUTORIZADO", "Identificación validada por documento de identidad."
return None, "DENEGADO", f"No se encontró ningún estudiante o docente con DNI {doc_num}."
@classmethod
def get_todays_classes_for_user(cls, user: User, target_date: Optional[date] = None) -> List[TodayClassDTO]:
"""
Recupera el cronograma presencial y virtual asignado para el usuario en la fecha indicada (por defecto hoy).
Indica sede, aula física, piso, horarios y nombre del docente.
"""
ref_date = target_date or date.today()
user_role = (user.role or "").lower()
classes: List[TodayClassDTO] = []
start_of_day = datetime.combine(ref_date, datetime.min.time())
end_of_day = datetime.combine(ref_date, datetime.max.time())
# Si el usuario es docente: reservas donde él es el docente asignado
if "docente" in user_role or "profesor" in user_role or "teacher" in user_role:
reservations = Reservation.query.filter(
Reservation.user_id == user.id,
Reservation.start_time >= start_of_day,
Reservation.start_time <= end_of_day,
Reservation.status.in_(["CONFIRMED", "PENDING"])
).order_by(Reservation.start_time.asc()).all()
for r in reservations:
comm = r.commission
subj_name = comm.subject.name if (comm and comm.subject) else "Clase Universitaria"
comm_name = comm.name if comm else "Comisión"
classroom = r.classroom
bld = classroom.building_entity if classroom else None
classes.append(TodayClassDTO(
subject_name=subj_name,
commission_name=comm_name,
classroom_name=classroom.name if classroom else "Aula no asignada",
building_name=bld.name if bld else "Sede Central",
floor=getattr(classroom, "floor", 1),
start_time=r.start_time.strftime("%H:%M"),
end_time=r.end_time.strftime("%H:%M"),
teacher_name=user.name
))
return classes
# Si el usuario es alumno: comisiones donde está inscripto
enrollments = StudentEnrollment.query.filter_by(student_id=user.id).all()
comm_ids = [e.commission_id for e in enrollments if e.commission_id]
if not comm_ids:
return []
reservations = Reservation.query.filter(
Reservation.commission_id.in_(comm_ids),
Reservation.start_time >= start_of_day,
Reservation.start_time <= end_of_day,
Reservation.status.in_(["CONFIRMED", "PENDING"])
).order_by(Reservation.start_time.asc()).all()
for r in reservations:
comm = r.commission
subj_name = comm.subject.name if (comm and comm.subject) else "Materia Cursada"
comm_name = comm.name if comm else "Comisión"
classroom = r.classroom
bld = classroom.building_entity if classroom else None
teacher_name = r.user.name if r.user else "Docente Titular"
classes.append(TodayClassDTO(
subject_name=subj_name,
commission_name=comm_name,
classroom_name=classroom.name if classroom else "Aula no asignada",
building_name=bld.name if bld else "Sede Central",
floor=getattr(classroom, "floor", 1),
start_time=r.start_time.strftime("%H:%M"),
end_time=r.end_time.strftime("%H:%M"),
teacher_name=teacher_name
))
return classes