Documento de Arquitectura — Promotions To-Be Inicial

Estado: Borrador
Versión: v1
Ámbito: Arquitectura propuesta inicial para automatizar el flujo manual de implementaciones VTQA
Sistema: Promotions dentro de Workspace
Backend de ejecución: Jenkins como caja negra, mediante jobs/scripts específicos para Promotions
Storage actual: repo.veritran.com / Nextcloud hospedado por Veritran
Origen de BAP: BAR — BAP Application Repository
Alcance inicial: VTQA
Fuera de alcance inicial: VTPROD, cancelación de ejecuciones, links efímeros, reemplazo de Jenkins

1. Resumen Ejecutivo

Promotions será una nueva capacidad dentro de Workspace para automatizar y gobernar el flujo de implementaciones que hoy se realiza de forma manual sobre Nextcloud y Jenkins.

El objetivo de v1 es reducir la intervención manual del usuario en la creación de carpetas, preparación de artefactos, edición de steps2run.vt, generación del paquete final y ejecución opcional en ambientes accesibles por Veritran.

En lugar de que el usuario entre manualmente a repo.veritran.com, cree carpetas, suba archivos y luego ejecute Jenkins, Promotions centralizará el flujo desde una UI propia:

Seleccionar un BAP desde BAR.
Crear una carpeta de implementación en Nextcloud.
Copiar el BAP y bapProps dentro de IMPLE_VTNET_OBJECTS.
Generar o permitir editar steps2run.vt.
Disparar un job/script específico de Jenkins para generar el paquete VT-FULL-<IMPLENAME>.tar.gz.
Consultar el estado del job de generación.
Permitir descarga del paquete final.
Disparar un job/script específico de Jenkins para ejecutar un VT-FULL ya generado cuando el cliente permita ejecución remota.
Mostrar progreso casi realtime usando SSE.

Jenkins no será modelado internamente por Promotions. Para esta arquitectura, Jenkins queda encapsulado como un execution backend. Promotions solo conocerá qué job invocar, con qué parámetros, cómo consultar estado, cómo leer logs y cómo resolver el paquete generado.

Una decisión clave acordada con el equipo de Jenkins/BT Wizard es desacoplar el flujo legacy run_implementation en dos capacidades específicas para Promotions:

Generate VT-FULL Job
Execute VT-FULL Job

Esto evita que la ejecución vuelva a generar el paquete y permite que cada deployment apunte a un VT-FULL concreto, previamente generado y trazable.

2. Objetivos

2.1 Objetivos Funcionales

Promotions v1 deberá permitir:

Listar implementaciones y su estado.
Crear una nueva implementación a partir de un BAP obtenido desde BAR.
Crear automáticamente la estructura estándar en Nextcloud.
Copiar físicamente el BAP y bapProps dentro de IMPLE_VTNET_OBJECTS.
Generar un steps2run.vt inicial.
Permitir edición controlada de steps2run.vt desde la UI.
Crear un paquete de implementación final mediante un job/script específico de Jenkins.
Mostrar el estado del empaquetado.
Permitir descargar el paquete generado.
Ejecutar un paquete ya generado mediante un job/script específico de Jenkins para clientes con ejecución remota habilitada.
Mostrar progreso de ejecución casi realtime usando SSE.
Registrar eventos mínimos de auditoría.

2.2 Objetivos Técnicos

Encapsular acceso a Nextcloud detrás de un adapter.
Encapsular Jenkins detrás de un adapter.
Encapsular BAR detrás de un adapter.
Mantener Jenkins como caja negra en v1.
Usar jobs/scripts específicos para Promotions, en lugar de depender del comportamiento acoplado del pipeline legacy.
Separar generación de paquete y ejecución.
Usar metadata configurable por cliente en base de datos.
Obtener parámetros dinámicos desde Jenkins cuando sea posible.
Usar metadata JSON como fallback cuando Jenkins no exponga suficiente información.
Mantener el paquete VT-FULL-<IMPLENAME>.tar.gz como contrato portable.
Integrarse con Workspace para autenticación y autorización.

2.3 Objetivos de Producto

Evitar que usuarios operativos creen carpetas manualmente en Nextcloud.
Reducir errores por nombres incorrectos, archivos faltantes o estructuras inválidas.
Proveer una experiencia guiada y trazable.
Separar claramente:
- creación de carpeta de implementación,
- creación de paquete,
- ejecución de implementación,
- descarga para entrega manual/on-premise.
Permitir futura evolución hacia runners customer-hosted o reemplazo de Jenkins sin rehacer la experiencia de usuario.

3. No Objetivos / Fuera de Alcance v1

La primera versión no busca:

Reemplazar Jenkins.
Reimplementar internamente la lógica de vt-wizard o BT Wizard.
Soportar publicación hacia VTPROD-PACKAGES.
Implementar cancelación o abort de builds Jenkins.
Generar links efímeros propios para descarga.
Permitir subida arbitraria de archivos desde la UI.
Permitir edición de bapProps.
Permitir edición manual del BAP.
Resolver definitivamente la convención de nombres IMPLENAME, aunque se recomienda estandarizarla.
Soportar múltiples environments más allá de VTQA.
Garantizar parsing perfecto de logs desde el día uno si Jenkins/vt-wizard no entrega salida estructurada.
Usar el pipeline legacy como contrato final de Promotions si este vuelve a generar el paquete durante la ejecución.

4. Principios de Diseño

4.1 Jenkins como Caja Negra

Promotions no debe depender de detalles internos del Jenkinsfile.

Debe conocer:

