# 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 ```mermaid 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.