Files
admin-edu-space/specs/012-beneficios-convenios-recepcion-qr/plan.md
T

5.8 KiB

Plan de Arquitectura Técnica (SDD-012)

Módulo: Portal de Beneficios, Convenios Comerciales y Control de Acceso por QR con IA (UdeCi) y Rol Recepción


1. Diagrama de Arquitectura del Sistema

graph TD
    subgraph "Perfiles y Clientes Web"
        ALUMNO[Estudiante / Docente: Catálogo & Credencial QR]
        BEDELIA[Bedelía / Admin: Panel ABM de Convenios]
        RECEPCION[Personal de Recepción: Escáner QR de Acceso]
        CHAT[UdeCi: Tutor Conversacional con IA]
    end

    subgraph "Frontend BFF Node.js / Express (:3000)"
        ROUTES_BENEFITS[/benefits & /benefits/manage]
        ROUTES_RECEPTION[/reception/scanner]
        ROUTES_CREDENTIAL[/credential/my-qr]
        PROXY_API[Axios Interceptors con Bearer Token]
    end

    subgraph "Backend Core FastAPI (:5000)"
        ROUTER_BENEFITS[routers/benefits.py]
        ROUTER_RECEPTION[routers/reception.py]
        ROUTER_AI[routers/ai_chat.py]
        SERVICE_LIVE[services/live_context_service.py]
        SERVICE_QR[services/qr_security_service.py]
    end

    subgraph "Persistencia PostgreSQL"
        TB_BENEFITS[(institutional_benefits)]
        TB_ACCESS_LOGS[(access_logs_qr)]
        TB_USERS[(users)]
        TB_RESERVATIONS[(reservations)]
    end

    ALUMNO -->|1. Consulta beneficios / Mi QR| ROUTES_BENEFITS
    BEDELIA -->|2. Carga / Edita convenios| ROUTES_BENEFITS
    RECEPCION -->|3. Escanea QR de alumno| ROUTES_RECEPTION
    CHAT -->|4. Pregunta por promociones| PROXY_API

    ROUTES_BENEFITS --> PROXY_API
    ROUTES_RECEPTION --> PROXY_API
    PROXY_API --> ROUTER_BENEFITS
    PROXY_API --> ROUTER_RECEPTION
    PROXY_API --> ROUTER_AI

    ROUTER_BENEFITS --> TB_BENEFITS
    ROUTER_RECEPTION --> SERVICE_QR
    SERVICE_QR --> TB_ACCESS_LOGS
    SERVICE_QR --> TB_USERS
    SERVICE_QR --> TB_RESERVATIONS
    ROUTER_AI --> SERVICE_LIVE
    SERVICE_LIVE --> TB_BENEFITS

2. Capas y Módulos a Desarrollar

Capa 1: Persistencia y Modelos SQLAlchemy ORM (backend/models/)

  1. models/institutional_benefit.py:
    • Campos: id, title, partner_name, category, discount_label, description, terms_conditions, target_roles, building_id, coupon_code, valid_from, valid_until, is_active, image_url, created_by_user_id, timestamps.
    • Relaciones con Building y User.
  2. models/access_log_qr.py:
    • Campos: id, user_id, building_id, scanned_by_user_id, scanned_at, status, reason.
    • Relaciones con User y Building.

Capa 2: DTOs y Esquemas Pydantic v2 (backend/schemas/)

  1. schemas/benefit_dto.py:
    • BenefitBaseDTO: Validaciones con Field(..., min_length=3, max_length=150).
    • BenefitCreateDTO: title, partner_name, category, discount_label, description, terms_conditions, target_roles, valid_from, valid_until, etc.
    • BenefitUpdateDTO: Campos opcionales para edición parcial.
    • BenefitResponseDTO: Formato serializado con model_config = ConfigDict(from_attributes=True).
  2. schemas/reception_dto.py:
    • QRVerificationRequestDTO: qr_token: str, building_id: int.
    • QRVerificationResponseDTO: status: str, user_name: str, user_dni: str, user_role: str, matricula_status: str, todays_classes: List[ClassScheduleDTO], scanned_at: datetime.

Capa 3: Endpoints RESTful en FastAPI (backend/routers/)

  1. routers/benefits.py (prefix="/api/v1/benefits", tags=["Benefits & Convenios"]):
    • GET /: Lista de beneficios vigentes con filtros por rol, categoría y sede.
    • GET /{id}: Detalle de un beneficio específico.
    • POST /: Creación de convenio (restringido a ADMIN, BEDELIA). Retorna 201 Created.
    • PUT /{id}: Edición de convenio (restringido a ADMIN, BEDELIA). Retorna 200 OK.
    • PATCH /{id}/toggle-status: Activa o pausa la publicación. Retorna 200 OK.
    • DELETE /{id}: Eliminación lógica o física. Retorna 204 No Content.
  2. routers/reception.py (prefix="/api/v1/reception", tags=["Reception & Access Control"]):
    • POST /verify-qr: Valida el código QR, genera el AccessLogQR y retorna los datos y aulas del día en < 300 ms.
    • GET /recent-logs: Historial de los últimos ingresos escaneados por sede.
    • GET /student-qr-token: Genera el token firmado del alumno para su credencial virtual.

Capa 4: Integración con IA UdeCi y Contexto en Vivo

  1. LiveContextService (backend/app/services/live_context_service.py):
    • Se inyecta la sección CONVENIOS Y BENEFICIOS ACTIVOS: lista resumida de promociones por categoría, descuentos y comercios vigentes.
    • Si un usuario pregunta sobre cafeterías o descuentos, UdeCi responde de inmediato utilizando datos reales de InstitutionalBenefit.
  2. GuideService:
    • Agregar guía paso a paso para que Bedelía aprenda a dar de alta convenios ("¿Cómo publico un nuevo convenio?").

Capa 5: Frontend BFF (Express + Nunjucks + Bootstrap 5)

  1. Rutas y Controladores (frontend/src/routes/):
    • routes/benefits.js: /benefits (catálogo para alumnos/docentes) y /benefits/manage (panel Bedelía).
    • routes/reception.js: /reception/scanner (consola de recepción con escáner de cámara).
    • routes/credential.js: /credential/my-card (credencial digital interactiva con QR).
  2. Vistas Nunjucks:
    • views/benefits/catalog.html: Grid de tarjetas con estilo marketplace, badges de descuento, buscador en vivo y modal de cupón/canje.
    • views/benefits/manage.html: Tabla de gestión con modales de alta/edición, switches de estado y selector de sede.
    • views/reception/scanner.html: Vista de alta velocidad con visor de cámara (html5-qrcode), campo de entrada para pistola USB, tarjeta de validación instantánea y cronograma áulico del día.
    • views/credential/card.html: Credencial universitaria digital con foto, datos de carrera y QR rotativo/seguro.