Qué job ejecutar.
Qué parámetros enviar.
Cómo obtener el build ID / build URL.
Cómo consultar estado.
Cómo leer logs o eventos.
Cómo interpretar resultado final.
Dónde queda publicado el paquete final.

No debe modelar internamente cada stage del pipeline.

4.2 Separación entre Packaging y Execution

Generar un paquete y ejecutar un paquete son responsabilidades distintas.

El flujo legacy podía generar el VT-FULL y, al ejecutar, volver a generarlo. Esto no es ideal porque:

Duplica trabajo.
Dificulta asegurar qué paquete exacto fue ejecutado.
Mezcla responsabilidades.
Complica la trazabilidad.

Promotions v1 debe usar dos capacidades distintas:

Generate VT-FULL Job
Execute VT-FULL Job

4.3 Separación entre Dominio y Backend Técnico

Promotions debe exponer conceptos de negocio:

Implementación.
Carpeta de implementación.
Paquete de implementación.
Ejecución.
Descarga.
Auditoría.

Jenkins debe verse como una dependencia técnica, no como el modelo de dominio.

4.4 Portabilidad del Paquete

El paquete final VT-FULL-<IMPLENAME>.tar.gz debe seguir siendo el contrato portable entre Veritran y los ambientes destino.

Debe poder usarse para:

Ejecución automatizada desde Jenkins.
Descarga y entrega manual a cliente on-premise.
Potencial ejecución futura desde un runner customer-hosted.

4.5 Automatizar lo Manual sin Romper el Flujo Actual

La arquitectura v1 debe automatizar la preparación manual actual, pero sin exigir cambios profundos en Jenkins ni en vt-wizard.

4.6 Evolución por Adapters

Las integraciones deben encapsularse detrás de adapters:

BARAdapter
NextcloudAdapter
JenkinsAdapter
WorkspaceAuthAdapter

Esto permite reemplazar o evolucionar partes sin impactar el dominio principal.

4.7 Auditoría desde el Inicio

Toda operación relevante debe emitir eventos de auditoría.

La auditoría no debe depender únicamente de logs Jenkins.

5. Arquitectura de Alto Nivel

[Diagram]

34. Cambio Relevante: Jobs Específicos para Promotions

6.1 Situación Legacy

El flujo legacy run_implementation podía operar de esta forma:

EJECUTAR=false
  -> generar VT-FULL

EJECUTAR=true
  -> generar VT-FULL
  -> ejecutar

Eso significa que, si Promotions primero generaba un paquete y luego ejecutaba, la ejecución podía volver a generar el VT-FULL.

6.2 Nuevo Modelo

Se acuerda crear dos scripts/jobs nuevos para uso de Promotions:

Generate VT-FULL Job
Execute VT-FULL Job

6.3 Beneficios

El paquete se genera una sola vez.
La ejecución apunta a un paquete ya generado.
Se puede auditar exactamente qué paquete fue ejecutado.
Se desacopla packaging de execution.
La interfaz de parámetros de Jenkins queda más limpia.
Promotions no queda atado al comportamiento legacy de run_implementation.

6.4 Diagrama

[Diagram]

34. Componentes Principales

6.1 Promotions UI

Interfaz de usuario dentro de Workspace.

Responsabilidades:

Mostrar listado de implementaciones.
Permitir creación de implementación desde un BAP.
Permitir selección de ambiente y nodo.
Mostrar estructura esperada de carpeta.
Permitir edición de steps2run.vt.
Permitir generar paquete.
Permitir ejecutar paquete cuando aplique.
Mostrar progreso casi realtime.
Mostrar logs o link a logs.
Mostrar descarga del paquete final.
Mostrar resultado estructurado si está disponible.

La UI debe ocultar acciones no permitidas según permisos y metadata del cliente.

Ejemplo:

Cliente conectado:
- Crear carpeta.
- Generar paquete.
- Ejecutar paquete.
- Descargar.
Cliente on-premise:
- Crear carpeta.
- Generar paquete.
- Descargar.
- No mostrar ejecución remota.

6.2 Promotions Backend/API

Servicio principal de dominio.

Responsabilidades:

Orquestar flujos de implementación.
Persistir metadata y estados.
Validar permisos.
Invocar BAR.
Invocar Nextcloud.
Invocar Jenkins.
Emitir eventos SSE.
Registrar auditoría.
Resolver links de descarga.
Exponer APIs para UI.

El backend debe contener el modelo de dominio. Jenkins, Nextcloud y BAR son dependencias externas.

6.3 Promotions DB

Base de datos agnóstica a tecnología en v1.

Responsabilidades:

Guardar implementaciones.
Guardar paquetes.
Guardar ejecuciones.
Guardar metadata de clientes.
Guardar configuración de integración por cliente.
Guardar estados.
Guardar eventos de auditoría.
Guardar referencias a Jenkins builds.
Guardar rutas de Nextcloud.
Guardar contenido actual o versión de steps2run.vt.
Guardar relación entre package generado y deployment ejecutado.

La tecnología específica queda fuera del alcance de esta versión del documento.

6.4 BAR Adapter

Adapter para consumir BAR — BAP Application Repository.

Premisa v1:

BAR devuelve:

BAP como .tar.gz.
Archivo bapProps.

Responsabilidades:

Obtener metadata del BAP.
Descargar el artefacto BAP.
Descargar bapProps.
Exponer una interfaz interna estable hacia Promotions.

Interfaz conceptual:

BARAdapter
  - getBap(bapId): BapMetadata
  - downloadBapArtifact(bapId): BinaryArtifact
  - downloadBapProps(bapId): BinaryArtifact

