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
@@ -0,0 +1,111 @@
# 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.