Documentación técnica — Full Vuelos

Full Vuelos es una aplicación de práctica del campus Full Advanced: una aerolínea de bajo costo (identidad visual inspirada en Wingo) que sirve como objetivo realista para practicar testing manual y automatizado.

Esta sección documenta las reglas de negocio exactas que implementa el código — es la referencia para escribir casos de prueba contra la app.

Contenido

1. Autenticación y sesiones — usuarios propios, sesión aparte, registro público con reservas de ejemplo.
2. Tarifas y precios — multiplicadores por tarifa, tipos de pasajero, extras, monedas de visualización.
3. Reservas e inventario — PNR, validaciones, asientos y atomicidad.
4. Cancelación y check-in — ventanas de tiempo, selección de asiento y restauración de inventario.
5. Pagos simulados — validación de tarjeta (Luhn), qué se almacena.

Datos de demostración

• Inventario: vuelos diarios en 16 rutas (32 sentidos) durante los próximos 45 días, generados determinísticamente al sembrar o reiniciar el playground. La siembra completa las rutas que falten sin tocar las existentes (top-up). Cada vuelo tiene 180 asientos; la disponibilidad inicial es determinística (120–179) para que las demos sean reproducibles.
• Usuario demo: viajero.demo / Vuelos2026! con dos reservas (una cancelable a ~5 días, una dentro de la ventana de check-in).
• Cuentas nuevas: el registro público siembra las mismas dos reservas de ejemplo para el viajero recién creado.
• Reinicio: la base es compartida por todos y cada noche (06:03 UTC) se vacían todas las tablas de Full Vuelos y se vuelve a sembrar exactamente este estado, con el inventario de los 45 días siguientes. Las cuentas y reservas creadas durante el día desaparecen.

Convenciones

• Toda la UI es solo en español, deliberadamente.
• Todos los importes se almacenan en USD con dos decimales, redondeo half-up. El selector de moneda solo cambia la visualización, con tasas fijas ficticias (ver Tarifas y precios).
• Las violaciones de reglas de negocio responden HTTP 400 con el mensaje en pantalla; los errores de autenticación son 401 genéricos; los recursos ajenos o inexistentes son 404. Una selección de vuelo inválida o caduca en /reservar (GET) redirige (303) a la página principal con un aviso amable en lugar de mostrar un error crudo.

Autenticación y sesiones

Modelo

Full Vuelos tiene su propia tabla de usuarios (vuelos_users) y su propia cookie de sesión (fv_sesion, firmada, válida 14 días y limitada a /practica-vuelos). No hay relación con las cuentas del campus Full Advanced:

• Iniciar sesión en el campus no abre Full Vuelos, y viceversa.
• Cerrar sesión en Full Vuelos no cierra la sesión del campus.
• No hay rol de backoffice: todos los usuarios son viajeros (decisión de producto, igual que Full Bazar).

Registro público

POST /practica-vuelos/registro crea una cuenta y abre sesión de inmediato, redirigiendo a la página principal con el aviso de bienvenida. Si el inventario de vuelos existe, la cuenta recibe las mismas dos reservas de ejemplo que viajero.demo (seed_example_bookings): una ida y vuelta BOG ↔ BAQ cancelable (tarifa Plus + maleta documentada + selección de asiento, ~5 días) y un solo-trayecto BOG → MDE dentro de la ventana de check-in. Vuelos agotados o inventario ausente simplemente omiten la reserva correspondiente — el registro nunca falla por esto.

Las contraseñas se almacenan con hash Argon2id.

Login

POST /practica-vuelos/login. Cualquier fallo (usuario inexistente, contraseña errada, cuenta desactivada) responde 401 con el mismo mensaje genérico Usuario o contraseña inválidos. — nunca se revela cuál parte falló.

El parámetro next redirige tras el login, pero solo a rutas locales de /practica-vuelos; cualquier otro valor cae a la página principal (anti open-redirect).

Páginas protegidas

Requieren sesión de Full Vuelos: el flujo de reserva (/reservar*), Mis reservas, el detalle de reserva, cancelación y check-in. Un visitante anónimo es redirigido (303) al login con ?next= apuntando a su destino original, query string incluida — la búsqueda y el manual son públicos.

Cancelación y check-in

Cancelación

POST /practica-vuelos/reservas/{codigo}/cancelar.

Reglas:

