Aurora Office

1Qué es

Un switch de pagos se administra, no solo se despliega. Hay que dar de alta un banco, decidir qué pasos corren para su tráfico, mapear sus campos, probar el flujo antes de encenderlo, certificarlo y dejar constancia de quién aprobó qué. Todo eso se puede hacer con curl y un fichero YAML; Aurora Office existe para que no haga falta.

Office es la consola de Switch Aurora. Lo que ofrece, en una frase por cosa:

Función	Qué resuelve
Lista y ficha de interconexión	Ver de un golpe qué contrapartes hay, en qué versión, activas o en borrador, y con qué resultado de certificación.
Flujo dibujado	El diagrama del recorrido de la transacción y del mapeo de campos, generado en el servidor, con el estado de cada paso. Se puede descargar.
Editor guiado	Un asistente por pasos que produce la plantilla. El YAML se muestra, pero se lee: no se escribe.
Simular	Ver qué pasos correrían y a qué nodo saldría un mensaje, antes de activar nada. Es requisito: no se puede pedir la activación de una versión que no se simuló.
Publicar con cuatro ojos	Quien solicita no aprueba. El switch se llama solo cuando un segundo usuario aprueba.
Informe de certificación	Las corridas y su matriz caso a caso con evidencia, que es lo que se le entrega a un banco.
Reglas de ruteo	Alta, orden real de evaluación y simulación del ruteo, con el veredicto explicado por hechos y no por un sí o un no.

2Arquitectura

La regla que ordena todo lo demás

Office nunca escribe en la base de datos del switch. Toda mutación viaja por los endpoints /admin con un token de alcance, exactamente igual que si la hiciera un script. El switch es la fuente de verdad y Office se alinea a lo que está desplegado.

No es purismo: es lo que permite que la consola se actualice sin coordinar una migración, que dos consolas no se pisen, y que cualquier cambio quede en la auditoría del switch con el cliente que lo pidió. La base propia de Office guarda lo suyo —usuarios, solicitudes de publicación, preferencias—, no una copia del modelo del switch.

Piezas

SwitchAdminClient      el único camino hacia el switch, con su token de alcance
PlantillaYamlService   valida la plantilla en local y señala la ruta del campo que falla
FlujoDiagrama          dibuja el SVG en el servidor: sin JavaScript de terceros
PublicacionCuatroOjos  solicitud -> aprobación de otro usuario -> llamada al switch

El diagrama se genera en el servidor a propósito. Un SVG servido es imprimible, se puede adjuntar a un correo y no depende de que una librería siga existiendo el año que viene.

Validar dos veces, y que se note

La plantilla se valida en Office antes de enviarla, y el switch la valida otra vez al recibirla. La primera validación es cortesía —dice el error señalando el campo, sin ir y volver—; la segunda es la que manda. Si alguna vez discrepan, gana el switch, y eso es deliberado.

3Instalación y despliegue

Variables del contenedor

Variable	Obligatoria	Para qué
`MAIN_DATASOURCE_URL`	sí	Base de datos propia de Office.
`AURORA_OFFICE_SWITCH_BASE_URL`	sí	Dónde está el switch, por la red interna.
`AURORA_OFFICE_ADMIN_PASSWORD`	sí	Clave del usuario de arranque. Sin ella, el arranque aborta.
`AURORA_OFFICE_ADMIN_USERNAME`	no	Nombre del usuario de arranque; por defecto `admin`.

Por qué la clave no está en el repositorio

La cuenta de arranque no trae clave de fábrica. Un despliegue anterior la tenía en claro en un changeset, y eso tiene tres problemas: es la misma en todos los despliegues, queda en la historia del repositorio para siempre —atacable sin prisa y sin dejar rastro— y rotarla exige una migración.

Ahora la clave viene del entorno, se guarda cifrada al arrancar y el comportamiento es fail closed: si la variable no está y la cuenta no tiene todavía una clave propia, la aplicación no levanta y dice por qué. Rotar es reiniciar con otro valor.

