Este documento desarrolla los treinta casos de uso identificados en el diagrama. Cada uno describe una interacción completa entre un actor y el sistema que termina en un resultado de valor observable para ese actor. ## Plantilla Todos los casos usan la misma estructura. Los **diez casos principales** del sistema —CU01, CU02, CU03, CU07, CU10, CU15, CU18, CU20, CU21 y CU24— se desarrollan con todos los campos de la tabla de abajo y sus flujos alternativos detallados; los veinte restantes usan la forma compacta, con la misma información pero sin desglosar cada rama en su propia tabla. Se eligen como principales los que sostienen el producto de punta a punta: la entrada de cada actor (CU01, CU02, CU03), lo que el viajero viene a hacer (CU07, CU18), lo que la agencia paga por hacer (CU15, CU10), lo que ninguna persona dispara pero sin lo cual la compra no cierra (CU20, CU21) y la única mirada del administrador sobre el negocio (CU24). | Campo | Significado | |---|---| | Actor principal | Quien inicia el caso y recibe el valor. | | Actores secundarios | Sistemas externos que participan. | | Requerimiento | El requerimiento funcional que este caso realiza. | | Permiso | La clave de permiso que el sistema exige para autorizar la acción. | | Precondiciones | Lo que debe ser cierto antes de empezar. | | Postcondición | El estado en que queda el sistema si el caso termina bien. | | Flujo principal | La secuencia cuando todo sale como se espera. | | Flujos alternativos | Qué pasa cuando no. | --- ## CU01 · Registrarse como viajero | Campo | Valor | |---|---| | Actor principal | Visitante | | Actores secundarios | — | | Requerimiento | RF01 | | Permiso | Ninguno: el caso es público | | Precondiciones | El visitante no tiene sesión iniciada. | | Postcondición | Existe una cuenta activa con rol `viajero`, con la contraseña almacenada como hash, y el visitante queda autenticado con un token válido. | **Flujo principal** 1. El visitante abre el formulario de registro. 2. El sistema solicita la política de contraseñas vigente y arma con ella el indicador de fortaleza. 3. El visitante ingresa nombre, apellido, correo y contraseña. 4. El sistema valida en el cliente contra la misma política, en vivo, y mantiene el envío deshabilitado mientras algo no se cumpla. 5. El visitante envía el formulario. 6. El sistema normaliza el correo, vuelve a validar en el servidor y comprueba que el correo no esté registrado. 7. El sistema hashea la contraseña, crea la cuenta, le asigna el rol `viajero` y emite un token de acceso. 8. El sistema devuelve los datos públicos del usuario, sus permisos y el token, y redirige al catálogo. **Flujos alternativos** | Rama | Condición | Comportamiento | |---|---|---| | A1 | El correo ya está registrado | El sistema responde 422 con un mensaje que ofrece iniciar sesión o recuperar la contraseña. No revela ningún otro dato de la cuenta existente. | | A2 | La contraseña no cumple la política | El sistema responde 422 enumerando en castellano todos los requisitos incumplidos, no solo el primero. | | A3 | Algún campo obligatorio falta o tiene formato inválido | El sistema responde 422 con el detalle por campo, sin alcanzar la lógica de negocio. | | A4 | Se superó el límite de diez registros por hora desde la misma IP | El sistema responde 429 e indica cuándo puede reintentarse. | --- ## CU02 · Registrar agencia | Campo | Valor | |---|---| | Actor principal | Visitante | | Actores secundarios | Nominatim / OSM | | Requerimiento | RF04, RF28 | | Permiso | Ninguno: el caso es público | | Endpoint | `POST /api/auth/registro-agencia` | | Precondiciones | El visitante no tiene sesión iniciada, dispone de su legajo del registro de agentes de viajes y **ya eligió un plan en la vitrina** (CU15), que es de donde llega. | | Postcondición | Existe una cuenta con rol `agencia` en `travia_auth` y una agencia en `travia_app`. **La cuenta queda lista para usarse**: nadie tiene que habilitarla. El visitante queda autenticado con un token válido y el alta continúa, sin cambiar de pantalla, en el pago del plan que ya había elegido. | **Por dónde se entra, que no es un detalle** Una agencia **no llega a este formulario por su cuenta**: llega desde la vitrina de planes, después de haber visto el precio y los límites y de haber elegido uno. El alta es el segundo paso de un recorrido de tres —elegir el plan, crear la cuenta, pagar— y no un trámite que termina en un panel vacío donde alguien tiene que descubrir que además hay que suscribirse. El orden importa por una razón concreta: **quien abandona porque el precio no le cierra, abandona antes de cargar un CUIT, un legajo y una contraseña**. Poner el formulario primero solo consigue que ese abandono ocurra más tarde y con más trabajo tirado, del lado del visitante y del sistema. Del lado del servidor **el orden es el inverso y no puede no serlo**: la suscripción pertenece a una agencia y el cobro necesita a quién cobrarle, así que la cuenta se crea antes del pago. Lo que viaja entre pantalla y pantalla es el plan elegido, no una suscripción a medio hacer: no existe ningún registro intermedio que limpiar si el visitante se va en el medio. **Flujo principal** 1. El visitante elige un plan en la vitrina y el sistema abre el formulario de alta con ese plan a la vista y su importe, para que no se pierda de vista qué se está por contratar. 2. El sistema presenta el formulario en tres secciones —la agencia, quien la administra, y el acceso— y solicita la política de contraseñas vigente para armar el indicador de fortaleza. 3. El visitante ingresa nombre comercial, razón social, CUIT, legajo EVT, teléfono, sus datos personales y las credenciales. 4. El sistema revisa en el navegador lo único que puede comprobarse mirando el texto —los once dígitos del CUIT y los caracteres del teléfono— y mantiene el envío deshabilitado mientras falte un campo obligatorio. El legajo EVT no se revisa en el cliente: no tiene un formato garantizado. 5. El visitante envía el formulario. 6. El sistema normaliza el CUIT y el correo, valida en el servidor construyendo los objetos de valor del dominio, y comprueba que el correo, el CUIT y el legajo no estén ya registrados. 7. El sistema crea la cuenta en el esquema de identidad con el rol `agencia`. 8. El sistema crea la agencia en el esquema de negocio. 9. El sistema emite un token de acceso y responde 201 con el usuario, la agencia y el token. 10. El sistema lleva al visitante, ya autenticado, al paso de pago del plan que eligió al principio, con el importe y el plan ya cargados: no hay que volver a buscarlo. El recorrido sigue en CU15 desde su paso 3. 11. Desde ese momento, la agencia puede consultar sus datos con `GET /api/agencias/mia`, que no recibe identificador: la agencia se resuelve por el token. **Flujos alternativos** | Rama | Condición | Comportamiento | |---|---|---| | A1 | El CUIT no es válido, o el legajo EVT falta o no entra en la columna | El sistema responde 422 con el mensaje que redacta el propio objeto de valor, ubicado en el campo que falló. El CUIT se rechaza también cuando su dígito verificador no cierra, no solo cuando no tiene once dígitos. **Del legajo solo se exige que esté presente y que no supere los 20 caracteres**: no se valida su formato, y el motivo está más abajo. | | A2 | El legajo EVT o el CUIT ya pertenecen a otra agencia | El sistema responde 422 diciendo cuál de los dos está repetido. No revela ningún dato de la agencia existente ni quién la administra. | | A3 | El correo ya tiene una cuenta | El sistema responde 422 ofreciendo iniciar sesión o recuperar la contraseña, con el mismo texto que usa el alta de viajero. | | A4 | La agencia no se puede guardar después de haber creado la cuenta | El sistema **borra definitivamente la cuenta recién creada** y propaga el error. Ver la explicación más abajo. | | A5 | Se superó el límite de registros por hora desde la misma IP | El sistema responde 429 e indica cuándo puede reintentarse. Comparte el limitador con el alta de viajero. | | A6 | La geocodificación del domicilio falla | El alta se completa igual. El trabajo queda encolado para reintento y la agencia no aparece en las búsquedas por cercanía hasta que resuelva. | **Por qué A4 borra la cuenta en vez de reintentar** La cuenta va a `travia_auth` y la agencia a `travia_app`. Son dos bases con usuarios y privilegios distintos, así que **no hay una transacción que abarque a las dos**: cada escritura es atómica por separado y nada las une desde el motor. Si la segunda falla, la alternativa a compensar es dejar una cuenta con rol `agencia` y sin agencia detrás. Esa cuenta puede iniciar sesión, no puede hacer absolutamente nada, y además deja el correo bloqueado para siempre: quien lo intente de nuevo recibe "ese correo ya está registrado" sobre una cuenta fantasma que no puede ni recuperar. Por eso el caso de uso deshace lo que hizo, con un borrado definitivo y no lógico —una cuenta que nunca terminó de existir no tiene por qué quedar en la papelera—. **Por qué A1 no valida el formato del legajo** Exigir que el legajo tenga exactamente cinco dígitos, que es lo que miden actualmente los legajos del registro de agentes de viajes, sería la regla obvia. No se exige, y el motivo conviene tenerlo a mano porque es la pregunta obvia frente a un campo que dice "legajo" y no valida nada: - **El registro es secuencial y sigue creciendo.** El día que pase a seis dígitos, la validación rechaza agencias reales. El sistema fallaría justo cuando el negocio crece, y por una regla que nadie recordaría haber escrito. - **No protegería de nada.** Un número inventado de cinco dígitos pasaría igual, así que la regla no evitaría ni una sola alta fraudulenta. - **La comprobación que serviría es humana.** No hay API pública del registro; la única verificación posible es una persona mirándolo, y queda fuera del alcance. Validar el formato tampoco adelantaría nada de ese trabajo: solo daría la impresión de que sí. **El CUIT es el caso contrario y por eso A1 sí lo rechaza.** Su dígito verificador se calcula por módulo 11, así que el sistema puede descartar un número inventado **sin consultar a nadie**. El criterio que separa a los dos campos es si la validación puede decidir sola. Cuando no puede, lo honesto es decir qué queda sin comprobar: **el legajo se guarda, se exige único y nadie verifica que sea auténtico.** **La agencia queda operativa desde el alta.** Travia es un servicio por suscripción: una agencia se registra, contrata un plan y empieza a usarlo, sin que nadie la habilite a mano. Lo que decide si puede publicar es su plan vigente —CU15—, no una propiedad suya. **Lo que la agencia recibe y lo que no.** Recibe una sesión iniciada, sus datos consultables y el permiso `paquetes.publicar` en el token. No recibe ningún correo, porque no hay ninguna novedad que esperar: el alta se resuelve en el acto. --- ## CU03 · Iniciar sesión | Campo | Valor | |---|---| | Actor principal | Visitante | | Actores secundarios | — | | Requerimiento | RF02 | | Permiso | Ninguno: el caso es público | | Precondiciones | Existe una cuenta con el correo indicado. | | Postcondición | El usuario dispone de un token de acceso con los permisos derivados de sus roles, el contador de intentos fallidos queda en cero y el intento queda auditado. | **Flujo principal** 1. El visitante ingresa correo y contraseña. 2. El sistema normaliza el correo y busca la cuenta. 3. El sistema comprueba que la cuenta admita iniciar sesión: que su estado sea activo y que no tenga un bloqueo temporal vigente. 4. El sistema verifica la contraseña contra el hash almacenado. 5. El sistema reinicia el contador de intentos fallidos, registra la marca de último acceso y audita el intento como exitoso. 6. El sistema emite un token con los permisos del rol y devuelve los datos públicos del usuario. **Flujos alternativos** | Rama | Condición | Comportamiento | |---|---|---| | A1 | El correo no existe | El sistema consume igualmente el tiempo de verificación de contraseña, audita el intento con motivo interno propio y devuelve 401 con un mensaje **idéntico** al de contraseña incorrecta. | | A2 | La contraseña es incorrecta | El sistema suma un intento fallido, audita el intento y devuelve 401 con el mismo mensaje que A1. | | A3 | Este intento alcanza el quinto fallo consecutivo | El sistema bloquea la cuenta durante quince minutos además de responder 401. | | A4 | La cuenta tiene un bloqueo vigente | El sistema responde 423 indicando que la cuenta está bloqueada temporalmente y hasta cuándo. | | A5 | Se superó el límite de peticiones por cuenta o por IP | El sistema responde 429 antes de tocar la base de datos. | --- ## CU07 · Buscar y filtrar paquetes | Campo | Valor | |---|---| | Actor principal | Visitante o viajero; no hace falta sesión | | Actores secundarios | — | | Requerimiento | RF09, RF08 | | Permiso | **Ninguno.** `GET /api/paquetes` es pública, con límite de tasa por IP | | Precondiciones | Ninguna. Sin paquetes publicados la búsqueda responde vacía, no falla | | Postcondición | Nada cambia en el sistema: es una lectura. El navegador conserva la búsqueda en la dirección, y la última búsqueda enviada desde el buscador queda guardada para precargarlo | **Flujo principal** 1. El visitante completa el buscador de la portada: destino (obligatorio, elegido de la lista de países), origen (opcional), fecha de salida en `DD/MM/AAAA` (opcional), la casilla «Fechas cercanas (±3 días)» y la cantidad de viajeros, que arranca en dos. 2. La web valida antes de enviar —destino vacío, país que no está en la lista, fecha mal escrita o pasada— y, si todo está bien, guarda la búsqueda en el navegador y navega a `/paquetes` con los criterios en la dirección. 3. La pantalla de resultados lee los criterios **sólo** de la dirección, los normaliza y le pide a `GET /api/paquetes` la página, sin token. 4. El servidor valida la forma de cada parámetro, pide la hora una sola vez y rechaza una fecha de salida anterior a hoy. 5. El servidor aplica la vitrina —lo que puede verse siempre— y después los criterios, cuenta el total, ordena y trae la página. 6. La web muestra las tarjetas con el precio por persona, el total para los viajeros pedidos, la duración y el estado —«Quedan 3 lugares», «Agotado»—, y anuncia el resultado en una región `role="status"`. 7. El visitante cambia el orden o la página; cada cambio queda en la dirección, así que el botón «atrás» del navegador vuelve al estado anterior. 8. El visitante acota los resultados con los filtros. En escritorio (1024 px o más) una barra lateral los aplica al instante: el precio al salir del campo o con Enter —no por tecla, para no pedir una búsqueda por dígito—, la duración y la agencia al elegirlas. Cada filtro aplicado es una entrada del historial y un chip removible sobre la grilla. 9. Por debajo de 1024 px los filtros viven en una hoja inferior que trabaja sobre un **borrador**: nada cambia hasta apretar el botón del pie, que dice de antemano cuántos paquetes va a mostrar —la misma búsqueda pedida con un paquete por página, leyendo sólo el total—. 10. Las opciones de los filtros salen de las `facetas` de la respuesta: el rango real de precios, las duraciones y las agencias presentes, calculadas sin los filtros para que los controles no se achiquen al usarlos. **Flujos alternativos** | Rama | Condición | Comportamiento | |---|---|---| | A1 | No hay paquetes para los criterios | La web explica por qué y ofrece **una** salida concreta según lo pedido: con fecha exacta, «Buscar ±3 días»; si ya era flexible, «Buscar sin fecha»; sin fecha, «Ver todos los destinos». Siempre ofrece además «Modificar búsqueda» | | A2 | La fecha de salida del enlace ya pasó | El servidor responde **422** con `campo: "fecha_salida"`. La web marca el campo de la fecha y ofrece «Buscar desde hoy», que quita la fecha y la flexibilidad | | A3 | Otro parámetro no vale (código de país mal formado, orden desconocido, tamaño de página fuera de rango) | **422** con el campo en `errors`. La web muestra el mensaje del servidor y ofrece empezar una búsqueda nueva | | A4 | Se pide una página posterior a la última | El servidor responde **200 vacío con el total real**; la web reemplaza la dirección por la última página que existe | | A5 | Falla la red o el servidor responde 5xx | La web lo dice —«Puede ser la conexión. Tu búsqueda sigue acá.»— y deja reintentar sin perder los criterios | | A6 | La dirección trae parámetros viejos o inválidos | La web los normaliza —orden desconocido a «próxima salida», página inválida a 1, «flexible» sin fecha descartado, los parámetros del buscador anterior ignorados— y reemplaza la dirección **con un solo pedido** a la API | | A7 | No hay paquetes **por los filtros** (sin ellos, la búsqueda sí tendría) | La web dice que los filtros son la causa. Con un filtro, ofrece «Quitar este filtro»; con varios, «Limpiar filtros», que se puede deshacer durante diez segundos desde el aviso flotante. Si la búsqueda tampoco tiene nada sin filtros, es el vacío de A1 | | A8 | El mínimo de precio supera al máximo mientras se escribe | El par se marca en el campo y **no se aplica** hasta que vuelve a valer; en la hoja, el botón no aplica y lleva al campo con error. Un rango invertido que llega en un enlace se da vuelta en silencio | | A9 | El servidor rechaza un filtro con **422** (formato o valor) | La web marca el control del filtro que dice `campo` —que todo 422 trae, lo rechace el Form Request o el dominio—, muestra el mensaje del servidor y ofrece «Quitar este filtro» | | A10 | En la hoja, el borrador daría cero paquetes | El pie lo dice antes de aplicar, **sin bloquear**: el botón aplica igual. Si el conteo falla, el botón dice «Ver resultados» sin mostrar un error | **El circuito completo** ```mermaid sequenceDiagram autonumber participant W as Web · Resultados participant C as ControladorCatalogo
y PeticionBuscarEnElCatalogo participant U as BuscarEnElCatalogo
(caso de uso) participant P as CatalogoDePaquetes
(puerto) participant A as CatalogoDePaquetesEloquent participant DB as MySQL · travia_app W->>C: GET /api/paquetes?pais_destino=BR&fecha_salida=...
sin token · throttle:api por IP alt Forma inválida: tipo, formato, código de país C-->>W: 422 · mensaje + campo + errors else Forma válida C->>U: Comando(criterios, orden, paginación) U->>U: ahora = Reloj::ahora(), una sola vez alt Fecha pedida anterior a hoy U-->>W: 422 · mensaje + campo + errors else Fecha válida U->>P: buscar(criterios, orden, paginación, ahora) P->>A: lo implementa A->>DB: COUNT con vitrina + criterios opt El desplazamiento no pasa el total A->>DB: SELECT con JOIN a agencias vivas
ORDER BY criterio, id · LIMIT 12 OFFSET n end A-->>U: Página de PaqueteEnVitrina + total U->>U: situación y duración de cada ficha
con el mismo ahora U->>P: facetas(criterios.sinFiltros(), ahora) P->>A: lo implementa A->>DB: MIN / MAX / COUNT sobre la vitrina + búsqueda
y GROUP BY agencia A-->>U: FacetasDelCatalogo U-->>C: Resultado C-->>W: 200 · paquetes + paginacion + orden + filtros + facetas end end ``` Hay dos consultas —una cuenta y otra trae la página— y **salen del mismo armado de condiciones**, así que no pueden filtrar cosas distintas. No van en una transacción: un paquete publicado entre el `COUNT` y el `SELECT` puede correr el total en uno, y eso sólo cambia un número del encabezado; la página que se muestra es igual de válida. Es una inexactitud aceptada a cambio de no abrir una transacción en el endpoint que cualquiera puede llamar sin cuenta. **Por qué el caso de uso pide la hora una sola vez.** La misma hora decide qué fecha pedida ya pasó, qué paquetes están en la vitrina y qué cartel lleva cada uno. Si cada paso preguntara la suya, una búsqueda a la medianoche podría contradecirse. Y el momento llega al SQL como parámetro, nunca como `NOW()` o `CURDATE()`: el reloj del dominio es uno solo. **Por qué es un puerto aparte de `RepositorioPaquetes`.** Aquel es el de la agencia: escribe, lee por id sin filtrar y lista lo propio, incluidos los despublicados y los cerrados. Éste es de sólo lectura, cruza con `agencias` para el nombre y la baja, pagina y ordena, y lo usa alguien sin sesión. Mezclarlos daría una interfaz que sirve a dos pantallas con reglas opuestas sobre qué se muestra, y un adaptador donde un filtro del panel podría colarse en la vitrina. ### Qué entra en la vitrina Antes de mirar ningún criterio, y siempre, un paquete aparece sólo si cumple cuatro condiciones. Tres son la traducción de `Paquete::seMuestraEnLaVitrinaAl()` y la cuarta es lo único que la entidad no sabe: su agencia. ```mermaid flowchart TD P["Paquete en la tabla"] --> E{"estado = activo"} E -->|no| X1["No se ve:
despublicado por la agencia"] E -->|sí| D{"paquetes.deleted_at IS NULL"} D -->|no| X2["No existe:
dado de baja"] D -->|sí| F{"fecha_salida >= hoy"} F -->|no| X3["Cerrado:
el viaje ya salió"] F -->|sí| AG{"agencias.deleted_at IS NULL"} AG -->|no| X4["No se ve:
agencia dada de baja"] AG -->|sí| V["En la vitrina,
disponible o agotado"] V --> CR["Recién ahí, los criterios:
país, fecha, viajeros,
precio, noches y agencia, combinados con Y"] ``` Es, a propósito, **el mismo conjunto que ocupa lugar del plan**: lo que la agencia paga por tener publicado es exactamente lo que el viajero ve. El cupo **no** está en la lista: un agotado se muestra con su cartel, porque ocultarlo le escondería al viajero que ese viaje existe y puede liberar lugar. Sólo cuando se piden viajeros quedan afuera los que no tienen lugar para todos. **La definición vive en el dominio y el SQL la copia.** Cada condición del adaptador es la traducción literal de la regla de la entidad y de `CriteriosDeBusqueda::admite()`, y el orden SQL tiene que coincidir con `OrdenDelCatalogo::comparar()`. Si una de las definiciones cambia, la consulta tiene que cambiar con ella. La alternativa —filtrar en PHP después de traer, con una sola definición— se descartó porque obligaría a leer el catálogo entero en cada búsqueda y rompería el total. ### Decisiones de negocio de la búsqueda | Decisión | Por qué | Qué se descartó, y a cambio de qué | |---|---|---| | **Una fecha de salida pasada se rechaza con 422** | Ignorarla devolvería viajes de cualquier fecha como si fueran la respuesta a la pregunta que se hizo. Se compara la **fecha indicada** y no la ventana: «hoy, flexible» vale aunque la ventana arranque tres días atrás, y «ayer, flexible» no, aunque llegue a pasado mañana. La regla tiene que poder explicarse en una frase: la fecha que elegiste ya pasó | Se descartó ignorarla o corregirla en silencio a hoy. A cambio, un enlace viejo compartido da un 422, y por eso la web lo convierte en «Buscar desde hoy» (rama A2) | | **Los paquetes de una agencia dada de baja se excluyen** | Ahí no hay nada que deducir: la agencia dejó de existir para el negocio y nadie puede atender lo que se le compre. Es un `JOIN` con `agencias.deleted_at IS NULL`, interno porque un paquete sin agencia no debería existir (hay foránea) y, si existiera, no habría a quién comprarle | Se descartó dejarlos visibles hasta que alguien los despublique uno por uno | | **Una suscripción vencida no oculta los paquetes ya publicados** | Dos motivos. Uno: la situación de una suscripción se deduce con el reloj en `Suscripcion::situacionAl()` y no está en ninguna columna; filtrarla en SQL sería escribir esa regla por segunda vez, lo mismo que el padrón de agencias se niega a hacer. Dos: ocultar de golpe los viajes de una agencia que se atrasó un día con el pago castiga a los viajeros que ya los estaban mirando, y la sanción por impago —si la hay— tiene que decidirse con nombre propio, no aparecer como efecto lateral de un buscador | Se descartó filtrar por suscripción. A cambio, una agencia con el mes vencido **no puede publicar ni reactivar**, pero lo que ya tenía sigue a la venta, coherente con `contarActivosDeAgencia()`, que tampoco mira la suscripción | | **El orden por precio compara importes sin convertir monedas** | Hoy todo el catálogo está en pesos: la tabla `paquetes` no tiene columna `moneda`, y `Dinero::esMenorQue()` lanzaría ante dos monedas distintas | **Limitación conocida.** El día que haya paquetes en más de una moneda, ordenar por precio necesita una conversión, y `OrdenDelCatalogo` es el lugar donde va. Mientras tanto, ordenar en SQL por la columna `precio` es correcto sólo porque la moneda es una sola | | **Los destinos destacados de la portada filtran por país** | La búsqueda filtra por país de destino. «Bariloche» lleva a `/paquetes?pais_destino=AR`: es menos preciso que la foto, pero no promete un filtro que la API no hace | **El filtro por ciudad queda fuera de esta búsqueda**: es el mapa, con la geolocalización, el que lo necesita. Estos destacados son atajos fijos de la portada, no los paquetes destacados por plan de CU06 | | **Todo orden desempata por `id`** | Dos paquetes con el mismo precio o la misma salida son lo más común del catálogo; sin desempate fijo la base puede devolverlos en cualquier orden, y el mismo paquete aparecería en la página 1 y en la 2 y otro en ninguna | El `id` no significa nada para el viajero: está para que paginar sea estable | | **El orden por defecto es la próxima salida** | Es lo más urgente del catálogo —lo que antes deja de poder comprarse— y no premia a ninguna agencia por bajar el precio ni por subirlo | Se descartó «por relevancia», que especificaba CU06, porque todavía no hay ningún dato de relevancia con qué ordenar | | **El país se valida por formato, no contra el catálogo de países** | Buscar viajes a un país que Travia no tiene cargado no es un error del viajero: la respuesta correcta es «no hay viajes ahí», una página vacía | Se descartó una consulta extra por búsqueda sólo para cambiar un resultado vacío por un 422 que dice lo mismo peor | ### Decisiones de los filtros | Decisión | Por qué | Qué se descartó, y a cambio de qué | |---|---|---| | **Las facetas se calculan sin los filtros** | Describen la búsqueda, no el resultado filtrado: si siguieran a los filtros, el rango de precio se encogería a lo ya elegido y el desplegable de agencias quedaría con una sola opción | Se descartó calcularlas sobre lo filtrado, que ahorraba una consulta | | **Bordes inclusivos en precio y noches** | «Hasta $400.000» incluye el de $400.000; «4 a 6 noches» incluye el de 4 y el de 6. Es como lo lee cualquiera | Se descartaron los bordes exclusivos, que obligarían al viajero a adivinar si «hasta» incluye el valor que escribió | | **Noches, no días** | La tarjeta dice «5 días / 4 noches», y lo que el viajero compara entre paquetes es cuántas noches paga. Cero noches es la excursión de ida y vuelta en el día, y es un valor válido | Se descartó filtrar por `cantidad_dias`, que además no es columna | | **La agencia no se valida contra el padrón** | Un enlace viejo a una agencia dada de baja no es un error del viajero: la respuesta correcta es una página vacía | Se descartó una consulta extra por búsqueda para convertir un vacío en un 422 | | **Escritorio aplica al instante; el teléfono, con un borrador** | Al lado de la barra lateral están los resultados y el botón Atrás deshace cada paso; en la hoja los resultados están tapados, así que aplicar por cada toque sería cambiar algo que no se ve | Se descartó un solo comportamiento para los dos tamaños. El contenido de los controles es el mismo componente, `PanelDeFiltros`, en dos modos | | **Los filtros viven en la dirección y no en la última búsqueda guardada** | Un enlace compartido o recargado reconstruye los filtros; pero la portada que precarga la última búsqueda no los arrastra, porque filtrar afina una búsqueda y no es parte de ella | Se descartó guardarlos, a cambio de que quien vuelve empiece con los resultados completos. La última búsqueda guarda sólo destino, origen, fecha, flexibilidad y viajeros | --- ## CU10 · Publicar paquete turístico | Campo | Valor | |---|---| | Actor principal | Agencia | | Actores secundarios | — | | Requerimiento | RF06 | | Permiso | `paquetes.publicar` | | Precondiciones | La agencia tiene sesión iniciada. | | Postcondición | Existe un paquete activo. Si el negocio lo permite, además está publicado y visible en el catálogo público (ver CU07); si no, la agencia recibe la salida concreta para poder publicarlo. | **Flujo principal** 1. La agencia abre el alta de paquete, `/agencia/paquetes/publicar`. 2. La agencia carga nombre, país y ciudad de destino, país de origen, fechas de salida y regreso, cupos, precio, descripción e imagen principal (URL). El sistema muestra la duración en días **calculada de las fechas**, no como un campo que se carga. 3. La agencia confirma la publicación. 4. El sistema resuelve la última suscripción de la agencia y su situación contra el reloj. Si no habilita a publicar, corta acá (rama A2). 5. El sistema cuenta los paquetes que hoy ocupan un lugar del plan de la agencia y le pregunta a la política de publicación si entra uno más. Si no entra, corta acá (rama A1). 6. El sistema valida los países contra el catálogo vigente, y valida las fechas, los cupos, el precio y el largo de la imagen contra las reglas del dominio. 7. El sistema persiste el paquete, activo y publicado. 8. El sistema confirma la publicación con el consumo actualizado del plan —cuántos paquetes activos tiene la agencia ahora y cuántos lugares le quedan— y ofrece ver el paquete. **Flujos alternativos** | Rama | Condición | Comportamiento | |---|---|---| | A1 | La agencia alcanzó el límite de paquetes activos de su plan | El sistema responde **409** con el tope del plan, cuántos tiene hoy, y el plan más barato de la oferta vigente que sí le alcanzaría —a igual precio, el que más permite—, o la señal de que ya está en el tope de la oferta si no hay a dónde subir. El formulario conserva todo lo cargado. | | A2 | La agencia no tiene suscripción vigente, o está vencida | El sistema responde **402**, dice la situación —nunca contrató, o desde cuándo está vencida— y ofrece la salida concreta: ir a la vitrina de planes o renovar. No es un 403: el permiso `paquetes.publicar` está en el token, lo que falta es el contrato vigente. | | A3 | La fecha de regreso es anterior o igual a la de salida, el precio o los cupos no son positivos, o la fecha de salida ya pasó | El sistema responde **422** con el campo señalado. La fecha vencida se compara contra el comienzo del día del reloj del dominio, no contra la constante `today` de Laravel: un viaje que sale hoy se puede publicar hoy. | | A4 | Un país de origen o destino no existe en el catálogo vigente, o la imagen supera los 500 caracteres | El sistema responde **422** con el campo señalado. | **Lo que queda fuera de este flujo.** La banda de precios de mercado (RF17, CU12) y la geocodificación del destino (RF23, CU11) no forman parte de este flujo: son otros casos de uso, con sus propios requerimientos, que se disparan sobre un paquete ya publicado. **En móvil** El diseño previsto es que el caso de uso sea el mismo y use los mismos endpoints, con la forma de cargarlo recortada: los campos indispensables, las imágenes tomadas con la cámara del dispositivo en lugar de subirse desde el disco. Es la misma decisión que gobierna toda la aplicación móvil: **se recorta el formulario, nunca la capacidad**. --- ## CU15 · Contratar o renovar suscripción | Campo | Valor | |---|---| | Actor principal | Agencia | | Actores secundarios | Pasarela de cobro | | Requerimiento | RF05 | | Permiso | `suscripcion.contratar` | | Precondiciones | La cuenta tiene sesión iniciada y administra una agencia. No hay una suscripción propia vigente: si la hay, lo que corresponde es esperar a que termine el período pagado. | | Entradas | **Dos, y la vitrina es común a las dos.** Desde el alta: el visitante elige el plan sin sesión, crea su cuenta (CU02) y vuelve acá con el plan ya elegido. Desde el panel: una agencia que ya opera renueva o cambia de plan. La diferencia está en si hay sesión al elegir, no en el caso de uso. | | Postcondición | Existe una suscripción con el plan elegido, el **precio congelado** del día de la contratación, el período de un mes y el estado `activa`. El cobro se ejecutó **una sola vez** y su referencia quedó guardada. La agencia queda habilitada para publicar. | **Flujo principal** 1. La agencia abre la vitrina de planes, que es **pública y no exige sesión**, y muestra los planes activos de menor a mayor precio con su precio y sus límites. Es la puerta de entrada de cualquier agencia, tenga cuenta o no. 2. El sistema adapta las tarjetas a quien está mirando. **Sin sesión**, el botón dice «Empezar con este plan» y lleva al alta de agencia (CU02) arrastrando el plan elegido; el recorrido vuelve a este caso en el paso 3 con la sesión ya iniciada. **Con sesión**, consulta la suscripción propia: si ya tiene una vigente marca cuál y desactiva el resto, y si venció el botón dice «Renovar» en lugar de «Contratar». 3. La agencia elige un plan. El sistema abre la confirmación **con el importe a la vista** y genera en ese momento una clave de idempotencia, que va a repetirse en todos los envíos de ese formulario. 4. La agencia confirma. 5. El sistema comprueba si esa clave ya contrató. Si ya lo hizo, devuelve la misma suscripción con 200 y **no vuelve a cobrar**. 6. El sistema comprueba que el plan exista y se siga ofreciendo: la vitrina abierta puede ser de hace media hora y la administración pudo retirarlo (CU26). 7. El sistema comprueba que la última suscripción de la agencia no esté vigente. 8. El sistema le pide a la pasarela que cobre el precio **que dice el plan**, nunca uno que haya viajado en la petición. 9. Con el cobro aprobado, el sistema crea la suscripción congelando el precio, fijando el período de las 00:00:00 del día de hoy a las 23:59:59 del día del vencimiento, y guardando la referencia del cobro. 10. El sistema responde 201 y la pantalla confirma con el plan y la fecha hasta la que quedó paga. **Flujos alternativos** | Rama | Condición | Comportamiento | |---|---|---| | A1 | Llega la misma clave de idempotencia de una contratación ya hecha | El sistema devuelve **200** con la misma suscripción y el mensaje «esta suscripción ya estaba contratada, así que no volvimos a cobrarla». No se toca la pasarela. Es el camino del doble clic y del reintento del navegador. | | A2 | El plan no existe o fue retirado de la oferta | El sistema responde **422** y ofrece la salida: volver a la lista y elegir uno vigente. No es 404 porque el plan es un campo del formulario, no el recurso que la URL direcciona. | | A3 | La agencia ya tiene una suscripción vigente | El sistema responde **409** diciendo **hasta cuándo** está paga, que es el dato con el que se sabe cuándo sí puede renovar. La pantalla vuelve a consultar la suscripción para dejar de ofrecer lo que el servidor rechazó. | | A4 | La pasarela rechaza el cobro | El sistema responde **402** con el motivo y la salida —reintentar con otro medio—. **No queda nada escrito**: no hay suscripción pendiente que limpiar después. El formulario conserva su clave, así que reintentar sigue siendo seguro. | | A5 | La cuenta no administra ninguna agencia | El sistema responde **403** explicando que la suscripción es de una agencia y para dónde ir. No es 404: lo que falta no es el recurso sino la condición para pedirlo. | | A6 | Se superaron los 5 intentos por minuto o los 20 por hora | El sistema responde **429**. Es el límite más estricto del sistema porque es el único circuito que mueve dinero: cada llamada que pasa termina en la pasarela. | **El orden de los pasos 5 a 9 es la regla, no una preferencia.** Se comprueba la idempotencia antes que nada —si no, un doble clic cobra dos veces—, se valida el plan y la vigencia antes de cobrar —si no, se le saca plata a alguien para después rechazarle la contratación— y se guarda después de cobrar —si no, quedan suscripciones activas sin pago detrás—. Cada inversión de ese orden tiene un damnificado concreto. **Qué queda fuera de este caso de uso.** Al bajar a un plan con menos cupo, el sistema **no** pide elegir qué paquetes conservar activos, y es una decisión explícita: la política de publicación se consulta sólo al escribir, no sobre el pasado. Si una agencia baja de plan con más paquetes activos de los que su nuevo tope permite, ninguno se despublica solo —despublicar la oferta de alguien sin que lo pida sería el peor de los tres resultados posibles— y la agencia simplemente no puede publicar uno más hasta que el exceso se drene solo, despublicando o cuando los viajes salgan. Tampoco hay cambio de plan a mitad de período ni baja: la entidad sabe cancelarse conservando el mes pagado, pero ningún caso de uso la invoca. Y **la renovación no es automática**: renovar es volver a recorrer este mismo caso, con un formulario nuevo y una clave nueva. **El cobro entra por un puerto.** El caso de uso le habla a `PasarelaDeCobro` y no sabe qué hay del otro lado. Cambiar de proveedor de cobro no cambia este caso de uso: cambia una línea del proveedor de puertos, y la rama A4 es la misma para cualquier pasarela que rechace. --- ## CU18 · Comprar paquete | Campo | Valor | |---|---| | Actor principal | Viajero | | Actores secundarios | Mercado Pago | | Requerimiento | RF11 | | Permiso | `ordenes.crear` | | Precondiciones | El viajero tiene sesión iniciada y el paquete está publicado con cupos disponibles. | | Postcondición | Existe una orden en estado pendiente de pago, con los cupos descontados y una reserva con vencimiento, y el viajero tiene la URL de checkout. | **Flujo principal** 1. El viajero selecciona el paquete y la cantidad de pasajeros. 2. El sistema muestra el resumen persistente: paquete, fechas, pasajeros e importe total. 3. El viajero carga los datos de los pasajeros y confirma. 4. El sistema abre una transacción de base de datos. 5. El sistema bloquea la fila del paquete y relee el cupo disponible dentro de la transacción. 6. El sistema descuenta los cupos, crea la orden en estado pendiente con su vencimiento de reserva y confirma la transacción. 7. El sistema crea la preferencia de pago en la pasarela y obtiene la URL de checkout. 8. El sistema devuelve la orden y redirige al viajero al checkout, incluido en CU19. **Flujos alternativos** | Rama | Condición | Comportamiento | |---|---|---| | A1 | Otro viajero tomó el último cupo mientras este completaba los datos | La relectura dentro de la transacción detecta la falta de cupo. El sistema revierte, responde 409 y ofrece salidas cercanas del mismo destino. | | A2 | La pasarela no responde al crear la preferencia | La orden queda pendiente con su reserva vigente y el sistema ofrece reintentar el pago desde el historial de compras. | | A3 | El viajero abandona sin pagar | La reserva vence y CU21 devuelve los cupos al paquete. | | A4 | El paquete fue despublicado entre la selección y la confirmación | El sistema responde 409 informando que el paquete ya no está disponible. | --- ## CU20 · Procesar notificación de pago | Campo | Valor | |---|---| | Actor principal | Mercado Pago | | Actores secundarios | Firebase Cloud Messaging, a través de CU29, para avisar al viajero y a la agencia (paso 6) | | Requerimiento | RF12 | | Permiso | Ninguno: se autentica por firma del mensaje, no por sesión | | Precondiciones | Existe una orden pendiente asociada al identificador de pago informado. | | Postcondición | La orden queda confirmada con su asiento contable, o cancelada con los cupos devueltos. El evento queda marcado como procesado. | **Flujo principal** 1. La pasarela envía la notificación al borde público, que la enruta a la API como a cualquier otro cliente. 2. El sistema valida la firma del mensaje. 3. El sistema comprueba si ese identificador de evento ya fue procesado. 4. El sistema consulta el estado real del pago contra la API de la pasarela, en lugar de confiar en el contenido del mensaje. 5. Si el pago está aprobado, el sistema confirma la orden, asienta el crédito neto de la agencia y la retención de comisión, y marca el evento como procesado. 6. El sistema notifica al viajero y a la agencia. **Flujos alternativos** | Rama | Condición | Comportamiento | |---|---|---| | A1 | La firma no valida | El sistema descarta el mensaje, responde 401 y registra el intento. | | A2 | El evento ya fue procesado | El sistema responde 200 sin volver a aplicar ningún efecto. La repetición es esperada: la pasarela reintenta. | | A3 | El pago fue rechazado | El sistema cancela la orden, devuelve los cupos al paquete y avisa al viajero indicando el motivo y ofreciendo otro medio de pago. | | A4 | La orden ya venció y sus cupos fueron liberados, pero el pago llegó aprobado | El sistema intenta reservar nuevamente. Si hay cupo, confirma. Si no, inicia la devolución y avisa al viajero. | --- ## CU21 · Liberar reservas vencidas | Campo | Valor | |---|---| | Actor principal | Planificador | | Actores secundarios | Firebase Cloud Messaging, a través de CU29, para avisar al viajero (paso 4) | | Requerimiento | RF11 | | Permiso | Ninguno: proceso interno sin exposición pública | | Precondiciones | Existen órdenes pendientes cuyo vencimiento de reserva ya pasó. | | Postcondición | Cada orden vencida queda cancelada y sus cupos vuelven a estar disponibles. | **Flujo principal** 1. El planificador dispara el proceso según su intervalo configurado. 2. El sistema selecciona las órdenes pendientes con vencimiento cumplido. 3. Para cada una, dentro de una transacción, cancela la orden y devuelve los cupos al paquete. 4. El sistema notifica al viajero que la reserva expiró y le ofrece volver a intentarlo. **Flujos alternativos** | Rama | Condición | Comportamiento | |---|---|---| | A1 | El pago se confirma mientras el proceso está corriendo | El bloqueo de fila serializa ambas operaciones. La que llega segunda encuentra la orden en un estado que ya no admite su transición y no hace nada. | --- ## CU24 · Supervisar el estado comercial de las agencias | Campo | Valor | |---|---| | Actor principal | Administrador | | Actores secundarios | — | | Requerimiento | RF19 | | Permiso | `admin.agencias.gestionar` | | Endpoint | `GET /api/administracion/agencias?busqueda=…` | | Pantalla | `/administracion/agencias` en la web | | Precondiciones | El administrador tiene sesión iniciada y su token trae el permiso. | | Postcondición | Ninguna: el caso **no modifica nada**. Termina con el administrador sabiendo qué agencias operan al día, a cuáles se les vence el plan esta semana y cuáles dejaron de pagar. | **Flujo principal** 1. El administrador abre la pantalla de agencias del panel de Travia. 2. El sistema exige `admin.agencias.gestionar` antes de ejecutar nada; sin ese permiso no se llega al caso de uso. 3. El sistema lista las agencias registradas con su nombre comercial, su legajo, el plan que contrataron y la fecha hasta la que está pago. 4. Para cada una, el sistema **deriva la situación en el momento de la consulta**: se la pregunta a su última suscripción, que compara el período pago contra el reloj y responde `vigente`, `por_vencer`, `suspendida_por_impago` o `cancelada`. 5. El administrador busca por texto —nombre comercial, razón social, CUIT con guiones o sin ellos, legajo EVT— para llegar a una agencia concreta. El recuento debajo del buscador dice siempre cuántas coinciden **sobre cuántas hay**, para que el recorte se lea como recorte. 6. El administrador abre el detalle de una agencia y ve su identidad fiscal, sus datos de contacto, la fecha de alta y el período que tiene pago, con el precio que quedó congelado al contratar. 7. El caso termina ahí. **No hay ninguna acción que ejecutar**: la pantalla no ofrece aprobar, suspender ni reactivar. **Flujos alternativos** | Rama | Condición | Comportamiento | |---|---|---| | A1 | La agencia se registró y nunca contrató un plan | Se informa **sin suscripción**, que no es lo mismo que suspendida: nunca dejó de pagar, todavía no empezó. Es el grupo donde una llamada comercial vale más, así que se muestra aparte y no mezclado con los impagos. | | A2 | La suscripción está cancelada y todavía le quedan días pagos | Se informa **cancelada**, no suspendida por impago. La cancelación le gana al calendario: decir que alguien no pagó cuando lo que hizo fue irse sería acusarlo de algo que no hizo. | | A3 | La suscripción vence dentro de los días de aviso | Se informa **por vencer**, y la agencia **sigue publicando con normalidad**. El mes está pagado: el aviso es información para quien administra, no una restricción para quien pagó. | | A4 | El período pago terminó y no hubo renovación | Se informa **suspendida por impago** sin que nadie haya hecho nada, y vuelve a estar vigente en el mismo instante en que la agencia contrata de nuevo. No hay proceso nocturno que marque filas ni acción de reactivación que alguien pueda olvidarse de hacer. | | A5 | El administrador quiere sancionar a una agencia que está al día | La pantalla no lo permite, y es deliberado: la sanción por incumplimiento de políticas está fuera de alcance. Ver más abajo. | | A6 | El token no trae el permiso | El sistema responde **403**. No es 404: el recurso existe y lo que falta es la autorización; esconderlo no agregaría nada, porque el control ya se hizo. | **Por qué este caso de uso no tiene ni una acción, que es lo primero que llama la atención.** RF19 nació pidiendo *"aprobar, suspender y administrar agencias"*, y las dos primeras palabras dejaron de describir al sistema el día que Travia se definió como servicio por suscripción. **La aprobación no existe**: una agencia se registra, contrata un plan y opera; nadie la habilita. **Y la suspensión no es una decisión sino una consecuencia**: se produce cuando un período pago termina sin renovarse, y se deshace cuando se paga. Sumar botones que hicieran a mano lo que la regla ya hace sola sería una segunda puerta que hace lo mismo peor: no cobra, no vence sola y necesita una persona disponible. Por eso lo que queda es leer, y leer alcanza: **es la primera pantalla que muestra el estado del negocio**. **El estado no se guarda, se calcula, y ahí está la mitad del diseño.** Vive en `SituacionDeSuscripcion` —`vigente`, `por_vencer`, `suspendida_por_impago`, `cancelada`— y lo computa `Suscripcion::situacionAl($ahora)`. La columna `estado` de la tabla guarda solamente `activa` o `cancelada`: **«vencida» no es un valor persistido**. Una columna que guardara lo mismo sería un dato que puede quedar desactualizado respecto de la fecha real de vencimiento —el error clásico de este modelo— y obligaría a un proceso programado del que la pantalla pasaría a depender. Acá no hay nada que pueda no haber corrido. Los días de aviso que separan `vigente` de `por_vencer` **llegan por parámetro y no como constante**: cuántos días antes se avisa es una decisión comercial, del mismo tipo que el precio de un plan, y el día que se quiera avisar con quince no hay que tocar ninguna regla de dominio. **Lo que queda explícitamente fuera, y conviene decirlo antes de que lo pregunten.** La sanción administrativa por incumplimiento de políticas —dar de baja a una agencia que estafa, aunque esté al día con el pago— **no está en alcance**. Es una capacidad razonable en cualquier *marketplace*. Si aparece, es otra columna y otro permiso, y conviene que se llame distinto: mezclarla con la suspensión por impago haría que una pantalla que no juzga a nadie pasara a confundir una consecuencia automática con un castigo, y que nadie pudiera saber, mirando una fila, cuál de las dos cosas ocurrió. --- ## Casos de uso restantes Los veinte casos siguientes usan la forma compacta. La información es la misma: actor, requerimiento realizado, permiso exigido, precondición, postcondición, flujo principal y las excepciones que importan. CU07 y CU15 aparecen también acá solo como remisión a su desarrollo completo, para que cada subsistema se lea entero en un lugar. ### Identidad | Caso | Actor | RF | Permiso | Resumen | |---|---|---|---|---| | CU04 · Cerrar sesión | Usuario autenticado | RF02 | Sesión válida | El usuario solicita cerrar sesión y el sistema revoca el token utilizado, no todos los del usuario. Un token revocado deja de dar acceso de inmediato. Si el token ya era inválido, la respuesta es la misma: cerrar sesión es idempotente. | | CU05 · Gestionar perfil | Viajero, Agencia | RF03 | `agencia.perfil.editar` para los datos comerciales | El usuario modifica sus datos personales o de contacto. Para cambiar la contraseña debe ingresar la actual y la nueva, que se valida contra la misma política que en el alta. Si la contraseña actual es incorrecta, el cambio se rechaza y el intento queda auditado. | ### Catálogo y búsqueda | Caso | Actor | RF | Permiso | Resumen | |---|---|---|---|---| | CU06 · Explorar catálogo | Visitante | RF08 | `paquetes.ver` | El sistema devuelve la primera página del catálogo de paquetes activos, ordenada por relevancia, con veinticuatro elementos por página y los destacados del plan de cada agencia en la posición que corresponde. Si no hay paquetes, muestra un estado vacío que propone destinos alternativos en lugar de una lista en blanco. | | CU07 · Buscar y filtrar paquetes | Visitante | RF09 | Ninguno | **Desarrollado arriba en forma completa.** | | CU08 · Consultar detalle del paquete | Visitante | RF10, RF24 | `paquetes.ver` | El sistema muestra itinerario, descripción, imágenes, precio, condiciones, datos y reputación de la agencia, y ubica el destino y los puntos del itinerario en un mapa interactivo. Si el paquete aún no tiene coordenadas, el mapa se omite y el resto del detalle se muestra igual. | | CU09 · Buscar por cercanía | Viajero | RF25 | `paquetes.ver` | Con permiso de ubicación concedido, el sistema ordena agencias y salidas por distancia real calculada sobre la esfera y prellena el campo de origen. Si el usuario deniega el permiso, la búsqueda funciona igual con el origen ingresado a mano: la cercanía es una mejora, nunca un requisito. | ### Agencia | Caso | Actor | RF | Permiso | Resumen | |---|---|---|---|---| | CU11 · Geocodificar destino | Nominatim / OSM | RF23 | Proceso interno | Un trabajo en segundo plano toma la dirección o el destino y obtiene sus coordenadas, que quedan almacenadas junto al paquete o la agencia. Corre fuera del ciclo de petición para que la indisponibilidad del servicio externo nunca haga fallar un alta. Ante error, reintenta con espera creciente. | | CU12 · Consultar sugerencia de precio | Agencia | RF17 | `agencia.mercado.ver` | El sistema calcula los percentiles 25, 50 y 75 de los precios de los paquetes activos comparables por destino, duración y temporada, y ubica el precio de la agencia dentro de esa banda. Si no hay suficientes paquetes comparables, lo dice explícitamente en vez de mostrar una banda sin sustento. | | CU13 · Modificar paquete | Agencia | RF07 | `paquetes.editar` | La agencia lista sus paquetes (`GET /paquetes/mios`) y edita uno propio (`PATCH /paquetes/mios/{id}`), con el mismo formulario del alta. La pertenencia responde el mismo 404 para un paquete ajeno, inexistente o dado de baja. Editar el precio o la descripción no consulta el plan; sólo lo consulta editar una fecha que reabre un paquete cerrado, porque eso vuelve a ocupar un lugar. Si cambia el destino, se vuelve a geocodificar (CU11), y las órdenes ya confirmadas conservan las condiciones con que se compraron. | | CU14 · Despublicar paquete y deshacer | Agencia | RF07, RF26 | `paquetes.despublicar`, `paquetes.publicar` | Al despublicar (`DELETE /paquetes/mios/{id}/publicacion`) el sistema aplica baja lógica, libera en el acto el lugar del plan y ofrece deshacer durante diez segundos desde el aviso; lo despublicado queda recuperable en la papelera durante treinta días. Reactivar (`PUT .../publicacion`) vuelve a consultar la política de publicación, porque reactivar es publicar un lugar más. | | CU15 · Contratar o renovar suscripción | Agencia | RF05 | `suscripcion.contratar` | **Desarrollado arriba en forma completa.** | | CU16 · Consultar panel de métricas | Agencia | RF16 | `agencia.metricas.ver` | El sistema presenta ventas, visualizaciones, consultas recibidas y paquetes más visitados del período seleccionado, junto con el índice de demanda por destino. Los datos son siempre de la propia agencia: no hay forma de consultar los de otra. | | CU17 · Consultar cuenta y solicitar retiro | Agencia | RF13 | `agencia.cuenta.ver`, `agencia.retiro.solicitar` | El sistema deriva el saldo sumando los asientos del libro mayor de la agencia y lista los movimientos. La agencia solicita un retiro por un importe que no puede superar el saldo disponible. La solicitud queda registrada y pasa a CU28. | | CU28 · Procesar solicitud de retiro | Administrador | RF13 | `admin.retiros.procesar` | El administrador revisa la solicitud, la aprueba o la rechaza, y el sistema asienta el débito correspondiente o deja el saldo intacto con el motivo del rechazo registrado. El saldo nunca se edita a mano: solo cambia por asientos. | ### Compra | Caso | Actor | RF | Permiso | Resumen | |---|---|---|---|---| | CU19 · Pagar la orden | Viajero | RF12 | `ordenes.crear` | El viajero es redirigido al checkout de la pasarela, donde ingresa sus datos de pago. Travia nunca recibe ni almacena datos de tarjeta. El resultado del cobro no se toma de la redirección de vuelta sino de la notificación firmada de CU20. | | CU22 · Consultar historial de compras | Viajero | RF15 | `ordenes.ver_propias` | El sistema lista las órdenes del viajero con estado explícito, fecha, importe y agencia, y permite reintentar el pago de una orden pendiente aún vigente. El permiso acota la consulta a las órdenes propias por diseño, no por filtro de la interfaz. | | CU23 · Calificar paquete y agencia | Viajero | RF14 | `resenias.crear` | El viajero califica y comenta un paquete que efectivamente contrató y cuya fecha de regreso ya pasó. El sistema admite una sola reseña por orden. La calificación alimenta el score de reputación de la agencia, que a su vez influye en el orden de los resultados de búsqueda. | ### Administración y transversales | Caso | Actor | RF | Permiso | Resumen | |---|---|---|---|---| | CU25 · Gestionar usuarios | Administrador | RF18 | `admin.usuarios.gestionar` | El administrador consulta usuarios, los bloquea o los habilita. Un usuario bloqueado no puede iniciar sesión y sus tokens vigentes se revocan. El bloqueo por administración es distinto del bloqueo temporal por intentos fallidos y no vence solo. | | CU26 · Gestionar planes | Administrador | RF20 | `admin.planes.gestionar` | El administrador crea, modifica o desactiva planes con su precio, su tope de paquetes activos y su tope de destacados mensuales. Desactivar un plan no afecta a las suscripciones vigentes: deja de ofrecerse para nuevas contrataciones. | | CU27 · Consultar dashboard administrativo | Administrador | RF21 | `admin.metricas.ver` | El sistema presenta métricas globales de usuarios, agencias, ventas, suscripciones e ingresos, con el período seleccionable. | | CU29 · Notificar al usuario | Planificador | RF22 | Proceso interno | El sistema encola y entrega notificaciones de cambio de estado de compra, vencimiento de suscripción, promociones y novedades, por correo y por push en la aplicación móvil. Si la entrega push falla, la notificación queda igualmente disponible dentro de la aplicación: el canal puede fallar, el mensaje no se pierde. | | CU30 · Consultar centro de ayuda | Visitante | RF27 | Ninguno | Cualquier usuario accede desde cualquier pantalla a la ayuda, la busca por texto y la navega por tarea. Los formularios extensos ofrecen además ayuda contextual en el campo correspondiente. |