Promotions — Decisiones de Diseño y Arquitectura Simplificada v4

Propósito: explicar de forma simple las decisiones principales de diseño para Promotions, incluyendo runtime cloud y runtime on-premise.
Alcance: v1 enfocada en VTQA para cloud/conectados y despliegue BAP on-premise desde VT-FULL.
Fuera de alcance inicial: VTPROD, reemplazo total de Jenkins, cancelación de ejecuciones, links efímeros, sincronización automática on-premise -> Veritran, runners genéricos y rollback equivalente a VT Wizard.

1. ¿Qué problema queremos resolver?

Hay dos realidades operativas:

Clientes conectados
- Se preparan carpetas y archivos en Nextcloud.
- Se dispara Jenkins.
- Jenkins genera VT-FULL y/o ejecuta en ambientes accesibles.
Clientes on-premise / bancarios aislados
- Veritran genera un VT-FULL.
- El cliente lo recibe por un canal aprobado.
- Dentro del banco se ejecuta con VT Wizard.
- VT Wizard, entre otras cosas, toma el BAP y bapProps y los envía al componente que hoy conocemos como BAP Deployer.
- BAP Deployer hace el despliegue real del BAP dentro del cliente.

Problemas actuales:

Mucho trabajo manual en Nextcloud.
Jenkins funciona como interfaz operativa.
No hay UI local enfocada en despliegue BAP on-premise.
La trazabilidad queda dispersa entre Jenkins, archivos, VT Wizard y logs locales.
El rollback hoy lo cubre VT Wizard, y no queremos perder esa capacidad sin diseñar una alternativa.

La iniciativa Promotions ordena esto con dos runtimes:

Promotions Cloud Runtime
Promotions On-Premise Runtime

Ambos se conectan por el contrato portable:

VT-FULL-<IMPLENAME>.tar.gz

2. ¿Qué es Promotions?

Promotions es una iniciativa para orquestar implementaciones de forma controlada.

No es solo una pantalla cloud. Tendrá dos runtimes:

1. Promotions Cloud / Veritran-side
   - corre dentro de Workspace del lado Veritran
   - integra BAR, Nextcloud y Jenkins
   - crea implementación
   - genera VT-FULL
   - ejecuta en clientes conectados
   - permite descargar VT-FULL

2. Promotions On-Premise
   - corre dentro del banco, instalado por ambiente
   - incluye UI propia
   - incluye backend on-premise propio
   - el backend actual/provisional es BAP Deployer
   - incluye DB SQL local
   - importa VT-FULL
   - extrae BAP + bapProps
   - permite revisar BAP
   - permite ajustar variables de entorno de bapProps
   - despliega localmente
   - guarda historial local

3. Diagrama general

[Diagram]

Decisiones de diseño

4. ¿Por qué hay dos runtimes?

Porque los clientes conectados y on-premise tienen restricciones distintas.

En clientes conectados, Promotions puede orquestar:

BAR -> Nextcloud -> Jenkins -> VTQA

En on-premise, asumimos aislamiento bancario:

sin entrada desde Veritran
sin salida confiable a internet
infraestructura cerrada

Decisión: Promotions tendrá dos runtimes unidos por VT-FULL.

5. ¿Qué une cloud y on-premise?

El paquete portable:

VT-FULL-<IMPLENAME>.tar.gz

Decisión: VT-FULL es la frontera entre ambos mundos.

Cloud Runtime no necesita entrar al banco.
On-Premise Runtime no necesita salir a Veritran.

6. ¿Por qué crear Promotions Cloud si ya existe Jenkins?

Porque Jenkins debe ser backend técnico, no la experiencia principal.

Decisión: Promotions Cloud será la interfaz de orquestación. Jenkins queda como motor técnico.

[Diagram]

7. ¿Por qué desacoplar Jenkins en dos jobs?

Porque generar y ejecutar son responsabilidades distintas.

Nuevo modelo:

Generate VT-FULL Job
  -> toma carpeta fuente
  -> genera VT-FULL

Execute VT-FULL Job
  -> toma VT-FULL ya generado
  -> ejecuta ese paquete

Decisión: la ejecución debe apuntar a un paquete ya generado.

[Diagram]

8. ¿Qué automatiza Promotions Cloud?

Crear carpeta de implementación.
Generar paquete VT-FULL.
Ejecutar paquete solo para clientes conectados.

[Diagram]

9. ¿De dónde sale el BAP en Promotions Cloud?

Desde BAR.

BAR devuelve:

BAP .tar.gz
bapProps

Promotions Cloud copia ambos a:

