5.8 KiB
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/)
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
BuildingyUser.
- Campos:
models/access_log_qr.py:- Campos:
id,user_id,building_id,scanned_by_user_id,scanned_at,status,reason. - Relaciones con
UseryBuilding.
- Campos:
Capa 2: DTOs y Esquemas Pydantic v2 (backend/schemas/)
schemas/benefit_dto.py:BenefitBaseDTO: Validaciones conField(..., 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 conmodel_config = ConfigDict(from_attributes=True).
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/)
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 aADMIN,BEDELIA). Retorna201 Created.PUT /{id}: Edición de convenio (restringido aADMIN,BEDELIA). Retorna200 OK.PATCH /{id}/toggle-status: Activa o pausa la publicación. Retorna200 OK.DELETE /{id}: Eliminación lógica o física. Retorna204 No Content.
routers/reception.py(prefix="/api/v1/reception",tags=["Reception & Access Control"]):POST /verify-qr: Valida el código QR, genera elAccessLogQRy 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
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.
- Se inyecta la sección
GuideService:- Agregar guía paso a paso para que Bedelía aprenda a dar de alta convenios (
"¿Cómo publico un nuevo convenio?").
- Agregar guía paso a paso para que Bedelía aprenda a dar de alta convenios (
Capa 5: Frontend BFF (Express + Nunjucks + Bootstrap 5)
- 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).
- 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.