6.5 Nextcloud Adapter

Adapter para interactuar con repo.veritran.com.

Responsabilidades:

Crear carpetas.
Verificar existencia de paths.
Subir BAP a IMPLE_VTNET_OBJECTS.
Subir bapProps a IMPLE_VTNET_OBJECTS.
Escribir steps2run.vt.
Leer steps2run.vt.
Actualizar steps2run.vt.
Listar archivos generados.
Resolver ruta del paquete final.
Resolver link de descarga v1 hacia Nextcloud.

Interfaz conceptual:

NextcloudAdapter
  - createFolder(path)
  - uploadFile(path, file)
  - writeFile(path, content)
  - readFile(path)
  - updateFile(path, content)
  - listFiles(path)
  - exists(path)
  - getDownloadLink(path)

En v1, la descarga puede resolverse mediante link directo de Nextcloud.

A futuro, Promotions puede generar links efímeros, proxy de descarga o signed URLs.

6.6 Jenkins Adapter

Adapter para invocar Jenkins como caja negra.

Responsabilidades:

Disparar generación de VT-FULL.
Disparar ejecución de un VT-FULL ya generado.
Consultar estado de builds.
Consultar logs.
Obtener URL de build.
Obtener resultado.
Exponer eventos para SSE.
Intentar extraer parámetros dinámicos del job Jenkins.
Fallback a metadata JSON cuando Jenkins no exponga parámetros.

Interfaz conceptual:

JenkinsAdapter
  - triggerFullPackageGeneration(params): JenkinsBuildRef
  - triggerFullPackageExecution(params): JenkinsBuildRef
  - getBuildStatus(buildRef): BuildStatus
  - getBuildLogs(buildRef, cursor): LogChunk
  - getBuildUrl(buildRef): URL
  - getBuildResult(buildRef): BuildResult
  - getJobParameters(jobRef): JenkinsParameterSet

Promotions debe usar getJobParameters como POC para extraer choices dinámicos, por ejemplo nodos. Si no es viable o suficiente, usará metadata JSON por cliente.

6.7 SSE Event Stream

Canal de actualización casi realtime desde Promotions hacia la UI.

Decisión v1:

Promotions hace polling contra Jenkins.
Promotions transforma estado/logs en eventos.
Promotions emite eventos SSE hacia la UI.
La UI no consulta Jenkins directamente.

Responsabilidades:

Emitir estado de packaging.
Emitir estado de deployment.
Emitir pasos de progreso.
Emitir logs incrementales si se decide mostrar logs inline.
Emitir resultado final.
Emitir errores.

Eventos conceptuales:

package.queued
package.running
package.log
package.succeeded
package.failed

deployment.queued
deployment.running
deployment.log
deployment.step.updated
deployment.succeeded
deployment.failed

6.8 Audit/Event Log

Registro persistente de eventos de dominio.

Responsabilidades:

Registrar acciones de usuario.
Registrar transiciones de estado.
Registrar cambios a steps2run.vt.
Registrar invocaciones a Jenkins.
Registrar generación de links de descarga.
Registrar resultados.
Soportar trazabilidad posterior.

Eventos mínimos v1:

implementation.created
implementation.folder_created
steps2run.updated
package.requested
package.started
package.succeeded
package.failed
deployment.requested
deployment.started
deployment.succeeded
deployment.failed
package.download_link_generated

34. Modelo de Dominio

7.1 Entidades Principales

[Diagram]

34. Metadata Configurable por Cliente

Como no toda la metadata existe de forma centralizada en otro sistema, Promotions guardará un JSON configurable por cliente.

Ejemplo conceptual:

{
  "repoClient": "VTPLATFORM",
  "repoBasePath": "VTPLATFORM",
  "vtqaPackagesPath": "VTQA-PACKAGES",
  "supportsRemoteExecution": true,
  "defaultEnvironment": "VTQA",
  "allowedEnvironments": ["VTQA"],
  "nodes": ["NDA1", "NDA2"],
  "jenkins": {
    "generateJobPath": "PROMOTIONS/generate_vt_full",
    "executeJobPath": "PROMOTIONS/execute_vt_full",
    "defaultComponent": "CORE"
  },
  "nextcloud": {
    "objectsFolderName": "IMPLE_VTNET_OBJECTS"
  }
}

Notas:

VTPLATFORM es solo un ejemplo de cliente/repositorio.
Pueden existir otros clientes con otros valores de repoClient.
Los nodos deben intentar obtenerse desde Jenkins si la POC lo permite.
Si no es posible, se tomarán desde este JSON.
El JSON debe ser editable solo por usuarios con permisos administrativos.

34. Permisos

Promotions estará dentro de Workspace, por lo que la autenticación y autorización se apoyarán en ese componente.

Se propone un modelo granular de permisos.

Permiso	Descripción
`promotion:view`	Ver listado y detalle de implementaciones.
`promotion:create-folder`	Crear carpeta de implementación en Nextcloud.
`promotion:edit-steps2run`	Editar `steps2run.vt`.
`promotion:create-package`	Disparar Jenkins para crear `VT-FULL`.
`promotion:execute`	Disparar ejecución remota en VTQA.
`promotion:download-package`	Generar/ver link de descarga del paquete final.
`promotion:manage-customer-config`	Administrar metadata JSON de clientes.
`promotion:view-logs`	Ver logs o link de logs asociados a Jenkins.

Roles sugeridos:

Rol	Permisos típicos
Viewer	`promotion:view`, `promotion:view-logs`
Operator	Viewer + `create-folder`, `edit-steps2run`, `create-package`, `download-package`
Executor	Operator + `execute`
Admin	Todos, incluyendo `manage-customer-config`