• Solo el dueño de la reserva puede cancelarla (un código ajeno responde 404, no 403 — no se revela la existencia).
• Solo reservas confirmadas; cancelar dos veces responde La reserva ya está cancelada.
• Solo si faltan más de 24 horas para el primer vuelo: Solo puedes cancelar hasta 24 horas antes del primer vuelo.

Efectos de una cancelación exitosa:

• Estado → cancelled (definitivo; no hay reactivación).
• Los asientos de todos los tramos vuelven al inventario (sumando los pasajeros con silla, con tope en seats_total), en la misma transacción con bloqueo de filas.

Selección de asiento

GET|POST /practica-vuelos/reservas/{codigo}/asientos.

• Derecho a elegir (can_select_seats): reserva confirmada, sin check-in, primer vuelo en el futuro y (tarifa Full en algún tramo o extra seat_selection comprado o ventana de check-in abierta — entonces es gratis).
• Se elige un asiento por pasajero con silla (en orden de pasajeros) sobre el vuelo de ida (mapa 30 filas × letras A–F, estilo A320). Los bebés nunca reciben asiento.
• Validaciones: asiento existente (El asiento X no existe.), no repetido dentro de la misma selección (El asiento X está repetido.), no ocupado por otra reserva del mismo vuelo (El asiento X ya está ocupado.).
• Re-elegir está permitido hasta el check-in: los asientos actuales de la propia reserva no cuentan como ocupados.
• Sin derecho, el GET responde 400 con el detalle de la reserva y el mensaje: La selección de asiento está incluida en la tarifa Full, se puede comprar como extra, o es gratis durante el check-in (24 horas antes del vuelo).

Check-in

POST /practica-vuelos/reservas/{codigo}/checkin (también listado en /checkin con las reservas elegibles).

Reglas:

• Misma regla de propiedad (404 para códigos ajenos).
• Ventana: [salida del primer vuelo − 24 h, salida). Antes: El check-in abre 24 horas antes del primer vuelo y cierra a la hora de salida.
• Una sola vez por reserva: Esta reserva ya hizo el check-in.
• Una reserva cancelada nunca es elegible.

Efectos del check-in:

• checked_in_at queda marcado.
• Los asientos ya elegidos se conservan. Cada pasajero con silla sin asiento recibe uno asignado automáticamente en orden de filas (1A, 1B, …, letras A–F), saltando los asientos ya ocupados por otros pasajeros del mismo vuelo. La asignación es determinística y nunca repite asientos. Los bebés quedan sin asiento (En regazo).

Matriz de estados visible en la UI

Pagos simulados

El paso de pago no procesa cargos reales: no hay pasarela, no hay red bancaria. Aun así valida como un formulario real, porque el propósito de la aplicación es practicar pruebas contra reglas verídicas.

Validaciones de la tarjeta

Tarjeta de prueba canónica de la demo: 4111 1111 1111 1111 con cualquier vencimiento futuro y cualquier CVV válido.

Qué se almacena

• Solo los últimos 4 dígitos (card_last4) en la reserva, para mostrar ···· 1111 en el detalle.
• El número completo, el CVV y el titular nunca se persisten ni se registran en logs.

Propiedades del pago

• Sin cobro parcial: si cualquier validación falla —tarjeta, pasajeros, tarifa, asientos— no se crea nada y el usuario vuelve al paso correspondiente con el mensaje.
• Consistencia de precio: el total cobrado se recalcula en el servidor en el momento de confirmar; el total mostrado en pantalla nunca se confía como entrada.
• Tarjeta válida ≠ vuelo garantizado: si los asientos se agotaron entre la cotización y el pago, la reserva falla con El vuelo X no tiene suficientes asientos disponibles. y no se cobra nada.

Reservas e inventario

La reserva (PNR)

Una reserva es un registro con código PNR de 6 caracteres del alfabeto sin ambigüedades ABCDEFGHJKLMNPQRSTUVWXYZ23456789 (sin 0/O ni 1/I), generado al azar hasta ser único. Un viaje de ida y vuelta es una sola reserva con dos tramos (vuelos_booking_legs, posición 0 = ida, 1 = regreso).

Validaciones al reservar

Todas se verifican dos veces: al cotizar (paso de pago) y dentro de la transacción (paso de confirmación). Cualquier violación responde 400 con el mensaje correspondiente:

Inventario de asientos