<CLIENTE>/VTQA-PACKAGES/<IMPLENAME>/IMPLE_VTNET_OBJECTS/

El usuario solo puede editar steps2run.vt.

10. ¿Qué es Promotions On-Premise?

Es la variante local de Promotions que corre dentro del banco.

Incluye:

Promotions On-Premise UI
Promotions On-Premise Backend
  actual/provisional: BAP Deployer
DB SQL local
  implementación inicial: SQLite
  diseño conceptual: agnóstico al motor

Decisión: el componente que hoy llamamos BAP Deployer debe entenderse como el backend de Promotions On-Premise, aunque probablemente se renombre.

11. ¿Promotions On-Premise ya existe en todos los ambientes?

No necesariamente.

Nueva premisa:

Promotions On-Premise se instalará por ambiente.

Cada ambiente tendrá su propia instancia:

Ambiente A:
  UI + Backend + DB local

Ambiente B:
  UI + Backend + DB local

Esto implica:

Historial por ambiente.
Configuración por ambiente.
bapProps resuelto por ambiente.
Deploy local al ambiente donde está instalada la solución.

[Diagram]

12. ¿Qué problema resuelve Promotions On-Premise?

Permite desplegar solo el BAP con una UI local, sin pasar por todo VT Wizard.

Flujo:

Importar VT-FULL
Ver contenido BAP relevante
Ver overview del BAP
Editar variables de entorno de bapProps
Desplegar directo con Promotions On-Premise Backend
Guardar historial local

13. ¿Cómo funciona Promotions On-Premise?

[Diagram]

14. ¿Qué importa la UI on-premise?

Solo importa:

VT-FULL-<IMPLENAME>.tar.gz

No importa BAP suelto en v1.

Contenido relevante:

BAP .tar.gz
múltiples bapProps
manifest del BAP

15. ¿Cómo se selecciona el `bapProps` correcto?

El VT-FULL puede contener múltiples bapProps.

Promotions On-Premise Backend resolverá cuál corresponde según:

ambiente
variables de entorno locales
configuración runtime del ambiente

La UI mostrará el bapProps efectivo o la sección editable una vez resuelto.

16. ¿Qué parte de `bapProps` edita el usuario?

Solo la sección de variables de entorno, como formulario:

clave: valor

No habrá editor JSON libre.

[Diagram]

17. ¿El `VT-FULL` se modifica?

No.

El artefacto importado es inmutable.

Se guarda:

Hash del VT-FULL.
Hash del BAP.
Hash del bapProps original.
Variables modificadas.
effective bapProps.
Resultado y logs.

18. ¿Cómo se guarda historial on-premise?

En DB SQL local por ambiente.

Diseño:

Agnóstico al motor SQL.
Implementación inicial: SQLite.

Mínimo recomendado:

packageName
packageHash
bapName
bapVersion
bapHash
selectedBapProps
effectiveBapPropsHash
modifiedEnvVars
status
startedAt
finishedAt
deployedBy
logs
resultSummary
rollbackMetadata, si se define estrategia futura

19. ¿Qué pasa con rollback?

Este es un punto crítico.

VT Wizard actualmente cubre rollback. Si Promotions On-Premise despliega directamente, no debemos perder esa capacidad a largo plazo.

Decisión v1: rollback equivalente a VT Wizard queda fuera de alcance inicial, salvo decisión explícita.

Implicación: Promotions On-Premise puede aportar valor para despliegues BAP directos, pero no debe presentarse como reemplazo completo de VT Wizard en escenarios donde rollback robusto sea obligatorio.

Capacidad deseada a futuro

[Diagram]

20. ¿Cómo se autentica el usuario on-premise?

La UI on-premise vive dentro de Workspace on-premise.

Permisos sugeridos:

promotion-onprem:view
promotion-onprem:import-package
promotion-onprem:edit-env-vars
promotion-onprem:deploy
promotion-onprem:view-history
promotion-onprem:view-logs

21. ¿Cómo se distribuye Promotions On-Premise?

Como solución instalable por ambiente.

Incluye:

Promotions On-Premise UI
Promotions On-Premise Backend
  actual/provisional: BAP Deployer
DB SQL local
  SQLite inicial

No asumimos que BAP Deployer ya existe en todos los ambientes.

22. Decisiones resumidas