34. Estados

10.1 Estados de Implementation

DRAFT
CREATING_FOLDER
FOLDER_READY
FAILED

10.2 Estados de ImplementationPackage

PACKAGE_REQUESTED
PACKAGING
PACKAGE_READY
PACKAGE_FAILED

10.3 Estados de DeploymentExecution

DEPLOYMENT_REQUESTED
DEPLOYING
DEPLOYED
DEPLOYMENT_FAILED

10.4 Vista Unificada de Estado

Para simplificar la UI, Promotions puede exponer un estado agregado:

DRAFT
FOLDER_READY
PACKAGING
PACKAGE_READY
DEPLOYING
DEPLOYED
FAILED

10.5 Máquina de Estados General

[Diagram]

34. Flujo 1 — Crear Implementación desde BAP

11.1 Objetivo

Automatizar lo que hoy el usuario hace manualmente en Nextcloud:

Crear carpeta de implementación.
Crear IMPLE_VTNET_OBJECTS.
Copiar BAP.
Copiar bapProps.
Crear steps2run.vt.

11.2 Flujo

[Diagram]

11.3 Estructura Generada

<REPO_CLIENT>/
  VTQA-PACKAGES/
    <IMPLENAME>/
      IMPLE_VTNET_OBJECTS/
        steps2run.vt
        <bap-artifact>.tar.gz
        <bapProps-file>

Donde <REPO_CLIENT> puede ser VTPLATFORM u otro cliente configurado.

11.4 Generación Inicial de `steps2run.vt`

Formato:

<bap-artifact>.tar.gz:<NODE>

Ejemplo:

business-application-pruebas-baps-4.1.1-WebP2-03.tar.gz:NDA1

11.5 Edición de `steps2run.vt`

El usuario podrá editar únicamente steps2run.vt.

No podrá editar:

BAP.
bapProps.
Otros archivos internos.
Subir archivos arbitrarios.

Cada edición debe registrar evento:

steps2run.updated

Idealmente guardando:

Actor.
Timestamp.
Versión anterior o hash anterior.
Versión nueva o hash nuevo.
Implementation ID.

34. Flujo 2 — Generar Paquete de Implementación

12.1 Objetivo

Generar el paquete final portable:

VT-FULL-<IMPLENAME>.tar.gz

sin ejecutar la implementación.

12.2 Decisión

Generar paquete equivale a disparar Jenkins con:

EJECUTAR=false

12.3 Flujo

[Diagram]

12.4 Parámetros hacia Jenkins

Promotions deberá construir los parámetros requeridos por el job.

Conceptualmente:

IMPLENAME=<IMPLENAME>
CUSTOMER=<customer/repo client, según job>
NODE=<node seleccionado o requerido por Jenkins>
COMPONENTE=<component configurado o seleccionado>
EJECUTAR=false
GENERATEDOC=<según decisión/config>
TOKEN=<si aplica>
EXTRAFLAGS=<si aplica>
SKIP=<si aplica>
VTDBRUNIMPL=<si aplica>
ISZIP=<según estrategia>

El set exacto dependerá del contrato final definido con el equipo de Jenkins.

Promotions debe centralizar el mapeo en JenkinsAdapter, no dispersarlo en la UI.

34. Flujo 3 — Ejecutar Paquete

13.1 Objetivo

Ejecutar la implementación en VTQA para clientes con ejecución remota habilitada.

13.2 Regla de Disponibilidad

La acción de ejecutar solo debe estar disponible si:

customer.supportsRemoteExecution = true

Para clientes on-premise/desconectados, la UI no debe mostrar la acción o debe mostrarla deshabilitada.

13.3 Decisión

Ejecutar paquete equivale a disparar Jenkins con:

EJECUTAR=true

Actualmente se asume que Jenkins genera/prepara el paquete y ejecuta dentro del mismo flujo.

13.4 Flujo

[Diagram]

34. SSE y Seguimiento Realtime

14.1 Decisión v1

La estrategia será:

Promotions polling Jenkins -> Promotions SSE -> UI

La UI no consultará Jenkins directamente.

14.2 Motivos

Centraliza seguridad.
Evita exponer Jenkins a usuarios finales.
Permite normalizar eventos de negocio.
Permite parsear logs.
Permite cambiar Jenkins en el futuro sin cambiar la UI.

14.3 Ejemplo de Eventos SSE

event: deployment.step.updated
data: {
  "deploymentId": "DEP-20260511-1182",
  "step": "connecting_to_jenkins",
  "status": "completed"
}

event: deployment.log
data: {
  "deploymentId": "DEP-20260511-1182",
  "offset": 12048,
  "message": "Running VTWizard..."
}

event: deployment.succeeded
data: {
  "deploymentId": "DEP-20260511-1182",
  "summary": {
    "transactions": { "total": 242, "imported": 242, "skipped": 0 },
    "responseCodes": { "total": 87, "imported": 87, "skipped": 1 }
  }
}

34. Resultado Estructurado de Ejecución

La UI podrá mostrar un resumen estructurado si Jenkins/vt-wizard entrega información parseable desde logs o salida.

Ejemplo conceptual:

{
  "transactions": {
    "total": 242,
    "imported": 242,
    "skipped": 0
  },
  "responseCodes": {
    "total": 87,
    "imported": 87,
    "skipped": 1
  },
  "businessParameters": {
    "total": 121,
    "imported": 121,
    "skipped": 0
  },
  "configurationFiles": {
    "total": 5,
    "imported": 5,
    "skipped": 0
  }
}