Aviso para el primer redespliegue. La clave de fábrica se revoca al aplicar el changelog. Si el contenedor arranca sin AURORA_OFFICE_ADMIN_PASSWORD, no levanta y la cuenta queda sin clave utilizable hasta que se reinicie con la variable definida. Es recuperable, pero es un reinicio perdido.

Token del switch

Office necesita un token con los alcances de lo que vaya a hacer: READ para consultar, NODES_WRITE para operar enlaces, RULES_WRITE para activar interconexiones y disparar certificaciones. Conviene un token propio de Office y no el de otro sistema: la auditoría del switch registra el cliente, y un token compartido convierte esa auditoría en ruido.

4Operación diaria

Encender una contraparte nueva, de principio a fin

Importar o construir la plantilla: subir el YAML que mandó el banco, pegarlo, o levantarla con el asistente.
Revisar el flujo dibujado: qué pasos corren, qué campos se mapean y hacia qué nodo sale.
Simular con un mensaje de prueba. Sin este paso la versión no se puede proponer para activación.
Certificar contra el simulador y leer el informe. Los casos omitidos importan tanto como los aprobados: cada uno dice su causa.
Solicitar la publicación. Otro usuario aprueba; ahí, y solo ahí, Office llama al switch.

Roles

Dos roles de base: uno que puede mirar todo y simular, y otro que además puede solicitar y aprobar publicaciones. La separación no es decorativa: es lo que sostiene los cuatro ojos.

5API e integraciones

Office no publica API propia: es un cliente. Consume del switch las rutas de interconexiones, certificaciones y reglas de ruteo, con la cabecera X-Aurora-Admin-Token.

Dos detalles que importan al integrar, porque son las dos cosas que se rompen primero cuando el switch cambia:

Fechas: Office espera ISO-8601 con zona. Una fecha sin zona no se puede ordenar bien entre dos corridas hechas a la misma hora en husos distintos, y un informe firmado con una hora que no ocurrió no vale nada.
Nombres de paso: los que devuelve la simulación tienen que coincidir con los del catálogo de tuberías, o el diagrama dibuja un paso que no existe.

6Runbooks

El arranque aborta por la clave

Es el comportamiento esperado, no un fallo. Definir AURORA_OFFICE_ADMIN_PASSWORD en el entorno del contenedor y reiniciar. La clave debe tener al menos doce caracteres y no puede ser igual al nombre de usuario.

Office no ve al switch

Comprobar en este orden: que AURORA_OFFICE_SWITCH_BASE_URL apunte al nombre interno y no al público; que el token no esté revocado; y que tenga el alcance de lo que se está intentando. Un token sin alcance responde con un error explícito, no con una pantalla vacía.

Una activación no llega al switch

Revisar si quedó en solicitud pendiente de aprobación. Por diseño, una solicitud sin segundo par de ojos no llama al switch, y eso puede parecer una llamada perdida cuando en realidad es el control funcionando.

7Preguntas frecuentes

¿Por qué no edita la base del switch directamente, que sería más simple?

Porque sería más simple hoy y más caro siempre. Escribiendo por la API, la consola no se acopla al esquema, no hay que desplegar las dos cosas a la vez, dos consolas no se pisan y cada cambio queda en la auditoría con el cliente que lo pidió. Escribiendo en la base, el primer cambio de columna rompe la consola en silencio.

¿Se puede administrar el switch sin Office?

Sí. Todo lo que hace Office son llamadas HTTP documentadas, y hay una interfaz de línea de comandos para correr la certificación sin levantar nada. Office no es una capa obligatoria: es la que evita el error humano de escribir un YAML a mano delante de un banco.

¿Está publicado en internet?

Se sirve tras el proxy inverso, con certificado, y no se publica un entorno cuya cuenta de arranque no tenga clave propia definida. La consola de un switch de pagos no es una página que se deja abierta.