Pregunta	Decisión
¿Promotions es solo cloud?	No. Tiene runtime cloud y runtime on-premise.
¿Qué une ambos mundos?	`VT-FULL-<IMPLENAME>.tar.gz`.
¿Dónde vive Promotions Cloud?	En Workspace/Veritran-side.
¿Dónde vive Promotions On-Premise?	Dentro del banco, instalado por ambiente.
¿Qué incluye On-Premise?	UI + Backend + DB SQL local.
¿Cómo se llama el backend on-premise hoy?	BAP Deployer, pero probablemente será renombrado.
¿DB local?	SQL agnóstica; implementación inicial SQLite.
¿Se reemplaza Jenkins?	No en v1.
¿Cuántos jobs Jenkins nuevos habrá?	Dos: `Generate VT-FULL` y `Execute VT-FULL`.
¿Qué edita el usuario cloud?	Solo `steps2run.vt`.
¿Qué importa on-premise?	Solo `VT-FULL`.
¿Qué edita el usuario on-premise?	Variables de entorno dentro de `bapProps`.
¿Se modifica el artefacto original?	No, se trata como inmutable.
¿Cómo despliega on-premise?	Directo contra Promotions On-Premise Backend.
¿Dónde queda historial on-premise?	DB SQL local por ambiente.
¿Rollback?	Pendiente crítico; fuera de alcance v1 salvo decisión explícita.
¿Integridad/firma?	Mejora recomendada; mínimo hashes si es viable.

23. Pendientes relevantes

Definir estándar oficial de IMPLENAME.
Definir nombres finales de los jobs/scripts Jenkins cloud.
Definir contrato exacto de Generate VT-FULL Job.
Definir contrato exacto de Execute VT-FULL Job.
Confirmar input principal del job de ejecución: packagePath, packageName + repoClient, etc.
Definir naming final de BAP Deployer / Promotions On-Premise Backend.
Definir packaging e instalación por ambiente.
Definir schema de DB SQL local.
Confirmar SQLite como motor inicial.
Definir endpoints internos para import/inspect/deploy/history.
Confirmar si on-premise usará SSE o polling para progreso.
Confirmar estructura exacta de variables de entorno dentro de bapProps.
Confirmar resultado estructurado del backend on-premise.
Diseñar estrategia de rollback equivalente o complementaria a VT Wizard.
Definir metadata mínima a guardar desde v1 para habilitar rollback futuro.
Definir si ciertos despliegues deben seguir usando VT Wizard hasta resolver rollback.
Definir si se calcularán hashes SHA-256 en v1.
Definir cuándo incorporar VTPROD.

24. Conclusión

Promotions tiene dos modos de operación:

Promotions Cloud Runtime
Promotions On-Premise Runtime

El runtime cloud automatiza creación, empaquetado y ejecución para clientes conectados.

El runtime on-premise vive dentro del banco, instalado por ambiente, e incluye UI, backend y DB SQL local. El backend actual/provisional es BAP Deployer, pero conceptualmente será el backend de Promotions On-Premise y probablemente será renombrado.

El contrato entre ambos mundos es:

VT-FULL-<IMPLENAME>.tar.gz

La arquitectura mejora la experiencia cloud y on-premise sin romper el aislamiento bancario, dejando claro que rollback equivalente a VT Wizard queda como pendiente crítico antes de reemplazar completamente ese flujo.

Promotions — Decisiones de Diseño y Arquitectura Simplificada v4

1. ¿Qué problema queremos resolver?

2. ¿Qué es Promotions?

3. Diagrama general

Decisiones de diseño

4. ¿Por qué hay dos runtimes?

5. ¿Qué une cloud y on-premise?

6. ¿Por qué crear Promotions Cloud si ya existe Jenkins?

7. ¿Por qué desacoplar Jenkins en dos jobs?

8. ¿Qué automatiza Promotions Cloud?

9. ¿De dónde sale el BAP en Promotions Cloud?

10. ¿Qué es Promotions On-Premise?

11. ¿Promotions On-Premise ya existe en todos los ambientes?

12. ¿Qué problema resuelve Promotions On-Premise?

13. ¿Cómo funciona Promotions On-Premise?

14. ¿Qué importa la UI on-premise?

15. ¿Cómo se selecciona el bapProps correcto?

16. ¿Qué parte de bapProps edita el usuario?

17. ¿El VT-FULL se modifica?

18. ¿Cómo se guarda historial on-premise?

19. ¿Qué pasa con rollback?

Capacidad deseada a futuro

20. ¿Cómo se autentica el usuario on-premise?

21. ¿Cómo se distribuye Promotions On-Premise?

22. Decisiones resumidas

23. Pendientes relevantes

24. Conclusión

15. ¿Cómo se selecciona el `bapProps` correcto?

16. ¿Qué parte de `bapProps` edita el usuario?

17. ¿El `VT-FULL` se modifica?