Si la salida no es suficientemente estructurada, v1 debe degradar elegantemente a:

Estado final.
Link a logs.
Link de descarga del paquete.
Mensaje de error si aplica.

34. Flujo 4 — Descargar Paquete

16.1 Objetivo

Permitir que el usuario descargue el paquete final generado:

VT-FULL-<IMPLENAME>.tar.gz

16.2 Decisión v1

En v1, Promotions puede generar o devolver un link directo contra Nextcloud.

Evento de auditoría:

package.download_link_generated

16.3 Futuro

En versiones posteriores:

Link efímero generado por Promotions.
Proxy de descarga.
Signed URL.
Expiración configurable.
Auditoría de descarga efectiva.
Restricción por permiso granular.

34. Clientes On-Premise

17.1 Regla

Clientes on-premise o desconectados no tendrán acción de ejecución remota.

Flujo:

Crear implementación
Generar paquete
Descargar paquete
Entregar paquete al cliente
Cliente descomprime y ejecuta localmente

17.2 Diagrama

[Diagram]

34. Clientes con Ejecución Remota

18.1 Regla

Clientes con ejecución remota habilitada podrán:

Crear implementación.
Generar paquete.
Descargar paquete.
Ejecutar paquete en VTQA.

18.2 Diagrama

[Diagram]

34. Contrato con Nextcloud

19.1 Paths

El path base depende del cliente.

Ejemplo:

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

Ejemplo concreto visto previamente:

VTPLATFORM/VTQA-PACKAGES/IMPLE_WEB_P2_002/IMPLE_VTNET_OBJECTS

VTPLATFORM no es fijo globalmente; representa un cliente/repositorio y puede cambiar.

19.2 Operaciones v1

Promotions deberá soportar:

create implementation folder
create IMPLE_VTNET_OBJECTS
upload BAP .tar.gz
upload bapProps
write steps2run.vt
read steps2run.vt
update steps2run.vt
list files
resolve package path
resolve download link

34. Contrato con Jenkins

20.1 Jenkins como Execution Backend

Promotions usará Jenkins como caja negra.

Job inicial esperado:

Generate VT-FULL Job
Execute VT-FULL Job

20.2 Generar Paquete

EJECUTAR=false

Resultado esperado:

VT-FULL-<IMPLENAME>.tar.gz publicado en VTQA-PACKAGES

20.3 Ejecutar Paquete

Input conceptual:

Referencia al VT-FULL ya generado
Environment
Node
Component/configuration parameters
Runtime token/flags si aplican

Resultado esperado:

Implementación ejecutada en VTQA
Logs disponibles
Resultado parseable si es posible

20.4 Parámetros

Promotions debe construir los parámetros requeridos a partir de:

Implementation.
Customer metadata.
Environment.
Node.
Component.
Usuario.
Inputs opcionales.

Ejemplo conceptual para generación:

{
  "IMPLENAME": "IMPLE_WEB_P2_002",
  "REPO_CLIENT": "VTPLATFORM",
  "SOURCE_PATH": "VTPLATFORM/VTQA-PACKAGES/IMPLE_WEB_P2_002/IMPLE_VTNET_OBJECTS",
  "OUTPUT_PACKAGE": "VT-FULL-IMPLE_WEB_P2_002.tar.gz",
  "COMPONENTE": "CORE"
}

Ejemplo conceptual para ejecución:

{
  "PACKAGE_PATH": "VTPLATFORM/VTQA-PACKAGES/VT-FULL-IMPLE_WEB_P2_002.tar.gz",
  "REPO_CLIENT": "VTPLATFORM",
  "ENVIRONMENT": "VTQA",
  "NODE": "NDA1",
  "COMPONENTE": "CORE",
  "TOKEN": "...",
  "EXTRAFLAGS": ""
}

El mapeo exacto debe vivir en JenkinsAdapter.

34. POC de Parámetros Dinámicos Jenkins

Se realizará una POC para determinar qué puede extraerse desde Jenkins.

Objetivos de la POC:

Obtener listado de nodos disponibles.
Obtener choices de parámetros.
Obtener defaults.
Obtener metadata suficiente del job.
Evaluar si Jenkins expone esta información de forma estable.

Si la POC es exitosa:

Promotions obtiene opciones dinámicas desde Jenkins.

Si la POC no es suficiente:

Promotions usa metadata JSON configurable por cliente.

Arquitectura de fallback:

[Diagram]

34. Nombres de Implementación

La convención de IMPLENAME queda pendiente de estandarización.

Recomendación:

Evitar nombres que parezcan paquetes finales, por ejemplo VTFULL_*, para carpetas fuente.
Reservar VT-FULL-<IMPLENAME>.tar.gz para el paquete generado.
Incluir información suficiente para trazabilidad.
Evitar colisiones.
Mantener compatibilidad con Jenkins y Nextcloud.

Opciones candidatas:

IMPLE_<CUSTOMER>_<BAP_NAME>_<VERSION>_<SEQ>
IMPLE_<BAP_NAME>_<VERSION>_<YYYYMMDD>_<SEQ>
IMPLE_<COMPONENT>_<VERSION>_<SEQ>

Ejemplo:

IMPLE_BANCA_PERSONAS_2_4_1_001

Decisión pendiente:

Definir convención oficial para IMPLENAME.

34. API Conceptual

23.1 Implementations

GET    /promotions/implementations
POST   /promotions/implementations
GET    /promotions/implementations/{id}
GET    /promotions/implementations/{id}/files
GET    /promotions/implementations/{id}/steps2run
PUT    /promotions/implementations/{id}/steps2run

