El esquema `travia_app` concentra el dominio de negocio. Lo que sigue es el núcleo: agencias que publican paquetes, viajeros que generan órdenes, y el libro mayor que registra el dinero. Las tablas que sostienen la operación son cinco: `agencias`; `cambios_perfil_agencia`, para que las ediciones del perfil dejen rastro; `planes`, la primera que no describe a nadie sino a **lo que Travia vende**; `suscripciones`, la que ata las dos anteriores —**qué agencia compró qué plan, por cuánto y hasta cuándo**—; y `paquetes`, que es **el producto**: lo que las otras tres existen para habilitar. Alrededor están las de la venta y el dinero. Se documenta completo porque las decisiones de modelado se toman ahora —cuando todavía son baratas— y no cuando cada una arrastre una migración de datos. **Con `paquetes` el esquema deja de describir solamente quién opera y empieza a describir qué se vende.** Las cuatro tablas anteriores contaban la relación entre Travia y sus agencias; ésta es la primera fila que un viajero va a mirar, y es también la primera que **no se puede escribir sin preguntarle antes a otra tabla**: antes de guardar un paquete se consulta la suscripción de la agencia y los límites de su plan. Eso es la regla de negocio 2, y está desarrollado en la sección de `paquetes`. **Lo que decide si una agencia puede publicar es `SUSCRIPCION`, no una columna de `AGENCIA`.** 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. La tabla se escribe al contratar y es la que se consulta para saber en qué situación está una agencia; el motivo está más abajo, porque es de lo que más se puede defender de este modelo. ```mermaid erDiagram AGENCIA ||--o{ PAQUETE : publica AGENCIA ||--o{ SUSCRIPCION : contrata PLAN ||--o{ SUSCRIPCION : define AGENCIA ||--o{ ASIENTO : acumula PAQUETE ||--o{ ITINERARIO : detalla PAQUETE ||--o{ ORDEN : origina ORDEN ||--o{ PASAJERO : incluye ORDEN ||--o| PAGO : liquida ORDEN ||--o| RESENIA : habilita ORDEN ||--o{ ASIENTO : genera AGENCIA { bigint id PK bigint usuario_id UK string nombre_comercial string razon_social char cuit UK varchar legajo_evt UK string telefono decimal latitud decimal longitud datetime eliminado_en } PLAN { bigint id PK string nombre UK decimal precio_mensual int max_paquetes_activos "NULL = ilimitado, 0 = ninguno" int max_destacados_mes "NULL = ilimitado, 0 = ninguno" json beneficios "los textos de la tarjeta del plan" boolean activo "si se sigue ofreciendo" boolean es_recomendado "el distintivo «más elegido»" datetime deleted_at } SUSCRIPCION { bigint id PK bigint agencia_id FK bigint plan_id FK decimal precio_contratado "congelado el día de la firma" datetime inicia_el datetime vence_el string estado "activa | cancelada" varchar clave_idempotencia UK varchar referencia_cobro "lo que devolvió la pasarela" } PAQUETE { bigint id PK bigint agencia_id FK string nombre "sin índice único, a propósito" string pais_origen string pais_destino string ciudad_destino date fecha_salida date fecha_regreso int cupos_totales int cupos_disponibles decimal precio "12,2 · en pesos, sin columna moneda" string estado "activo | despublicado" text descripcion string imagen_principal decimal latitud_destino "NULL hasta geocodificar" decimal longitud_destino "NULL hasta geocodificar" datetime publicado_en datetime deleted_at } ORDEN { bigint id PK bigint paquete_id FK bigint usuario_id FK int cantidad_pasajeros decimal importe_total string estado datetime reserva_expira_en } PAGO { bigint id PK bigint orden_id FK string proveedor string referencia_externa UK string estado datetime notificado_en } ASIENTO { bigint id PK bigint agencia_id FK bigint orden_id FK string tipo decimal importe string concepto datetime fecha } RESENIA { bigint id PK bigint orden_id FK, UK int calificacion text comentario } ``` ## La agencia vive partida entre dos esquemas `AGENCIA` es la primera tabla que toca la frontera entre las dos bases. Los datos comerciales —nombre, razón social, CUIT, legajo, teléfono— viven en `travia_app`; la cuenta con la que se inicia sesión vive en `travia_auth`. `usuario_id` une las dos mitades y **no lleva clave foránea**. ```mermaid erDiagram USUARIO ||..o| AGENCIA : "administra (sin FK)" USUARIO { bigint id PK string email UK string hash_contrasena string estado } AGENCIA { bigint id PK bigint usuario_id UK "referencia lógica a travia_auth.usuarios" string nombre_comercial char cuit UK varchar legajo_evt UK datetime deleted_at "existe o está dada de baja" } ``` No es un olvido: **el motor no puede sostener esa restricción**. Los esquemas tienen usuarios de base de datos distintos y el usuario de negocio no tiene ningún privilegio sobre el de identidad (DOC03 puntos 2 y 9). Una clave foránea entre `travia_app.agencias` y `travia_auth.usuarios` obligaría a darle a `travia_app` visibilidad sobre la tabla de cuentas, que es exactamente lo que la separación existe para impedir. La consecuencia se asume y se declara: **la integridad referencial de esa relación es responsabilidad del código, no del motor.** El único lugar que crea las dos filas es el caso de uso de alta, y si la segunda falla borra la primera. El detalle de esa compensación está en la sección de arquitectura de la aplicación. El índice sobre `usuario_id` es único. Una cuenta administra a lo sumo una agencia, y esa regla sí puede sostenerla el motor porque no cruza esquemas. ## El perfil se edita; la identidad fiscal, no Las columnas de una persona y de una agencia se parten en dos grupos con reglas distintas: lo que su dueño edita cuando quiere, y lo que queda fijado en el alta. | Tabla | Editable desde el perfil | Fijo desde el alta | |---|---|---| | `travia_auth.usuarios` | `nombre`, `apellido`, `email`, `telefono` | `id`, `estado`, roles | | `travia_app.agencias` | `nombre_comercial`, `telefono`, `email_contacto`, `descripcion`, `logo_url` | `razon_social`, `cuit`, `legajo_evt` | **La identidad fiscal no se edita, y no por prudencia sino por definición.** Cambiar el CUIT o el legajo de una agencia no es corregir un dato: es afirmar que la fila describe a otra empresa. La corrección de un CUIT mal cargado es un trámite administrativo, que es cuando corresponde volver a mirar la documentación. En la práctica la restricción no depende de la buena voluntad de la pantalla: el formulario del servidor no declara esos campos, así que se descartan antes de llegar al caso de uso. **`agencias.email_contacto` no es el correo de la cuenta.** El de `travia_auth.usuarios` es una credencial: con él se inicia sesión y vive en el esquema de identidad. El de contacto es información comercial que el viajero va a ver junto a los paquetes, y por eso vive en el esquema de negocio. Nacen iguales —al registrarse, Travia solo conoce una dirección— y se separan en cuanto la agencia edita su perfil. Los dos son únicos, cada uno en su tabla. **`logo_url` guarda una dirección y no un archivo.** Montar almacenamiento de archivos para un logo obligaría a resolver antes límites de tamaño, tipos permitidos y servido de estáticos. Cuando exista la carga de archivos, la columna pasa a guardar la ruta del archivo subido sin que la agencia se entere. ### La bitácora de cambios Los cambios del perfil tienen que quedar registrados, y `updated_at` no alcanza: dice cuándo se tocó la fila, no qué decía antes. ```mermaid erDiagram AGENCIA ||--o{ CAMBIO_PERFIL_AGENCIA : "deja rastro en" CAMBIO_PERFIL_AGENCIA { bigint id PK bigint agencia_id FK string campo "nombre_comercial, telefono, email_contacto..." text valor_anterior "nulo si el campo estaba vacío" text valor_nuevo "nulo si se borró" bigint usuario_id "quién editó, referencia lógica" datetime ocurrido_en } ``` Se escribe **un renglón por campo modificado**, y guardar un formulario sin cambiar nada no escribe ninguno: una bitácora llena de asientos vacíos es una bitácora que después nadie lee. Los renglones de una misma edición entran en una transacción, porque media bitácora se leería como si esos campos no hubieran cambiado. La clave foránea contra `agencias` sí existe —las dos tablas viven en `travia_app`—, mientras que `usuario_id` es de nuevo una referencia lógica, por la misma razón que en `agencias`. ## La agencia no tiene estado `agencias` no tiene ninguna columna que diga en qué situación está la agencia. **Una agencia existe o está dada de baja, y eso ya lo dice `deleted_at`.** Lo que va a decidir si puede publicar es su suscripción vigente, que es otra cosa y vive en su propia tabla. **La alternativa era una columna de estado con todas las agencias en `aprobada` por defecto, y se descartó a propósito.** Deja un estado muerto, con cuatro valores posibles de los cuales tres no ocurren nunca, que alguien tiene que explicar en cada lectura del esquema y que invita a construir lógica sobre una distinción que no existe. Un dato que no distingue nada no es un dato: es una explicación pendiente. **`legajo_evt` se pide, con su índice único**, y se exige que no esté repetido; nadie comprueba después que sea auténtico contra el registro público. Es una limitación del sistema, no un olvido del modelo, y está desarrollada en el diagrama de clases de dominio junto al contraste con el CUIT. ### La baja lógica no reserva el CUIT ni el legajo Una agencia dada de baja no puede seguir reservando un CUIT ni un legajo que ya no usa: **la unicidad rige sólo entre las agencias vigentes**. Un `unique()` a secas sobre `cuit` y `legajo_evt` no sirve, porque el índice único de MySQL no distingue una fila vigente de una con `deleted_at` y el motor rechazaría con un error de clave duplicada lo que la validación y el dominio dan por libre. Los índices únicos van, entonces, sobre dos **columnas generadas** —`cuit_vigente` y `legajo_evt_vigente`—, que valen el dato mientras la agencia está vigente y `NULL` cuando está dada de baja: las vigentes chocan entre sí y las eliminadas quedan afuera del índice. Las columnas son virtuales, así que no ocupan espacio en la fila. Es la misma técnica que libera el nombre de un plan dado de baja, y con ella la validación, el dominio y el motor dicen lo mismo: un CUIT repetido entre agencias vigentes se rechaza con un 422 que dice «Ya hay una agencia registrada con ese CUIT», nunca con un error del motor. ## El padrón se lee ordenado, y por eso `agencias` tiene un índice El padrón de agencias no agrega ninguna tabla ni ninguna columna. Lo único que le suma al esquema es un índice, y conviene explicarlo porque **no existe para un filtro sino para un orden**. ```sql ALTER TABLE agencias ADD INDEX agencias_nombre_comercial_idx (nombre_comercial); ``` El padrón se muestra siempre ordenado por nombre comercial, porque quien administra encuentra «Sur Viajes» con el ojo antes que con el buscador. Un `ORDER BY nombre_comercial` sin índice obliga a MySQL a ordenar el padrón entero en memoria en cada consulta, y ese costo crece justo cuando Travia crece. **Lo que este índice no resuelve, dicho antes de que lo pregunten.** La búsqueda del padrón es por texto contenido —`LIKE '%sur%'`— y un B-tree no sirve para eso: sin un prefijo fijo no hay por dónde entrar al árbol. **La búsqueda va a barrer la tabla igual.** Lo que sí se ahorra es el ordenamiento posterior, que es la mitad del trabajo y la única mitad que un índice puede pagar hoy. Si el padrón llegara a un tamaño donde el barrido moleste, la respuesta es un índice de texto completo (FULLTEXT) sobre los campos que se buscan, y no ensanchar éste. **No es único**, y esa es otra decisión: dos agencias distintas pueden llamarse comercialmente parecido, y lo que las distingue es el CUIT y el legajo, que ya tienen su índice único. ### El padrón se arma en tres consultas, no en una por fila La grilla necesita, para cada agencia, su última suscripción y el plan de esa suscripción. La forma natural —recorrer las agencias preguntando por cada una— funciona idéntico con tres agencias de prueba y hace cincuenta consultas con cincuenta agencias reales. ```mermaid flowchart TD inicio(["GET /api/administracion/agencias"]) --> q1 q1["**1.** agencias vigentes
ORDER BY nombre_comercial
· LIKE si hay búsqueda"] q1 -->|"sin filas"| fin0(["padrón vacío
no se consulta nada más"]) q1 -->|"ids de las agencias"| q2 q2["**2.** últimas suscripciones
ROW_NUMBER() OVER
(PARTITION BY agencia_id
ORDER BY vence_el DESC, id DESC)"] q2 --> q3["**3.** todos los planes
incluidos los dados de baja"] q3 --> derivar["Suscripcion::situacionAl($ahora)
una sola lectura del reloj
para todas las filas"] derivar --> fin(["una FichaDeAgencia por fila,
con la situación ya resuelta"]) ``` La derivación de la situación **no aparece en ninguna de las tres consultas**, y ése es el punto: no hay ni un `WHERE vence_el < NOW()`. Si esa comparación estuviera en el SQL, la regla que decide quién puede publicar quedaría escrita dos veces —en PHP y en el motor— y la del motor es la que nadie prueba. Los planes se piden **todos y de una vez**, incluidos los que ya no se ofrecen: una agencia puede estar pagando un plan retirado de la vitrina, y en el padrón tiene que verse con su nombre y no como un hueco. ## `planes`: la primera tabla que no describe a nadie `agencias` describe una empresa y `cambios_perfil_agencia` describe lo que alguien hizo. `planes` describe **la oferta comercial de la plataforma**: qué se vende, a cuánto y con qué techo. Es además la tabla que destraba la regla de negocio 2, porque los dos topes que guarda son exactamente lo que decide si una agencia puede publicar un paquete más: `max_paquetes_activos` es la columna que se lee en cada intento de publicación, y es también la que se recorre para elegir el plan que se le sugiere a quien llegó al tope. ```mermaid erDiagram PLAN { bigint id PK varchar nombre UK "60 caracteres, único" decimal precio_mensual "12,2 en pesos" int max_paquetes_activos "NULL = ilimitado, 0 = ninguno" int max_destacados_mes "NULL = ilimitado, 0 = ninguno" json beneficios "lista de textos de la tarjeta" boolean activo "por omisión true" boolean es_recomendado "por omisión false" datetime deleted_at "baja lógica" } ``` **Los valores de esta tabla se siembran, no se escriben.** Los planes iniciales se siembran para que la plataforma no arranque vacía, y desde ahí los edita el panel. La consecuencia sobre el esquema es esta tabla: si los precios fueran constantes del código, `planes` no existiría y corregir una tarifa sería un despliegue. ### `NULL` es «ilimitado» y `0` es «ninguno» Son dos respuestas distintas y las dos tienen que poder darse. El Plan Inicial no permite destacar ningún paquete —`max_destacados_mes = 0`— y el Plan Agencia Pro publica sin techo —`max_paquetes_activos = NULL`—. Un solo entero con un valor mágico, `-1` o `9999` para «sin tope», colapsaría las dos en una y se rompería el día que alguien lo sumara o lo mostrara en pantalla. ```mermaid flowchart TD A["¿Entra otro paquete activo?"] --> B{"max_paquetes_activos"} B -->|"NULL"| C["Sí, siempre: el plan no tiene techo"] B -->|"0"| D["No, nunca: el plan no permite publicar"] B -->|"n > 0"| E{"¿activos hoy < n?"} E -->|"sí"| F["Entra"] E -->|"no"| G["Cupo agotado"] ``` **La convención vive en `LimitesDelPlan`, no en la columna.** El objeto de valor expone `permiteOtroPaqueteActivo()` y `permiteOtroDestacadoEsteMes()`, y es el único lugar del sistema donde se compara contra `null`. La columna solo refleja esa decisión. Los dos topes se cuentan por separado: un plan puede tener lugar para publicar y no tenerlo para destacar. ### Los beneficios son JSON y no una tabla `beneficios` guarda una lista de textos —«Soporte prioritario (respuesta en 12hs)»— que es lo que se lee en la tarjeta del plan. No son entidades: nadie los busca, nadie los filtra, nadie los relaciona con otra cosa y no tienen más atributo que su propio texto y el orden en que se muestran. **La alternativa era una tabla `beneficios_plan`, y se descartó a cambio de algo.** Lo que se pierde es poder consultarlos —contar cuántos planes ofrecen soporte telefónico, por ejemplo—; lo que se gana es no mantener claves, orden explícito y un *join* para pintar tres tarjetas que siempre se leen enteras y siempre junto a su plan. El límite de la decisión queda escrito: si algún día un beneficio pasa a ser algo que el sistema **habilita** en lugar de algo que muestra, deja de ser texto de presentación y ahí sí merece su propia tabla. El precio que se paga hoy es que una columna JSON no restringe nada por sí sola, así que la forma de los beneficios —hasta diez elementos, de hasta 120 caracteres— la sostiene entera la validación de la aplicación. ### El nombre es único entre los planes vigentes, no contra la historia La baja de planes es lógica, y **el índice único de MySQL no distingue entre una fila vigente y una con `deleted_at`**: para el motor las dos ocupan el mismo nombre. Con un `nombre UNIQUE` a secas, un plan dado de baja se llevaría su nombre con él para siempre, y volver a llamar «Plan Verano» a algo al año siguiente sería imposible. Un nombre identifica a un plan mientras el plan existe. **Un índice compuesto sobre (`nombre`, `deleted_at`) no alcanza**, aunque es la solución que uno escribe primero: MySQL considera distintos a dos `NULL`, así que dos planes vigentes —los dos con `deleted_at` nulo— pasarían el índice y el nombre dejaría de ser único justo donde importa. La forma que sí funciona es una **columna generada virtual** que vale el nombre mientras el plan está vigente y `NULL` cuando está dado de baja: ```sql nombre_vigente VARCHAR(60) GENERATED ALWAYS AS (IF(deleted_at IS NULL, nombre, NULL)) VIRTUAL UNIQUE INDEX planes_nombre_vigente_unique (nombre_vigente) ``` Los vigentes chocan entre sí; los eliminados quedan fuera del índice porque son `NULL`. La columna es virtual: se calcula al leer y no ocupa espacio en la fila. El repositorio consulta solo los vigentes, así que la aplicación y el motor dicen exactamente lo mismo. Se evaluó también borrar los planes de verdad en lugar de darlos de baja. Se descartó porque una suscripción vencida hace años sigue apuntando al plan que se contrató, y el borrado real dejaría esa referencia colgada. ### El índice compuesto es la consulta de la vitrina `planes_activo_precio_idx` cubre `(activo, precio_mensual)`, que es literalmente lo que hace `GET /api/planes`: filtrar por `activo` y ordenar de menor a mayor precio. Con el índice en ese orden el motor resuelve el filtro y el orden con una sola lectura, sin ordenar en memoria. **El orden lo decide el repositorio y no la pantalla.** Los planes se leen de barato a caro en la vitrina, en el panel y en cualquier comparación futura; si ordenara cada consumidor, bastaría con que una pantalla se olvidara para que los planes aparecieran en el orden en que se crearon, que no significa nada. ### La baja es lógica porque las suscripciones necesitan el pasado `deleted_at` no está por simetría con `agencias`: está porque una suscripción tiene que poder seguir nombrando el plan que se contrató, incluso después de que ese plan salga de la oferta. Es la misma razón por la que la suscripción va a guardar su `precio_contratado` en lugar de leerlo del plan. Por eso conviven **dos formas distintas de sacar un plan de circulación**, que no son intercambiables: | Acción | Qué hace | Cuándo corresponde | |---|---|---| | Desactivar (`activo = false`) | Sale de la vitrina, sigue existiendo y puede volver | Se deja de vender, pero hay agencias que lo tienen | | Eliminar (`deleted_at`) | Baja lógica, y el nombre vuelve a estar libre | El plan no lo tiene nadie | **Desactivar no tiene endpoint propio**: es la edición con `activo: false`. Un camino menos que mantener y una sola forma de dejar un plan fuera de la vitrina. Eliminar, en cambio, se frena si el plan tiene suscripciones vigentes: el caso de uso `EliminarPlan` se lo pregunta al puerto `ContadorDeSuscripciones`, que consulta filtrando por plan y comparando `vence_el` contra el reloj. ## `suscripciones`: el contrato que decide quién publica `agencias` describe una empresa, `planes` describe la oferta y `suscripciones` describe **el acuerdo entre las dos**: qué agencia compró qué plan, por cuánto y hasta cuándo. Es la tabla que hace que la afirmación del principio de este documento sea comprobable y no una intención: lo que habilita a publicar es una fila de acá que cubra el día de hoy. ```mermaid erDiagram AGENCIA ||--o{ SUSCRIPCION : contrata PLAN ||--o{ SUSCRIPCION : define SUSCRIPCION { bigint id PK bigint agencia_id FK "→ travia_app.agencias" bigint plan_id FK "→ travia_app.planes" decimal precio_contratado "12,2 · el precio del día de la firma" datetime inicia_el "00:00:00 del día de la contratación" datetime vence_el "23:59:59 del día del vencimiento" varchar estado "activa | cancelada · sin «vencida»" varchar clave_idempotencia UK "64 · el candado contra el doble cobro" varchar referencia_cobro "100 · lo que devolvió la pasarela" datetime created_at datetime updated_at } ``` ### Dos claves foráneas, y la que falta también es una decisión Tiene **dos claves foráneas reales**, y las dos existen por el mismo motivo: `agencias` y `planes` viven en `travia_app`, igual que ella, así que el motor puede sostener la coherencia y se le pide que lo haga. **Lo que no hay es ninguna columna hacia `travia_auth`, y esa ausencia es la misma decisión que ya se explicó en `agencias`.** Podría parecer natural guardar quién firmó la contratación, pero el usuario de base de datos del esquema de negocio no tiene un solo privilegio sobre el de identidad (DOC03 puntos 2 y 9): una foránea entre esquemas sería una promesa que ninguna conexión puede cumplir. Si algún día hace falta saber qué persona contrató, se llega por la agencia, que es de quien es el contrato. **El contrato es entre Travia y una empresa, no entre Travia y una persona**, así que el modelo no pierde nada por no tenerla. La foránea a `planes` va **sin `restrictOnDelete`**, y conviene decir por qué no es un olvido: la baja de planes es lógica —`eliminar` solo escribe `deleted_at`— así que el motor nunca llega a ver un `DELETE` que restringir. Esa regla la sostiene el caso de uso `EliminarPlan` preguntándole al puerto `ContadorDeSuscripciones`, que además puede explicar por qué no se puede en lugar de arrojar un error de integridad. Lo que sí aporta la foránea común es lo otro: que ninguna suscripción nombre un plan que no existe. ### El precio se congela en la fila `precio_contratado` es la columna que un `JOIN` contra `planes.precio_mensual` volvería innecesaria, y ahí está justamente la trampa. **Un aumento de la oferta comercial rige para la próxima renovación, nunca para el período en curso**: quien pagó treinta mil sigue debiendo treinta mil hasta que termine su mes. Sin esta columna, editar un plan desde el panel **reescribiría el pasado**, y el comprobante de agosto pasaría a decir en septiembre otra cosa de la que se cobró. El precio de un plan es un dato del plan; el precio de un contrato es un dato del contrato, y son dos cosas distintas aunque el día de la firma coincidan. Es el mismo motivo por el que una factura guarda el importe y no un puntero al catálogo. El nombre del plan, en cambio, **no se copia**: la suscripción guarda `plan_id` y quien la muestra lo resuelve por el repositorio. Un plan renombrado sigue siendo el mismo plan, así que ahí la referencia es correcta; lo que no puede cambiar retroactivamente es lo que se cobró. ### `estado` no tiene el valor «vencida», y esa ausencia es la decisión La columna admite `activa` y `cancelada`. **«Vencida» sería el tercer caso obvio y es exactamente el que no hay que persistir.** ```mermaid flowchart TD A["¿En qué situación está la suscripción?"] --> B{"estado"} B -->|"cancelada"| C["Cancelada
alguien decidió darla de baja"] B -->|"activa"| D{"¿vence_el cubre el momento?"} D -->|"no"| E["Suspendida por impago
falta renovar"] D -->|"sí"| F{"¿faltan 7 días o menos?"} F -->|"sí"| G["Por vencer
avisa, pero habilita"] F -->|"no"| H["Vigente"] ``` Una suscripción no se vence porque alguien la marque: se vence porque pasó el tiempo, y eso ya está escrito en `vence_el`. Si el vencimiento fuera un valor guardado, **la verdad del sistema dependería de un proceso nocturno** que saliera a recorrer filas para ponerlas en «vencida», y de que ese proceso efectivamente haya corrido. La noche que fallara habría agencias publicando con la suscripción terminada, y otras marcadas como vencidas después de haber renovado. Comparando `vence_el` contra el reloj, la respuesta se calcula cada vez que se pregunta y no puede quedar desactualizada. Lo que sí se persiste es la cancelación, porque ésa no la produce el paso del tiempo sino **una decisión de alguien**, y de eso no queda rastro en ninguna fecha. La distinción vive en dos tipos separados del dominio y no en un solo enum: `EstadoSuscripcion` es lo que la columna guarda, y `SituacionDeSuscripcion` —`vigente`, `por_vencer`, `suspendida_por_impago`, `cancelada`— es lo que se deriva. El diagrama de arriba es literalmente el orden de preguntas de `Suscripcion::situacionAl()`, y ese orden importa: **una suscripción cancelada se informa como cancelada aunque le queden días de calendario**, porque decir «suspendida por impago» de quien dio de baja sería acusarlo de algo que no hizo. ### Las fechas llevan hora aunque el plan se venda por días `inicia_el` y `vence_el` son `datetime` y no `date`, y el redondeo a día entero —de las 00:00:00 del día de la contratación a las 23:59:59 del día del vencimiento— **lo hace la entidad al contratar, no el mapeador ni el SQL**. Es una regla de negocio —cuánto dura lo que se compró— y no un detalle de cómo se guarda. Si el redondeo viviera en la persistencia, el dominio creería una cosa, la base guardaría otra y la comparación contra el reloj daría una tercera. Con un `DATE` se caería justo el extremo que importa: el fin de día volvería de la base convertido en medianoche y la agencia quedaría suspendida el primer minuto del día que tenía pago. ### `clave_idempotencia` es única, y el índice es el que gana la carrera La contratación es el único circuito del sistema que mueve dinero, así que repetirla no cuesta una fila de más: cuesta **un cobro de más**. La protección son dos piezas que hacen cosas distintas y ninguna reemplaza a la otra: | Pieza | Qué aporta | Qué no puede | |---|---|---| | La comprobación del caso de uso | Devuelve la suscripción que produjo el primer envío, con un mensaje que la agencia entiende y sin volver a tocar la pasarela | Cubrir la ventana entre preguntar y escribir | | El índice único de la columna | Que en dos envíos simultáneos gane uno solo, aunque los dos hayan pasado la comprobación | Explicar nada: es un choque de índice | Es la misma sociedad que ya se usó con el nombre del plan —la comprobación explica, el índice garantiza—, con una diferencia de precio: allá perder la carrera dejaba un nombre repetido, y acá dejaría un cobro repetido. **La clave la genera el cliente y no el servidor**, y ése es todo el mecanismo: el formulario la crea una vez al abrirse y la manda igual en todos sus envíos, así que un doble clic trae la misma clave y una renovación del mes que viene trae una nueva. Un servidor que la generara al recibir tendría una clave distinta en cada envío y no distinguiría nada. La columna es `varchar(64)` porque se espera un UUID o equivalente, y el mínimo de ocho caracteres que exige el formulario evita que una clave corta la repita otro cliente por casualidad. ### Los dos índices compuestos son dos consultas concretas | Índice | Consulta que resuelve | Quién la hace | |---|---|---| | `suscripciones_agencia_vence_idx` sobre `(agencia_id, vence_el)` | «La última suscripción de esta agencia», de a una o de a muchas | Cada contratación, para saber si hay una vigente; la ficha «Tu suscripción»; y el padrón de agencias, que la pide para todas las agencias de la pantalla a la vez | | `suscripciones_plan_vence_idx` sobre `(plan_id, vence_el)` | «¿Hay suscripciones vigentes de este plan?» | `EliminarPlan`, antes de dejar dar de baja un plan | Ninguno de los dos es preventivo: los dos son el par de columnas exacto que su consulta filtra y ordena, en ese orden, de modo que MySQL llega a la fila leyendo el índice y no ordena en memoria. **El primero de los dos tiene un segundo consumidor, y con él la consulta más elaborada del modelo.** El padrón necesita «la última suscripción» de cincuenta agencias a la vez, y la resuelve **en una sola consulta**, con una función de ventana: ```sql SELECT * FROM ( SELECT *, ROW_NUMBER() OVER (PARTITION BY agencia_id ORDER BY vence_el DESC, id DESC) AS orden FROM suscripciones WHERE agencia_id IN (?, ?, ?) ) AS ultimas WHERE orden = 1; ``` Son dos niveles y no uno porque **la ventana no se puede filtrar donde se calcula**: cuando se evalúa el `WHERE`, `ROW_NUMBER()` todavía no existe. Los identificadores viajan como parámetros ligados; el `selectRaw` no lleva un solo valor de entrada, sólo nombres de columna escritos en el código. El criterio de ordenamiento es **idéntico al del método singular** —vencimiento más lejano y, ante empate, el id más alto—, y eso es lo que garantiza que el padrón y el panel de la agencia miren la misma suscripción. El índice cubre justo el filtro y la partición, así que la ventana se calcula recorriendo el índice. Las dos alternativas se descartaron por lo mismo, por **partir el criterio en dos lugares**: | Alternativa | Por qué se descartó | |---|---| | `GROUP BY agencia_id` con `MAX(vence_el)` y un join contra la propia tabla | Resuelve el vencimiento y **no resuelve el empate**: dos suscripciones que vencen el mismo día devuelven dos filas, y hace falta un segundo nivel de subconsulta —el `MAX(id)` entre las que empataron— para volver a quedarse con una. El desempate terminaría escrito en un lugar distinto que el orden principal | | Traer el historial completo de esas agencias, ordenado, y quedarse en PHP con la primera de cada una | También es una sola consulta, pero **lee el historial entero para devolver una fila por agencia**. Hoy son pocos meses; con dos años de renovaciones son veinticuatro filas leídas para usar una | Es el mismo criterio con el que se eligió `planes_activo_precio_idx`, y el mismo argumento sirve para explicar por qué no hay un índice sobre `estado`: nadie pregunta por el estado sin preguntar antes por una agencia o por un plan. ### Lo que esta tabla no modela **No hay renovación automática ni cobro recurrente.** Una suscripción se contrata una vez y dura un mes; renovar es contratar de nuevo, con un formulario nuevo y una clave de idempotencia nueva. El modelo lo admite —una agencia puede tener varias filas a lo largo del tiempo, y lo que se comprueba antes de contratar es que la última no esté vigente— pero nadie cobra solo. **No hay cambio de plan a mitad de período.** La entidad tiene `cancelada()`, que conserva el período pagado, pero ningún caso de uso la invoca. Un cambio de plan con prorrateo exigiría además decidir qué se hace con la diferencia de precio, y esa decisión no está tomada. Queda declarado acá para que sea una limitación conocida y no un hallazgo. ## `paquetes`: el producto, y la primera escritura que pide permiso `agencias` describe una empresa, `planes` describe la oferta y `suscripciones` describe el acuerdo entre las dos. **`paquetes` es aquello para lo que existen las tres**: el viaje que una agencia pone a la venta y que un viajero compra. Las órdenes apuntan contra estas filas. Es además la primera tabla del proyecto en la que **insertar una fila no es una decisión del formulario**. En `agencias`, `planes` y `suscripciones` la escritura se rechaza por lo que trae el propio dato —un CUIT repetido, un nombre tomado, un cobro que falló—; acá se rechaza por algo que no está en el formulario: cuántos paquetes tiene ya publicados esa agencia y qué plan está pagando. Eso es la regla de negocio 2 y está desarrollado dos títulos más abajo. ```mermaid erDiagram AGENCIA ||--o{ PAQUETE : publica PAQUETE { bigint id PK bigint agencia_id FK "→ travia_app.agencias" varchar nombre "150 · sin índice único, a propósito" varchar pais_origen_codigo "2 · ISO 3166-1 alfa-2, sin FK" varchar pais_destino_codigo "2 · ISO 3166-1 alfa-2, sin FK" varchar ciudad_destino "120" decimal latitud_destino "9,6 · NULL hasta geocodificar" decimal longitud_destino "10,6 · NULL hasta geocodificar" date fecha_salida "DATE, no DATETIME" date fecha_regreso "DATE, no DATETIME" int cupos_totales "unsigned" int cupos_disponibles "unsigned" decimal precio "12,2 · en pesos, sin columna moneda" varchar estado "20 · activo | despublicado" text descripcion "NULL" varchar imagen_principal "500 · obligatoria · la referencia, no el archivo" datetime publicado_en "NULL · cuándo salió a la vitrina" datetime created_at datetime updated_at datetime deleted_at } ``` Una sola clave foránea, `agencia_id` contra `agencias`, y por el mismo motivo de siempre: las dos tablas viven en `travia_app`, así que el motor puede sostener la coherencia y se le pide que lo haga. **Lo que no hay —y no puede haber— es ninguna columna hacia `travia_auth`**: quién publicó se sabe por la agencia, porque el usuario de base de datos del esquema de negocio no tiene un solo privilegio sobre el de identidad (DOC03 puntos 2 y 9). Es la cuarta foránea del proyecto y las cuatro son internas al mismo esquema. ### Publicar no es insertar: acá es donde se consulta la regla de negocio 2 **Éste es el punto del modelo que sostiene el punto 7 de DOC01** —que el sistema no sea sólo un CRUD—. El límite de paquetes por plan vive en `LimitesDelPlan`, y los datos para aplicarlo en `suscripciones`, que dice qué plan paga cada agencia. Publicar es la escritura que los consulta. ```mermaid sequenceDiagram autonumber participant M as PublicarPaquete
(caso de uso) participant S as suscripciones participant PL as planes participant PQ as paquetes participant P as PoliticaDePublicacion
(dominio) M->>S: última suscripción de la agencia S-->>M: la fila, o nada M->>M: situacionAl(ahora) · si no habilita, 402 M->>PL: el plan de esa suscripción M->>PQ: COUNT de paquetes activos
(paquetes_cupo_del_plan_idx) PQ-->>M: N M->>PL: la oferta vigente, para poder sugerir M->>P: evaluar(situación, plan, N, oferta) alt Concedido P-->>M: permiso + límite + consumo M->>PQ: INSERT del paquete M-->>M: 201 con consumo_del_plan else Rechazado por límite P-->>M: motivo + tope + activos + plan sugerido,
o la señal de tope de la oferta si no hay a dónde subir M-->>M: 409 con la salida concreta end ``` Tres cosas de ese diagrama son la decisión, y no el orden natural de los pasos: - **Se pregunta por la suscripción antes que por el límite.** A quien no tiene el mes pago no le sirve que le sugieran cambiar de plan, y preguntar al revés le daría a una agencia vencida con lugar de sobra un «podés publicar» que después hay que desautorizar. - **Se cuenta contra la base y se decide en el dominio.** Contar es leer, y leer es trabajo de un adaptador; comparar el número contra el tope es la regla. `PoliticaDePublicacion` no consulta nada: recibe los tres datos ya resueltos y devuelve una decisión, que es la única razón por la que se puede probar entera sin base y sin reloj. - **El rechazo trae la salida, y la salida la calcula el dominio.** Cuando el límite no alcanza, la respuesta no es un «no»: viene con el plan más barato de la oferta vigente que sí permitiría publicar —a igual precio, el que más permite— o con la señal de que la agencia ya está en el tope de lo que Travia ofrece. Esa elección vive en la misma clase que compara los límites y no en el controlador: si la decidiera la capa HTTP quedaría fuera del dominio, sin pruebas propias, y habría que reescribirla en cada pantalla que rechace una publicación. Es lo que pide el punto 9 de DOC02. El `INSERT` ocurre **después** de que la política dijo que sí. Publicar primero y validar después dejaría paquetes visibles de agencias que no podían publicarlos, y haría falta un proceso aparte que saliera a borrarlos. ### Qué cuenta como «paquete activo» El límite del plan se mide contra un número, así que ese número tiene que estar definido en un solo lugar. **Un paquete ocupa un lugar del plan cuando su estado es `activo`, no está dado de baja y su fecha de salida todavía no pasó.** Es literalmente el filtro de `RepositorioPaquetes::contarActivosDeAgencia()` y es también lo que responde `SituacionDePaquete::ocupaCupoDelPlan()` sobre una entidad ya cargada: si el repositorio contara una cosa y la entidad dijera otra, la agencia vería seis paquetes en su panel y el sistema le diría que tiene siete. ```mermaid flowchart TD A["¿Cómo se ve hoy este paquete?"] --> B{"estado"} B -->|"despublicado"| C["Despublicado
no ocupa lugar del plan"] B -->|"activo"| D{"¿la fecha de salida ya pasó?"} D -->|"sí"| E["Ventas cerradas
no ocupa lugar del plan"] D -->|"no"| F{"¿quedan cupos?"} F -->|"no"| G["Agotado
SÍ ocupa lugar del plan"] F -->|"sí"| H["Disponible
SÍ ocupa lugar del plan"] ``` | Situación | Se ve en el catálogo | Admite reservas | Ocupa lugar del plan | |---|---|---|---| | Disponible | Sí | Sí | **Sí** | | Agotado | Sí | No | **Sí** | | Ventas cerradas | No | No | No | | Despublicado | No | No | No | **Los dos casos que deciden el criterio son «agotado» y «cerrado», y van para lados distintos a propósito.** Un agotado sigue ocupando: está publicado, ocupa lugar en la vitrina y puede recuperar cupo en cuanto se cancele una compra, así que sacarlo de la cuenta le dejaría a la agencia publicar de más y volver a pasarse del tope sola. Uno cuya fecha ya pasó, en cambio, no ocupa nada: si los viajes viejos siguieran contando, **una agencia del Plan Básico se quedaría sin poder publicar para siempre al tercer viaje vendido**, y el límite dejaría de medir la oferta vigente para pasar a medir el historial. Un tope de publicaciones que crece con el tiempo no es un tope: es una fecha de caducidad de la cuenta. **El orden en que se pregunta también es la regla.** «Despublicado» gana sobre todo lo demás porque es una decisión explícita de la agencia y no puede quedar tapada por el cupo; después viene la fecha, porque un micro que ya partió no se vende aunque le sobren lugares; y recién al final se mira el cupo. Nada de esto se persiste. **Ni «agotado» ni «vencido» son valores de `estado`**, por el mismo motivo por el que `suscripciones.estado` no tiene «vencida»: un paquete no está agotado porque alguien lo marque sino porque `cupos_disponibles` llegó a cero, y no está cerrado porque un proceso nocturno lo haya recorrido sino porque `fecha_salida` ya pasó. Los dos se deducen de columnas que ya están, con el reloj del dominio en la mano. Lo único que se guarda es la decisión de retirarlo de la vitrina, porque ésa no la produce el paso del tiempo. ### Los índices son consultas, y el de `precio` está ausente a propósito | Índice | Columnas | Consulta que resuelve | |---|---|---| | `paquetes_cupo_del_plan_idx` | `(agencia_id, estado, deleted_at, fecha_salida)` | **El límite del plan**: cuántos paquetes de esta agencia ocupan un lugar. Corre en cada intento de publicación. Sirve además el filtro `agencia_id` del catálogo, porque empieza por esa columna | | `paquetes_catalogo_destino_idx` | `(pais_destino_codigo, ciudad_destino, fecha_salida)` | Viajes a una **ciudad** que salgan dentro de un rango: la búsqueda por ciudad y el mapa de la geolocalización. Filtra por el código ISO y no por texto libre. La búsqueda por país no lo usa, porque no busca por ciudad | | `paquetes_salida_idx` | `(fecha_salida)` | La portada y las «próximas salidas»: el catálogo sin filtro de destino, ordenado por fecha. Es también el de `GET /api/paquetes` sin `pais_destino` | | `paquetes_catalogo_pais_salida_idx` | `(pais_destino_codigo, fecha_salida)` | **La búsqueda pública por país**: viajes a un país que todavía no salieron, ya ordenados por salida | **El primero es literalmente la definición de «paquete activo» escrita como índice**, y el orden de sus columnas no es decorativo. Las tres primeras entran como igualdad —`deleted_at IS NULL` también: MySQL resuelve un `IS NULL` por acceso `ref` y no barriendo— y `fecha_salida` queda al final, que es donde tiene que ir la única comparación por rango, porque después de un rango el resto del índice ya no puede usarse para filtrar. Con las cuatro columnas adentro **el `EXPLAIN` reporta `Using index` y el `COUNT` se contesta sin ir a buscar una sola fila**. Que `deleted_at` esté *dentro* del índice y no afuera es la parte que se pasa por alto. Eloquent agrega el `deleted_at IS NULL` a cada consulta por su cuenta, así que dejarlo fuera del índice habría obligado al motor a leer cada fila candidata para descartarla; incluirlo cuesta ocho bytes por entrada y convierte la consulta más caliente de la tabla en una lectura de índice pura. **El segundo arranca por el destino y no por `estado`, al revés que el primero, y la inversión está buscada.** Ahí `estado` y `deleted_at` no descartan casi nada —la abrumadora mayoría de los paquetes de la tabla están activos y vivos—, así que ponerlos adelante engordaría cada entrada del índice para filtrar prácticamente ninguna fila. Lo que sí descarta es el destino. Y el país va antes que la ciudad porque «quiero ir a Brasil» es una búsqueda corriente y «quiero ir a una ciudad sin decir de qué país» no lo es. **No hay índice sobre `precio`, y conviene dejar dicho por qué no es un olvido.** El catálogo va a poder ordenarse por precio, pero siempre después de filtrar por destino o por fecha, y MySQL usa un solo índice por tabla en cada consulta: uno sobre `precio` a secas quedaría sin usar salvo para ordenar el catálogo completo sin ningún filtro, que no es una pantalla que exista. Ordenar por precio viene siempre después de filtrar por la fecha —`fecha_salida >= hoy` está en todas las consultas de la vitrina—, y un índice sólo puede servir un rango o un orden distinto de él, no los dos. El *filesort* se hace sobre lo ya filtrado por país y fecha, que es poco. **El filtro por rango de precio es el mismo caso**: queda como filtro residual sobre lo que ya recortaron el destino y la fecha (ver más abajo). Agregar `precio` sería adivinar, y un índice que nadie usa se paga en cada inserción. Tampoco se crea un índice propio para la foránea: MySQL exige uno que empiece por la columna referenciada y `paquetes_cupo_del_plan_idx` ya arranca con `agencia_id`, así que el motor lo reutiliza. ### La búsqueda por país tiene su propio índice, porque el de ciudad no alcanza La búsqueda pública filtra por **país** de destino, no por ciudad, y siempre con la fecha de salida por rango: `fecha_salida >= hoy` va en todas las consultas de la vitrina y la ventana que pide el viajero es un `BETWEEN`. El orden por defecto es, además, `fecha_salida, id`. **`paquetes_catalogo_destino_idx` no servía para esa consulta, aunque empiece por el país.** Es `(pais_destino_codigo, ciudad_destino, fecha_salida)`: sin ciudad en el `WHERE`, la columna del medio corta el índice. MySQL entra por el país y después tiene que leer **todos** los paquetes de ese país —también los que ya salieron, que con el tiempo son la mayoría— y filtrar la fecha fila por fila. Y tampoco da el orden, porque dentro de un país las entradas están ordenadas por ciudad y no por fecha: cada página terminaría en un *filesort*. ```sql ALTER TABLE paquetes ADD INDEX paquetes_catalogo_pais_salida_idx (pais_destino_codigo, fecha_salida); ``` **`(pais_destino_codigo, fecha_salida)` pone la igualdad adelante y el único rango al final**, que es donde tiene que ir —el mismo criterio que el índice del límite del plan—. Con «Brasil, desde hoy» el motor recorre sólo los viajes a Brasil que todavía no salieron, y los recorre ya ordenados. InnoDB agrega la clave primaria al final de todo índice secundario, así que las entradas quedan en orden `(país, fecha_salida, id)`: **exactamente el `ORDER BY` del orden por defecto con su desempate**, y el `LIMIT 12` puede cortar sin ordenar nada. ```mermaid flowchart LR Q["WHERE pais_destino_codigo = 'BR'
AND fecha_salida >= hoy
ORDER BY fecha_salida, id
LIMIT 12"] Q --> V{"¿Qué índice?"} V -->|"(país, ciudad, fecha)"| A["La ciudad corta el índice:
lee todo Brasil, también lo salido,
y ordena con filesort"] V -->|"(país, fecha) + id implícito"| B["Recorre sólo lo que no salió,
ya en el orden pedido:
corta en la fila 12"] ``` **Se evaluó reemplazar el índice de ciudad por éste, y se descartó.** Buscar por ciudad —el mapa que llega con la geolocalización— sigue necesitando `(país, ciudad, fecha)`. El ahorro sería un índice menos que mantener en una tabla que se escribe poco —las agencias publican, los viajeros leen—, y el costo sería volver a barrer el país entero en cuanto la ciudad entre al buscador. Se paga un índice más en cada inserción a cambio de que las dos búsquedas tengan el suyo. **Lo que deliberadamente no se indexa:** | Columna | Por qué no | |---|---| | Ninguna, cuando no hay destino | `paquetes_salida_idx (fecha_salida)` ya cubre la portada: el rango por fecha y el orden por `fecha_salida, id` salen del mismo índice | | `pais_origen_codigo` | Buscar sólo por origen no es una pantalla del producto —se sale casi siempre desde Argentina, así que el origen descarta poco— y combinado con el destino llega tarde: el destino ya redujo las filas | | `cupos_disponibles` | Es una comparación por rango sobre una columna que cambia con cada venta. Queda como filtro residual sobre lo que ya recortaron el país y la fecha | | `precio` | Lo explicado arriba: el orden por precio va después del rango por fecha, y un índice no sirve las dos cosas. El filtro por rango de precio es el mismo caso: un segundo rango después del de la fecha no puede usar el índice | | `estado`, `deleted_at` | Casi todas las filas están activas y vivas: no descartan nada. Es el mismo argumento con el que el índice de destino arrancó por el país y no por el estado | ### Los filtros del catálogo no piden cambios de esquema El catálogo se filtra por precio, por noches y por agencia **sin tocar el esquema**: ni columna ni índice nuevo. Cada filtro tiene su motivo. | Filtro | Condición en SQL | Qué índice lo sirve | |---|---|---| | `agencia_id` | `paquetes.agencia_id = ?` | `paquetes_cupo_del_plan_idx`, que empieza por `agencia_id`. Es la foránea, y MySQL ya exigía un índice que arrancara por ella | | `precio_minimo`, `precio_maximo` | `paquetes.precio >= ?` y `<= ?`, con el importe ligado como decimal exacto | **Ninguno, a propósito.** Es un segundo rango después del de `fecha_salida`, y después de un rango el resto del índice ya no filtra. Recorta lo que ya recortaron el destino y la fecha | | `noches_minimas`, `noches_maximas` | `DATEDIFF(fecha_regreso, fecha_salida) >= ?` y `<= ?` | **Ninguno, y ninguno podría sin cambiar el esquema.** Es una expresión sobre dos columnas: sólo la cubriría una columna generada indexada | **Por qué las noches no se guardan, aunque indexarlas lo exigiría.** Una columna `noches` sería la misma concesión que ya se negó `cantidad_dias` (ver abajo): un dato derivado de las fechas que puede contradecirlas. Una columna **generada** —`noches AS (DATEDIFF(fecha_regreso, fecha_salida)) STORED`— no puede contradecirlas y sí admite índice, y es la salida si alguna vez hiciera falta. No se agregó porque hoy no descarta nada que el destino y la fecha no hayan descartado antes, y sería un índice más en cada inserción sin medición que lo pida. `Paquete::noches()` en el dominio y `DATEDIFF` en el SQL dicen lo mismo: días de calendario entre salida y regreso, también cuando el viaje cruza de mes. **Las facetas son agregados sobre las mismas condiciones.** El rango de precios y de noches y las agencias presentes (`FacetasDelCatalogo`) salen de `MIN`, `MAX` y `COUNT` sobre el mismo armado de la vitrina, más un `GROUP BY agencias.id` para las agencias. No leen ninguna tabla nueva ni cruzan con `suscripciones`. **Es diseño, no medición.** Si el catálogo creciera al punto de que el recorte por destino y fecha dejara demasiadas filas, la decisión se toma con un `EXPLAIN` en la mano y no antes. ### `cantidad_dias` no se persiste El formulario la muestra y la tarjeta del catálogo la necesita. **Y aun así no hay columna.** Guardarla sería admitir que exista un paquete que sale el 1, vuelve el 5 y dice durar diez días: tres números que se contradicen y ninguna forma de saber cuál de ellos es el bueno. La duración se deriva de `fecha_salida` y `fecha_regreso` cada vez que se pregunta —`Paquete::duracionEnDias()`, contando salida y regreso, que es como la cuenta una agencia de viajes— y **se publica en la API aunque no se guarde**. Que un dato viaje en la respuesta no obliga a que exista como columna: lo que la pantalla necesita es el número, y lo que la base tiene que garantizar es que no pueda contradecir a las fechas de las que sale. Una columna derivada sólo puede desincronizarse. Por lo mismo el formulario **no acepta** `cantidad_dias` como campo de entrada: si viajara como dato habría que elegir a cuál de los tres creerle. ### `nombre` no es único, ni global ni por agencia No hay índice único sobre `nombre`. **Es una decisión explícita y no un descuido que convenga «arreglar» más adelante**, así que queda escrita acá para que nadie la lea como deuda. | Alternativa | Por qué se descartó | |---|---| | Único global | Dos agencias pueden publicar «Bariloche 5 días» y las dos tienen razón: es el nombre de un destino, no una marca. El único convertiría al primero que publica en dueño de una palabra del castellano | | Único por agencia | Una misma agencia repite el mismo viaje cada temporada. Ese es justamente el caso que quedaría prohibido, y es el más frecuente de todos | El paquete se identifica por su `id`, y lo que lo distingue para un viajero es el conjunto de destino, fechas y precio, no el título. Cuando dos paquetes de la misma agencia se llaman igual, lo que hay es dos salidas distintas del mismo viaje, que es exactamente lo que una agencia carga. **La baja es lógica y no reserva ningún valor**, y acá eso sale gratis. `deleted_at` existe para que las órdenes ya vendidas puedan seguir nombrando el paquete que se compró. Como la tabla no tiene ninguna restricción de unicidad, no hace falta la columna generada que usan `planes` y `agencias` para que una fila dada de baja no siga reservando su valor. **Y si algún día se agregara una restricción única a esta tabla, tendría que nacer escrita sobre una columna generada que se anule con la baja.** ### El precio se guarda como el de un plan, y no hay columna `moneda` `precio` es `decimal(12,2)` en pesos. El dominio lo maneja como `Dinero`, que guarda **centavos enteros** porque sumar importes con decimales de coma flotante descuadra los saldos; la columna es un decimal con dos posiciones, que es como se escribe un precio y como lo espera cualquiera que consulte la base a mano. La conversión entre una forma y la otra la hace el mapeador, en un único punto. **Es exactamente el criterio de `planes.precio_mensual` y de `suscripciones.precio_contratado`, y eso es lo que se estaba eligiendo.** Guardar centavos enteros acá —una columna `precio_centavos`— sería igual de correcto tomado en sí mismo y peor para Travia: dejaría **dos convenciones de dinero conviviendo en el mismo esquema**, cualquier informe SQL que cruce paquetes con suscripciones tendría que dividir una columna por cien y la otra no, y el día que una orden multiplique el precio del paquete por la cantidad de pasajeros habría que recordar de qué lado está cada una. Una sola forma de guardar dinero vale más que la mejor de las dos formas aplicada a la mitad de las tablas. Tampoco hay columna `moneda`, por lo mismo que no la tienen las otras dos: Travia opera en pesos argentinos. El día que haya más de una moneda se agrega la columna **en las tres tablas a la vez** y se lee en los mapeadores, sin tocar el dominio, que ya la trae dentro de cada `Dinero`. ### Las fechas del viaje son `DATE`, y las del período de la suscripción no `fecha_salida` y `fecha_regreso` son `DATE`. `suscripciones.inicia_el` y `vence_el` son `DATETIME`. **La diferencia está buscada y las dos elecciones son correctas, porque no miden lo mismo.** En la suscripción el extremo importa a la hora: el mes pago termina a las 23:59:59 y un `DATE` le habría quitado a la agencia el último día. En el paquete no hay ninguna hora que preservar —un viaje sale un día, no a las 00:00:00Z del día— y el dominio compara siempre contra **el comienzo del día** (`$ahora->setTime(0, 0, 0)`), justamente para que un viaje que sale hoy a la tarde se pueda publicar hoy al mediodía. Una hora guardada acá no cambiaría ninguna respuesta y sólo abriría la puerta a que dos paquetes cargados la misma mañana se ordenaran distinto por un dato que nadie completó a propósito. Es también la razón por la que la API las manda como `aaaa-mm-dd` y no en formato completo: una fecha con hora y huso hace que un navegador al oeste de Greenwich muestre el día anterior. `publicado_en` sí es un instante, y ahí el huso es el dato. ### Las coordenadas nacen nulas, y `NULL` significa «todavía no» `latitud_destino` y `longitud_destino` son `decimal(9,6)` y `decimal(10,6)` nulables. La longitud lleva un entero más porque llega a 180 y la latitud a 90. **Seis decimales y no siete**: el dominio considera iguales dos coordenadas que coinciden hasta el sexto decimal —unos 11 cm— porque más precisión que eso es ruido del proveedor y no una ubicación distinta (`Coordenada::equivaleA()`). Guardar más dígitos sería guardar diferencias que el propio sistema decide ignorar. **Nacen en `NULL` porque la geocodificación corre aparte.** Geocodificar depende de un servicio externo, y su disponibilidad no puede impedirle a una agencia poner un viaje a la venta ni demorar la publicación mientras alguien espera una respuesta HTTP. Por eso `NULL` acá quiere decir **«todavía no lo geocodificamos»** y nunca «no se pudo»: la API lo publica como `pendiente_de_geocodificar`, para que el mapa sepa a quién le falta ubicación en lugar de tener que adivinarlo de la ausencia de dos números. ### Cuándo salió a la vitrina y con qué imagen **`publicado_en` está separada de `created_at` a propósito.** Son dos datos distintos —uno es cuándo se escribió la fila y el otro cuándo el paquete salió a la vitrina— que coinciden mientras un paquete se cree publicado, y se separan en cuanto exista un borrador o una importación masiva que cargue un día lo que se publica el lunes. Por eso el orden del catálogo —«lo más nuevo primero»— mira `publicado_en` y no `created_at`. **La imagen es una URL y no un archivo subido, y es obligatoria.** `imagen_principal` guarda la referencia; cuando exista la carga de archivos, el campo recibe la ruta que devuelva esa carga y la validación se amplía en un solo lugar. Es obligatoria porque un paquete sin foto no se vende y la tarjeta del catálogo no tiene cómo mostrarlo, y la validación acota su largo al de la columna, 500 caracteres, para que una URL larga se rechace con un 422 y no llegue al motor. ## `paises`: el catálogo que sostiene a RF06 Si el país de origen y el de destino se validaran como texto libre, «Argentina», «argentina» y «ARG» serían tres destinos distintos para el catálogo y para la geocodificación. Por eso se validan contra un universo cerrado de valores. **Ningún requerimiento funcional pide un catálogo de países**: la tabla nace como soporte de RF06, con el mismo criterio que `cambios_perfil_agencia` —una pieza que ningún RF nombra sosteniendo uno que sí existe—, aunque a diferencia de esa tabla ésta tiene pantalla de administración propia y merece su propia sección. ```mermaid erDiagram PAIS { varchar codigo PK "2 · ISO 3166-1 alfa-2" varchar nombre "100" datetime created_at datetime updated_at datetime deleted_at } ``` **Por qué es una tabla administrable y no un `enum` ni un arreglo de constantes.** Un `enum` habría sido más barato de escribir y es exactamente el error que se evita con los planes: cambiar un país —o corregirle el nombre— exigiría un despliegue. Se siembra con las **249 entradas de la norma ISO 3166-1** y queda con alta y baja lógica desde `/administracion/paises`, detrás de un permiso propio, `admin.paises.gestionar`, deliberadamente **distinto** del de planes: administrar la oferta comercial y administrar un catálogo geográfico son dos responsabilidades, aunque las tenga el mismo rol. **No tiene edición, y no es una omisión.** Corregir el nombre de un país no es una operación que la búsqueda ni la geocodificación necesiten, así que queda fuera hasta que alguien la pida. **La siembra inserta sólo los códigos que nunca existieron.** Si insertara o "actualizara" todos los códigos en cada corrida, un país que la administración dio de baja **volvería a aparecer** en la siembra siguiente, deshaciendo una decisión administrativa cada vez que se despliega. **La unicidad es sólo entre las filas vigentes.** `codigo` tiene un índice único sobre una columna generada que se anula con `deleted_at`, la misma técnica que usan `planes.nombre` y `agencias.cuit`/`legajo_evt`. **`paquetes` la referencia por código y sin clave foránea, y es una concesión deliberada.** `pais_origen_codigo` y `pais_destino_codigo` guardan el código ISO y no el `id` de una fila de `paises` —esta tabla no tiene `id` numérico, el código **es** la clave primaria—, porque el código es la identidad estable: dar de baja y volver a dar de alta un país crea otra fila pero sigue siendo el mismo país para quien lo referencia, y la geocodificación filtra por ese código sin necesitar un `join`. La contrapartida es que **no hay foránea**: como la unicidad de `paises.codigo` rige sólo entre las filas vigentes, la columna no es candidata a clave única contra la historia entera y MySQL 8.4 no admite una foránea hacia una columna así. La integridad la sostienen el caso de uso, la migración y el seeder —la misma concesión que ya hace `agencias.usuario_id` hacia `travia_auth`—, y un código huérfano cargado a mano se muestra igual, con el nombre en `null`. **Un paquete conserva el país que el catálogo retiró**: la vigencia sólo se exige a los países nuevos o cambiados, no a los que ya estaban guardados. ## Decisiones de modelado **El CUIT y el legajo se guardan normalizados.** Sin guiones ni espacios. Guardar `30-71234567-8` en una fila y `30712345678` en otra haría que el índice único no sirviera para nada: serían dos valores distintos para el mismo contribuyente. La normalización ocurre antes de validar, no después. **El CUIT es `char(11)`; el legajo EVT, `varchar(20)`.** La diferencia de tipo no es un detalle de estilo: es la misma decisión que explica por qué uno se valida y el otro no. - El CUIT **tiene** once dígitos, siempre, y el último es un verificador calculado por módulo 11. El ancho fijo es una propiedad del dato, y por eso `char(11)` es correcto: cualquier valor de otro largo está mal. - El legajo EVT sale de un registro **secuencial que sigue creciendo**. Hoy mide cinco dígitos, pero eso es una observación del presente, no una regla del dominio. `varchar(20)` deja lugar para que crezca —y para un eventual cambio de numeración— sin tocar la base. **El ancho de la columna acompaña a la validación.** Una regla de formato que se quitara de PHP sin ensanchar la columna **movería el rechazo a MySQL, que es el peor lugar posible para enterarse**: un legajo de seis dígitos dejaría de dar un 422 con un mensaje en castellano para dar un error del motor a mitad de una escritura que además cruza dos esquemas. **El ancho de la columna y el del objeto de valor no se escriben dos veces.** `LegajoEvt::LARGO_MAXIMO` vale 20 y el Form Request arma su regla `max:` a partir de esa constante. Si mañana la columna cambia, hay un solo número que mover; si estuvieran duplicados, la validación y la base se separarían sin ruido y el síntoma aparecería en producción. **`cupos_disponibles` es una columna, no un cálculo.** Derivarlo contando órdenes en cada consulta de catálogo sería costoso y, peor, no se podría bloquear con `SELECT ... FOR UPDATE`. Se mantiene como contador y se protege con la transacción de compra. Son **dos** columnas y no una —`totales` y `disponibles`— porque con una sola el paquete perdería cuántos lugares tenía al empezar, y con eso se van el «quedan 3 de 20», el cuánto se vendió y la posibilidad de devolver un lugar cancelado sin pasarse del total. Al publicar arrancan iguales; después se separan solas. Las dos son `unsigned`: el dominio ya impide un cupo negativo en `Cupo`, y el motor lo vuelve a impedir, que es lo que se quiere cuando la reserva descuenta de a uno dentro de una transacción. **`referencia_externa` es única en `PAGO`.** Es lo que hace idempotente el webhook: si Mercado Pago entrega dos veces el mismo evento, el segundo intento choca contra el índice único y se descarta sin efecto. **`eliminado_en` en lugar de borrado físico.** Habilita el deshacer y la papelera de 30 días. Un paquete eliminado sigue existiendo para las órdenes históricas que lo referencian, que de otro modo quedarían huérfanas. En las tablas la columna se llama `deleted_at`, que es el nombre que espera Eloquent; el diagrama usa el nombre conceptual. **La baja lógica no reserva ningún valor**: donde hay unicidad, rige sólo entre las filas vigentes, con un índice único sobre una columna generada que se anula al dar de baja la fila. Así el motor sigue teniendo la última palabra sin que una baja bloquee un CUIT o un nombre para siempre. **Una reseña por orden, no por paquete.** El índice único sobre `orden_id` garantiza que solo califique quien compró, y una sola vez por compra. **Latitud y longitud en agencia y en paquete.** Se guardan las coordenadas ya resueltas en lugar de geocodificar en cada búsqueda: el proveedor de geocoding tiene límites de uso y la búsqueda por cercanía necesita calcular distancias sobre miles de filas. En `paquetes` las dos columnas **nacen nulas**, porque las completa la geocodificación, que corre aparte: publicar no puede quedar atado a que un servicio externo responda. **El saldo de la agencia no existe como columna.** Se deriva de la suma de sus asientos. Un saldo almacenado se desincroniza en cuanto una operación falla a mitad de camino; una suma de asientos, no.