• Cada vuelo tiene seats_total (180) y seats_available.
• Al confirmar la reserva, seats_available se descuenta en el conteo con asiento (adultos + menores; los bebés en regazo no descuentan) por tramo, en la misma transacción que crea reserva + tramos + pasajeros: o todo o nada.
• Los vuelos se bloquean con with_for_update en orden de id (mismo idioma anti-deadlock que las transferencias del Banco Americano): dos compras simultáneas del último asiento no pueden ganar ambas.
• La búsqueda solo muestra vuelos con seats_available >= pasajeros_con_asiento, así que el agotamiento solo se manifiesta entre la búsqueda y el pago (condición de carrera clásica — ejercicio de testing intencional).

Búsqueda

validate_search impone: origen dentro del mapa direccional de venta (ROUTE_DESTINATIONS: BAQ, CCS, CLO, GUA, HAV), destino servido por ese origen, ida no en el pasado, regreso ≥ ida (si aplica), al menos 1 adulto, ≤ 1 bebé por adulto y ≤ 9 personas en total. Los resultados se ordenan por hora de salida y solo incluyen vuelos del día consultado con estado scheduled.

Los selectores de ciudad se ordenan alfabéticamente por nombre de ciudad (ignorando acentos), no por código IATA.

Tira de fechas (resultados)

date_strip calcula, para la ruta y el día consultados, la disponibilidad de los 3 días anteriores y 3 posteriores (nunca en el pasado): cada día sabe si hay vuelos con asientos suficientes y el precio base más barato. La UI pinta de gris y deshabilita los días sin vuelos (title="No hay vuelos disponibles") y enlaza los disponibles a /buscar conservando ruta, tipo de viaje y composición de pasajeros. Cuando no hay selección posible, el botón Continuar se deshabilita y GET /reservar con selección inválida redirige a la página principal con ?aviso=seleccion.

Mis reservas (gestión)

filter_bookings aplica búsqueda por código (substring, sin mayúsculas) y filtro de estado (todas / confirmada / checkin / cancelada); split_bookings separa el resultado en próximas (confirmadas con primer vuelo futuro, más cercanas primero) e historial (voladas o canceladas, más recientes primero, plegadas en la UI).

Tarifas y precios

Tarifas

Cada vuelo tiene un precio base (USD, tarifa Básica, por pasajero). Las tarifas superiores multiplican el precio base y agregan inclusiones:

La tarifa se elige una vez por reserva y aplica a todos los tramos (ida y regreso).

Tipos de pasajero

Cada pasajero tiene un tipo (pax_type):

Reglas del grupo (validadas en búsqueda y en la reserva):

• Al menos 1 adulto: Debe viajar al menos un adulto.
• Máximo 1 bebé por adulto: Cada bebé debe viajar en el regazo de un adulto: máximo 1 bebé por adulto.
• Máximo 9 personas en total: El grupo máximo permitido son 9 personas por reservación.

Los cálculos de precio e inventario usan el conteo con asiento (seated = adultos + menores): los bebés no pagan ni descuentan inventario.

Extras

Los extras se compran por separado y aplican a todos los pasajeros con asiento de la reserva (regla deliberada de simplificación del demo):

Regla de inclusión: un extra que la tarifa ya incluye no se puede comprar — la UI no lo muestra y el servicio rechaza la compra con La tarifa <tarifa> ya incluye este extra. Con tarifa Full no hay extras disponibles.

Monedas de visualización

Los precios se almacenan en USD; el selector 💱 de la barra superior (cookie fv_currency, 180 días) solo cambia cómo se muestran — incluidos búsqueda, tarifas, extras, resumen de pago y detalle de reserva. Las tasas son fijas y ficticias (entorno de demostración, sin feed de mercado):

Un código desconocido en la cookie o en el parámetro cae a USD. Formato: US$ 49.99 para USD; $ 209.958 COP para el resto (código como sufijo).

Fórmula del total

total = (Σ precio_tarifa(tramo) + Σ extras) × pasajeros_con_asiento

• precio_tarifa(tramo) = base_price(tramo) × multiplicador(tarifa), redondeado a 2 decimales half-up por tramo.
• El total final se redondea a 2 decimales half-up.
• La cotización del paso de pago y el cobro del paso de confirmación ejecutan la misma validación: el precio nunca cambia entre pantallas a menos que cambie el inventario.

Ejemplo

BOG→BAQ (base $58.99) ida y vuelta, tarifa Plus, 2 adultos + 1 bebé, maleta documentada como extra:

• Tramos: $58.99 × 1.25 = $73.74 por tramo y pasajero con asiento → $147.48 por pasajero
• Extra: $35.00 por pasajero con asiento (la Plus no incluye maleta documentada)
• Total: ($147.48 + $35.00) × 2 = $364.96 (el bebé no suma)