23.2 Packages

POST   /promotions/implementations/{id}/packages
GET    /promotions/packages/{packageId}
GET    /promotions/packages/{packageId}/download-link

23.3 Deployments

POST   /promotions/packages/{packageId}/deployments
GET    /promotions/deployments/{deploymentId}
GET    /promotions/deployments/{deploymentId}/events
GET    /promotions/deployments/{deploymentId}/logs

23.4 Customer Config

GET    /promotions/customers/{customerId}/config
PUT    /promotions/customers/{customerId}/config

23.5 SSE

GET /promotions/events?entityType=deployment&entityId=<id>
GET /promotions/events?entityType=package&entityId=<id>

34. Validaciones

24.1 Crear Implementación

Validar:

Usuario tiene permiso promotion:create-folder.
BAP existe en BAR.
Cliente asociado existe o puede resolverse.
Cliente tiene metadata válida.
Environment permitido.
Node permitido.
IMPLENAME no existe ya en el path destino.
Nextcloud está disponible.
BAR devuelve BAP .tar.gz y bapProps.

24.2 Editar `steps2run.vt`

Validar:

Usuario tiene permiso promotion:edit-steps2run.
Archivo existe.
Formato por línea válido:

<artifact>.tar.gz:<node|ALL>

Artefacto referenciado existe en IMPLE_VTNET_OBJECTS, salvo reglas especiales.
Node existe en choices de Jenkins o metadata JSON.
No se introducen comandos o contenido fuera del contrato esperado.

24.3 Generar Paquete

Validar:

Usuario tiene permiso promotion:create-package.
Implementation está en FOLDER_READY.
steps2run.vt existe y es válido.
BAP y bapProps existen en Nextcloud.
Jenkins está disponible.
Parámetros requeridos pueden resolverse.

24.4 Ejecutar

Validar:

Usuario tiene permiso promotion:execute.
Cliente soporta ejecución remota.
Package está en PACKAGE_READY.
Package tiene packagePath resoluble.
Node permitido.
Jenkins está disponible.
Parámetros requeridos pueden resolverse.

34. Observabilidad

25.1 Logs

Promotions debe registrar logs propios para:

Requests de usuario.
Llamadas a BAR.
Llamadas a Nextcloud.
Llamadas a Jenkins.
Errores de integración.
SSE events emitidos.
Cambios de estado.

25.2 Métricas

Métricas sugeridas:

implementations_created_total
package_generations_requested_total
package_generations_succeeded_total
package_generations_failed_total
deployments_requested_total
deployments_succeeded_total
deployments_failed_total
jenkins_poll_duration_ms
nextcloud_operation_duration_ms
bar_download_duration_ms
sse_connections_active

25.3 Trazabilidad

Cada flujo debe tener IDs correlacionables:

implementationId
packageId
deploymentId
generationBuildId
executionBuildId
auditEventId

34. Manejo de Errores

26.1 Error descargando desde BAR

Estado:

FAILED

Evento:

implementation.failed

Mensaje sugerido:

No se pudo obtener el BAP o bapProps desde BAR.

26.2 Error creando carpeta en Nextcloud

Estado:

FAILED

Posibles causas:

Path ya existe.
Credenciales inválidas.
Permisos insuficientes.
Nextcloud no disponible.

26.3 Error creando paquete en Jenkins

Estado:

PACKAGE_FAILED

Promotions debe guardar:

Build URL.
Último status.
Logs relevantes o link.
Error resumido si puede extraerse.

26.4 Error ejecutando implementación

Estado:

DEPLOYMENT_FAILED

Promotions debe guardar:

Build URL.
Logs.
Resultado parcial si existe.
Error parseado si es posible.

26.5 SSE desconectado

Si la conexión SSE se corta, la UI debe poder reconectar y recuperar estado actual mediante REST.

34. Seguridad

27.1 Autenticación

Promotions usará Workspace para autenticar usuarios.

27.2 Autorización

Promotions usará permisos granulares asociados a roles/grupos de Workspace.

27.3 Secretos

Los secretos de integración deben estar fuera del frontend.

Promotions Backend debe manejar:

Credenciales BAR si aplican.
Credenciales Nextcloud.
Credenciales Jenkins.
Tokens técnicos.
Parámetros sensibles.

27.4 Token Runtime

Si existe un token runtime requerido por Jenkins/vt-wizard, Promotions debe tratarlo como secreto.

Opciones:

Pedirlo cada vez y no persistirlo.
Resolverlo desde configuración segura.
Integrarlo con Workspace/secret manager futuro.

Para v1 puede mantenerse como input no persistido si así lo exige el flujo actual.

34. Riesgos

Riesgo	Impacto	Mitigación
Jenkins no expone parámetros dinámicos suficientes	UI no puede poblar nodos automáticamente	Fallback a metadata JSON por cliente.
Contrato de jobs nuevos no está definido	Promotions no puede invocar Jenkins establemente	Definir contrato explícito para generation/execution jobs.
Logs Jenkins no son parseables	No se puede mostrar resumen estructurado	Mostrar estado + logs + link; mejorar parser luego.
Nextcloud falla al crear carpetas	Implementaciones quedan incompletas	Operaciones idempotentes y validación previa de paths.
`IMPLENAME` no estandarizado	Colisiones o nombres ambiguos	Definir convención antes de producción.
Permisos demasiado amplios	Riesgo operativo	Usar permisos granulares en Workspace.
Cliente on-premise intenta ejecutar remoto	Error operativo	Ocultar acción si `supportsRemoteExecution=false`.
Link directo Nextcloud no cumple necesidades de seguridad futuras	Exposición o trazabilidad limitada	Evolucionar a link efímero/proxy.
Jenkins abort/cancel no está claro	No se puede cancelar ejecución	Dejar cancel fuera de v1.

