feat(benefits-reception): add institutional benefits, QR digital card & reception access control (SDD-012 v3.8.39)
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user