34. Roadmap Técnico Sugerido

Fase 1 — Base de Dominio y Metadata

Modelo de DB.
Customer metadata JSON.
Integración Workspace permissions.
Listado de implementaciones.
Creación manual/controlada de registros.

Fase 2 — Integración BAR + Nextcloud

BAR Adapter.
Nextcloud Adapter.
Crear carpeta de implementación.
Copiar BAP y bapProps.
Generar steps2run.vt.
Editar steps2run.vt.

Fase 3 — Jenkins Packaging Desacoplado

Jenkins Adapter.
Contrato con Generate VT-FULL Job.
Trigger del job de generación.
Polling de estado.
SSE para packaging.
Resolver paquete final.
Link de descarga v1.

Fase 4 — Deployment Execution Desacoplado

Contrato con Execute VT-FULL Job.
Trigger del job de ejecución usando package existente.
SSE de ejecución.
Logs.
Parser inicial de resultados.
Restricción por supportsRemoteExecution.

Fase 5 — Hardening

Auditoría completa.
Validaciones avanzadas.
Mejoras de permisos.
Observabilidad.
POC de extracción de parámetros Jenkins.
Estándar final de IMPLENAME.

Fase 6 — Evoluciones Futuras

Links efímeros.
VTPROD.
Cancelación/abort si Jenkins lo soporta.
Runner customer-hosted.
Reemplazo gradual de Jenkins.
Storage adapter alternativo.
Resultado estructurado nativo desde vt-wizard.

34. Decisiones de Arquitectura

ADR-001 — Jenkins se mantiene como caja negra en v1

Decisión: Promotions invoca Jenkins, pero no modela internamente sus stages.
Motivo: Reducir alcance y aprovechar el flujo existente.
Consecuencia: La arquitectura depende de Jenkins Adapter y del contrato de parámetros.

ADR-002 — Packaging y execution se desacoplan

Decisión: Promotions usará dos jobs/scripts: uno para generar VT-FULL y otro para ejecutar un VT-FULL ya generado.
Motivo: Evitar regenerar paquetes durante ejecución y mejorar trazabilidad.
Consecuencia: Se requiere definir dos contratos de parámetros con Jenkins.

ADR-003 — BAR es la fuente del BAP

Decisión: Promotions obtiene BAP y bapProps desde BAR.
Motivo: Centralizar origen de artefactos y evitar carga manual.
Consecuencia: Se requiere BAR Adapter y manejo de errores de descarga.

ADR-004 — Promotions copia físicamente los archivos a Nextcloud

Decisión: El BAP .tar.gz y bapProps se copian dentro de IMPLE_VTNET_OBJECTS.
Motivo: Mantener compatibilidad con el pipeline actual.
Consecuencia: Nextcloud sigue siendo el storage operativo para Jenkins.

ADR-005 — Solo `steps2run.vt` será editable en v1

Decisión: La UI permitirá editar únicamente steps2run.vt.
Motivo: Reducir riesgo operativo y evitar carga/modificación arbitraria de artefactos.
Consecuencia: Props y BAP quedan controlados por BAR y por el sistema.

ADR-006 — SSE se implementa desde Promotions hacia UI

Decisión: Promotions hará polling a Jenkins y emitirá SSE a la UI.
Motivo: Evitar que la UI dependa directamente de Jenkins.
Consecuencia: Promotions debe mantener workers/pollers o procesos de seguimiento.

ADR-007 — Metadata de cliente en JSON configurable

Decisión: La metadata faltante de cliente vivirá en JSON configurable en DB.
Motivo: No toda la metadata existe hoy en un sistema central.
Consecuencia: Se requiere UI/API administrativa y validación de schema.

ADR-008 — Link directo Nextcloud en v1

Decisión: v1 puede devolver un link directo a Nextcloud para descargar el paquete.
Motivo: Reducir complejidad inicial.
Consecuencia: Links efímeros quedan como mejora futura.

34. Preguntas Abiertas

¿Cuál será la convención oficial para IMPLENAME?
¿Cuáles serán los nombres finales de los jobs/scripts nuevos?
¿Qué parámetros exactos recibirá Generate VT-FULL Job?
¿Qué parámetros exactos recibirá Execute VT-FULL Job?
¿El job de ejecución recibirá PACKAGE_PATH, PACKAGE_NAME + REPO_CLIENT, packageId, u otro contrato?
¿Qué parámetros Jenkins se podrán extraer dinámicamente en la POC?
¿Qué formato real tendrá el resultado estructurado parseado desde logs?
¿Dónde se administrará visualmente el JSON de metadata de clientes?
¿Qué permisos exactos se mapearán contra grupos reales de Workspace?
¿El token runtime seguirá siendo input manual no persistido o se resolverá desde un mecanismo seguro?
¿Cuándo se incorporará el flujo VTPROD?
¿Cómo se versionarán cambios en steps2run.vt?
¿Se almacenará snapshot del contenido de steps2run.vt al momento de empaquetar?
¿Se debe generar documentación automática desde v1 o dejarlo según configuración de Jenkins?

34. Glosario

Término	Significado
Promotions	Sistema/capacidad para orquestar implementaciones desde Workspace.
Workspace	Componente Veritran donde vivirá Promotions y desde donde se gestionará autenticación/autorización.
BAR	BAP Application Repository, origen del BAP y `bapProps`.
BAP	Artefacto de aplicación/implementación devuelto por BAR como `.tar.gz`.
`bapProps`	Archivo de propiedades asociado al BAP.
Nextcloud	Storage actual en `repo.veritran.com`.
`repo.veritran.com`	Repositorio hospedado por Veritran.
`VTQA-PACKAGES`	Carpeta de trabajo inicial para implementaciones VTQA.
`VTPROD-PACKAGES`	Carpeta de producción, fuera de alcance v1.
`IMPLENAME`	Nombre de implementación usado como folder y parte del nombre del paquete final.
`IMPLE_VTNET_OBJECTS`	Carpeta donde se colocan BAP, `bapProps` y `steps2run.vt`.
`steps2run.vt`	Receta editable que mapea artefactos contra nodos.
`VT-FULL-<IMPLENAME>.tar.gz`	Paquete final generado por Jenkins.
Generate VT-FULL Job	Job/script Jenkins dedicado a generar el paquete final.
Execute VT-FULL Job	Job/script Jenkins dedicado a ejecutar un paquete final ya generado.
Jenkins Adapter	Capa que encapsula invocación y consulta de Jenkins.
Nextcloud Adapter	Capa que encapsula operaciones contra Nextcloud.
BAR Adapter	Capa que encapsula consumo de BAR.
SSE	Server-Sent Events para progreso casi realtime.
Cliente conectado	Cliente donde Veritran puede ejecutar remotamente.
Cliente on-premise	Cliente donde la ejecución se realiza manualmente dentro de infraestructura del cliente.

34. Resumen Final

Promotions v1 debe actuar como una capa de producto y orquestación sobre el flujo existente de implementaciones VTQA.

La solución propuesta automatiza la preparación manual en Nextcloud, integra BAR como fuente de BAP, mantiene Jenkins como caja negra, permite generar paquetes finales, habilita ejecución remota solo cuando corresponde, ofrece progreso casi realtime vía SSE y conserva el contrato portable VT-FULL-<IMPLENAME>.tar.gz.

La actualización más relevante es que el flujo de Jenkins se desacoplará en dos jobs/scripts específicos para Promotions:

Generate VT-FULL Job
Execute VT-FULL Job

Esto evita regenerar paquetes durante la ejecución y permite que cada deployment quede asociado a un package concreto y trazable.

El diseño favorece evolución incremental: primero encapsular y gobernar el flujo actual; luego mejorar seguridad, auditoría, descargas, parsing de resultados, VTPROD, runners customer-hosted o incluso reemplazo gradual de Jenkins.

Documento de Arquitectura — Promotions To-Be Inicial

1. Resumen Ejecutivo

2. Objetivos

2.1 Objetivos Funcionales

2.2 Objetivos Técnicos

2.3 Objetivos de Producto

3. No Objetivos / Fuera de Alcance v1

4. Principios de Diseño

4.1 Jenkins como Caja Negra

4.2 Separación entre Packaging y Execution

4.3 Separación entre Dominio y Backend Técnico

4.4 Portabilidad del Paquete

4.5 Automatizar lo Manual sin Romper el Flujo Actual

4.6 Evolución por Adapters

4.7 Auditoría desde el Inicio

5. Arquitectura de Alto Nivel

34. Cambio Relevante: Jobs Específicos para Promotions

6.1 Situación Legacy

6.2 Nuevo Modelo

6.3 Beneficios

6.4 Diagrama

34. Componentes Principales

6.1 Promotions UI

6.2 Promotions Backend/API

6.3 Promotions DB

6.4 BAR Adapter

6.5 Nextcloud Adapter

6.6 Jenkins Adapter

6.7 SSE Event Stream

6.8 Audit/Event Log

34. Modelo de Dominio

7.1 Entidades Principales

34. Metadata Configurable por Cliente

34. Permisos

34. Estados

10.1 Estados de Implementation

10.2 Estados de ImplementationPackage

10.3 Estados de DeploymentExecution

10.4 Vista Unificada de Estado

10.5 Máquina de Estados General

34. Flujo 1 — Crear Implementación desde BAP

11.1 Objetivo

11.2 Flujo

11.3 Estructura Generada

11.4 Generación Inicial de steps2run.vt

11.5 Edición de steps2run.vt

34. Flujo 2 — Generar Paquete de Implementación

12.1 Objetivo

12.2 Decisión

12.3 Flujo

12.4 Parámetros hacia Jenkins

34. Flujo 3 — Ejecutar Paquete

13.1 Objetivo

13.2 Regla de Disponibilidad

13.3 Decisión

13.4 Flujo

34. SSE y Seguimiento Realtime

14.1 Decisión v1

14.2 Motivos

14.3 Ejemplo de Eventos SSE

34. Resultado Estructurado de Ejecución

34. Flujo 4 — Descargar Paquete

16.1 Objetivo

16.2 Decisión v1

16.3 Futuro

34. Clientes On-Premise

17.1 Regla

17.2 Diagrama

34. Clientes con Ejecución Remota

18.1 Regla

18.2 Diagrama

34. Contrato con Nextcloud

19.1 Paths

19.2 Operaciones v1

34. Contrato con Jenkins

20.1 Jenkins como Execution Backend

20.2 Generar Paquete

20.3 Ejecutar Paquete

20.4 Parámetros

34. POC de Parámetros Dinámicos Jenkins

11.4 Generación Inicial de `steps2run.vt`

11.5 Edición de `steps2run.vt`

24.2 Editar `steps2run.vt`

ADR-005 — Solo `steps2run.vt` será editable en v1