Guía de implementación Vigente Versión: 1.0.1Estado: ACTIVOEntrada en vigor desde: 11/07/2024 | Guía de implementación PRE-RELEASE Versión: -Estado: -Entrada en vigor desde: N/A |
|---|
Las normas expuestas son de obligado cumplimiento. La STIC podrá estudiar los casos excepcionales los cuales serán gestionados a través de los responsables del proyecto correspondiente y autorizados por el Área de Gobernanza de la STIC. Asimismo cualquier aspecto no recogido en estas normas deberá regirse en primera instancia por las guías técnicas correspondientes al esquema nacional de seguridad y esquema nacional de interoperabilidad según correspondencia y en su defecto a los marcos normativos y de desarrollo software establecidos por la Junta de Andalucía, debiendo ser puesto de manifiesto ante la STIC.
La STIC se reserva el derecho a la modificación de la norma sin previo aviso, tras lo cual, notificará del cambio a los actores implicados para su adopción inmediata según la planificación de cada proyecto.
En el caso de que algún actor considere conveniente y/o necesario el incumplimiento de alguna de las normas y/o recomendaciones, deberá aportar previamente la correspondiente justificación fehaciente documentada de la solución alternativa propuesta, así como toda aquella documentación que le sea requerida por la STIC para proceder a su validación técnica.
Contacto Arquitectura: l-arquitectura.stic@juntadeandalucia.es
Los cambios en la normativa vendrán acompañados de un registro de las modificaciones. De este modo se podrá realizar un seguimiento y consultar su evolución. Ordenándose de mas recientes a menos recientes, prestando especial cuidado a las cabeceras de la tablas dónde se indican las fechas de entrada en vigor y versión.
El objetivo de este documento es determinar las pautas desde una visión general de todos los elementos que afectan al desarrollo y uso de los microfrontend
Definiciones
Ámbito de aplicación obligatorio (*) Esta arquitectura de referencia será de aplicación obligatoria(*) en los siguientes casos:
|
|---|
Se recomienda su aplicación:
Se recomienda analizar en detalle con la unidad de Arquitectura de la STIC y particularizarla para los siguientes casos:
Los cambios normativos dentro de la arquitectura de referencia seguirán el siguiente ciclo de vida:
La arquitectura de la solución resuelve la integración entre una aplicación "Host" y una o varios subgrupos funcionales de otros dominios de negocio, microfrontends. Esto brinda una solución altamente escalable y componible, de modo que las soluciones funcionales disponen de flexibilidad para configurar los niveles de agregación funcional necesarios.
La estrategia de la solución está basada en la presentación de un fragmento funcional "Fragment" con un añadido transversal identificado en base a capacidades "capabilites", las cuales habilitan que el fragmento sea interoperable dentro del navegador web que lo alberga de forma ordenada, segregando los aspectos comunes de forma cohesionada y homogénea en toda la organización.
Principios de comunicacion
Las integraciones Host con Microfront están basadas en el principio fundamental de que la interfaz de usuario es una representación del estado de la información que contiene.
Por ello se pauta una estrategia homogénea y cohesionada para que los datos fluyan hacia dentro de las componentes y los eventos hacia afuera.
El mantenimiento de este enfoque a lo largo de toda la implementación nos permite tener un modelo altamente componible, reutilizable y mantenible.
La violación de estos principios conllevaría la perdida de todos los beneificios expuestos, incrementando costes de desarrollo y reduciendo la capacidad de ser mantenidos y reutilizados.
Por esto no está permitida y debe evitarse a toda costa, y será objeto de revisión por parte del dpto
Podemos distinguir entre dos tipos de integración Host ↔Microfront ( H/MF ) :
Esta sección establece la normativa sobre la tecnología que involucrada en el desarrollo de los microfrontales
En esta sección se describen las pautas dentro de la organización para el diseño de los microfrontales. Es muy importante la adecuada selección de la funcionalidad a asignar al microfrontend, de tal forma que esta se pueda distribuir de forma independiente y cubra una necesidad de reutilización identificada por las diferentes áreas responsables dentro de la organización.
🎨 Diseño | ||
|---|---|---|
👮 Pauta | 📖 Descripción | 🕵️ Verificación |
DIS-P1 | Los diseños deben seguir las pautas determinadas por el sistema de diseño | Flujo de validación del diseño |
DIS-P2 | Se debe entregar el mapa de componentes del microfrontend | Revisión de la tabla |
| DIS-P3 | Se debe entregar un wireframe con el diseño a alto nivel y las consideraciones a nivel de UX | Revisión del diseño |
| DIS-P4 | Se deben entregar los HiFi con los diseños finales a implementar | Revisión del HiFi |
| DIS-P5 | Los diseños deben cubrir las necesidades funcionales acordadas en los casos de uso asignados al microfrontend | Revisión de los Casos de Uso |
DIS-excepción ALERTA | En caso de necesitar enrutamiento externo (URL) deberá ser justificada y previamente validada por la oficina de arquitectura creando un ticket Jira de decisión técnica (Tarea genera → tipo: decisión → subtipo: técnica) en el proyecto y asignársela al responsable del departamento LUIS MARTINEZ FONTIVEROS | N/A |
👨💻 Desarrollo | ||
|---|---|---|
👮 Pauta | 📖 Descripción | 🕵️ Verificación |
DES-P1 | Deben ser codificados con Typescript | Revisión de dependencias y Revisión de código |
DES-P2 | Deben estar basados en el estándar de Web Component | Revisión de código |
| DES-P3 | Para el desarrollo de los Web Component, se debe usar la librería de envoltura Lit | Revisión de dependencias y Revisión de código |
| DES-P4 | Se debe desarrollar haciendo uso de las herramientas provistas por el SAS, para el desarrollo de microfrontends | Revisión de dependencias y Revisión de código |
DES-excepción ALERTA | En caso de necesitar enrutamiento externo (URL) deberá ser justificada y previamente validada por la oficina de arquitectura creando un ticket Jira de decisión técnica (Tarea genera → tipo: decisión → subtipo: técnica) en el proyecto y asignársela al responsable del departamento LUIS MARTINEZ FONTIVEROS | N/A |
En esta sección se describen las pautas tecnológicas dentro de la organización para el testing de los microfrontends.
🧪 Testing | ||
|---|---|---|
👮 Pauta | 📖 Descripción | 🕵️ Verificación |
TST-P1 | El framework para definir los test es @openwc/testing que se basa en chai y mocha. | Revisión de dependencias y Revisión de código |
TST-P2 | El runner es Web Test Runner | Revisión de dependencias y Revisión de código |
| TST-P3 | El framework para mock es Sinon | Revisión de dependencias y Revisión de código |
| TST-P4 | La herramienta de browser headless es Puppeteer | Revisión de dependencias y Revisión de código |
ENR-excepción ALERTA | En caso de necesitar enrutamiento externo (URL) deberá ser justificada y previamente validada por la oficina de arquitectura creando un ticket Jira de decisión técnica (Tarea genera → tipo: decisión → subtipo: técnica) en el proyecto y asignársela al responsable del departamento LUIS MARTINEZ FONTIVEROS | N/A |
💻 Stand-alone | ||
|---|---|---|
👮 Pauta | 📖 Descripción | 🕵️ Verificación |
SA-P1 | Debe disponer de un componente de encapsulación que encargue de ofrecer los elementos del layout:
| Revisión del diseño y Revisión de código |
SA-P2 | El componente de encapsulación es el encargado de gestionar las notificaciones (diseño, componente) | Test unitario y Test de integración |
| SA-P3 | EL contenedor será el encargado de instanciar el theming de la stic. | Revisión de código |
| SA-P4 | El microfrontend no tendrá ningún acoplamiento o conocimiento de la existencia de este componente de encapsulación, para él es una integración con un host | Revisión de código |
| SA-P5 | El contenedor será un componente en CMS independiente y en el repositorio de código un componente de tipo aplicación (sas-cli). | Revisión de código y Revisión de CMS |
| SA-P6 | El proyecto debe tener un componente helm que permita el despliegue en las cloud privada del SAS | Revisión del helm |
| SA-P7 | La configuración deberá ser proporcionada a través de un configmap definido en el helm. Dicha configuración no debe tener información sensible y debe estar adaptada a los entornos donde se vaya a desplegar | Revisión del helm |
| SA-P8 | Debe ofrecer una propiedad que permita elegir entre integración:
| Revisión de la documentación, Test unitario |
| SA-P9 | El microfrontend debe entregar, a través del alm del SAS, un paquete npm en el repositorio de artefactos sin incluir el contenedor (Build-time) | Revisión del ALM y Revisión del repositorio de artefactos |
| SA-10 | El microfrontend debe entregar una versión ligera (sin dependencias externas), minificada y bundelizada en el CDN (Run-time) | Revisión del CDN |
| SA-11 | Toda esta información debe estar disponible y correctamente documentada, basándose para ello en la plantilla de documentación del microfrontend | Revisión de la documentación |
SA-excepción ALERTA | En caso de necesitar enrutamiento externo (URL) deberá ser justificada y previamente validada por la oficina de arquitectura creando un ticket Jira de decisión técnica (Tarea genera → tipo: decisión → subtipo: técnica) en el proyecto y asignársela al responsable del departamento LUIS MARTINEZ FONTIVEROS | N/A |
💻 Integrado | ||
|---|---|---|
👮 Pauta | 📖 Descripción | 🕵️ Verificación |
INT-P1 | El microfrontend será un componente en CMS independiente y en el repositorio de código un componente de tipo fragment (sas-cli). | Revisión de código y Revisión de CMS |
INT-P2 | Este tipo de microfrontend no se despliega en ningún servidor | Test unitario |
| INT-P3 | El microfrontend debe entregar, a través del alm del SAS, un paquete npm en el repositorio de artefactos sin incluir el contenedor (Build-time) | Revisión del ALM y Revisión del repositorio de artefactos |
| INT-P4 | El microfrontend debe entregar una versión ligera (sin dependencias externas), minificada y bundelizada en el CDN (Run-time) | Revisión del CDN |
| INT-P5 | Toda esta información debe estar disponible y correctamente documentada, basándose para ello en la plantilla de documentación del microfrontend | Revisión de documentación |
ENR-excepción ALERTA | En caso de necesitar enrutamiento externo (URL) deberá ser justificada y previamente validada por la oficina de arquitectura creando un ticket Jira de decisión técnica (Tarea genera → tipo: decisión → subtipo: técnica) en el proyecto y asignársela al responsable del departamento LUIS MARTINEZ FONTIVEROS | N/A |
🏗️ BuildTime | ||
|---|---|---|
👮 Pauta | 📖 Descripción | 🕵️ Verificación |
IBT-P1 | El host debe ser compatible con tecnología web-componente y lit | Se visualiza en el navegador |
ENR-P2 | El host debe utilizar ÚNICAMENTE paquetes obtenidos a través del repositorio de artefactos del SAS | Revisión del ALM |
| ENR-P3 | El host debe incluir en la sección dependencies del package.json de la aplicación | Revisión del package.json y Revisión del ALM |
| ENR-P4 | En caso de que el host sea una aplicación legacy, server render o escritorio, se deberá incluir un mecanismo (Maven, Ant, Nuget) en tiempo de construcción compatible con proyectos npm que descargue las dependencias del repositorio de artefactos y las copie a la carpeta de script de la aplicación legacy. | Revisión de configuración del gestor de paquetería y Revisión del ALM |
| ENR-P5 | El microfrontend debe entregar, a través del alm del SAS, un paquete npm en el repositorio de artefactos sin incluir el contenedor (Build-time) | Revisión del ALM y Revisión del repositorio de artefactos |
| ENR-P6 | El microfrontend debe ofrecer una documentación con toda la información necesaria para una integración en build-time, basándose para ello en la plantilla de documentación del microfrontend | Revisión de documentación |
ENR-excepción ALERTA | En caso de necesitar enrutamiento externo (URL) deberá ser justificada y previamente validada por la oficina de arquitectura creando un ticket Jira de decisión técnica (Tarea genera → tipo: decisión → subtipo: técnica) en el proyecto y asignársela al responsable del departamento LUIS MARTINEZ FONTIVEROS | N/A |
🏃♀️ RunTime | ||
|---|---|---|
👮 Pauta | 📖 Descripción | 🕵️ Verificación |
IRT-P1 | El host debe tener las dependencias de terceras necesarias para cargar el microfrontend | Revisión de código |
IRT-P2 | El host debe utilizar únicamente scripts del CDN del SAS | Revisión de código |
| IRT-P3 | El host debe incluir la configuración de importmap establecida en la documentación del microfrontend | Revisión de código |
| IRT-P4 | El host debe usar importación dinámica de módulos para una optima descarga y carga de módulos siempre que no esté justificada una carga síncrona por rendimiento y/o experiencia de usuario (parpadeos) | Revisión de código |
| IRT-P5 | El microfrontend debe entregar una versión ligera (sin dependencias externas), minificada y bundelizada en el CDN (Run-time) | Revisión del CDN |
| IRT-P6 | La cargas de las páginas asociadas a la navegación deben implementarse con importación dinámica de módulos | Revisión de código |
| IRT-P7 | El microfrontend deberá documentar en una lista de importmaps las dependencias necesarias para su correcta ejecución. | Revisión de código, Test de Integración |
| IRT-P8 | El microfrontend debe ofrecer una documentación con toda la información necesaria para una integración en build-time, basándose para ello en la plantilla de documentación del microfrontend | Revisión de documentación |
ENR-excepción ALERTA | En caso de necesitar enrutamiento externo (URL) deberá ser justificada y previamente validada por la oficina de arquitectura creando un ticket Jira de decisión técnica (Tarea genera → tipo: decisión → subtipo: técnica) en el proyecto y asignársela al responsable del departamento LUIS MARTINEZ FONTIVEROS | N/A |
🌐 General | ||
|---|---|---|
👮 Pauta | 📖 Descripción | 🕵️ Verificación |
ENR-P1 | Se hará uso de la librería @sas/lib-stic-route que se puede descargar del repositorio de artefactos | Revisión de código |
ENR-P2 | La navegación será siempre interna | Test unitario |
| ENR-P3 | El microfrontend debe proporcionar una constante con una lista de los paths disponibles | Test unitario |
| ENR-P4 | El microfrontend debe proporcionar un método métodos para construir los paths con variables | Test unitario |
| ENR-P5 | El microfrontend debe proporcionar en la documentación los paths disponibles juntos con sus variables | Revisión de documentación |
| ENR-P6 | La cargas de las páginas asociadas a la navegación deben implementarse con importación dinámica de módulos | Revisión de código |
ENR-excepción ALERTA | En caso de necesitar enrutamiento externo (URL) deberá ser justificada y previamente validada por la oficina de arquitectura creando un ticket Jira de decisión técnica (Tarea genera → tipo: decisión → subtipo: técnica) en el proyecto y asignársela al responsable del departamento LUIS MARTINEZ FONTIVEROS | N/A |
🌐 General | ||
|---|---|---|
👮 Pauta | 📖 Descripción | 🕵️ Verificación |
COM-P1 | La comunicación entre el host y un MFE deberá ser la estándar en el desarrollo de componentes, propiedades hacia abajo, eventos hacia arriba. Para más detalle consultar nota aclaratoria | Revisión de código |
COM-P2 | Deberá estar documentada la api de integración con el MFE (propiedades y eventos) | Revisión de documentación |
| COM-P3 | La comunicación entre dos MFE, deberá ser orquestado por el Host | Revisión de código |
COM-excepción ALERTA | En caso de necesitar otro mecanismo de comunicación como buses de eventos compartidos, cookies o IndexedDB deberá ser justificada y previamente validada por la oficina de arquitectura creando un ticket Jira de decisión técnica (Tarea genera → tipo: decisión → subtipo: técnica) en el proyecto y asignársela al responsable del departamento LUIS MARTINEZ FONTIVEROS | N/A |
Nota Aclaratoria
selected property that can be initialized to a given value by the owner of the element, but that is updated by the component itself when the user selects an item. In these instances, the component should dispatch an event to indicate to the component's owner that the selected property changed. See Dispatching events for more details.👮 Pauta | 📖 Descripción | 🕵️ Verificación |
|---|---|---|
GEC-P1 | No existe estado compartido entre el host y el microfrontend | Revisión de código |
GEC-P2 | Cualquier necesidad para compartir información entre el host y el microfrontend deberá ser a través de las pautas de comunicación definidas | Revisión de código |
| GEC-P3 | El host no debe compartir información que esté fuera del contexto de negocio del microfrontend | Revisión de documentación |
GEC-excepción ALERTA | En caso de necesitar que alguna dependencia no sea cargada desde el CDN del SAS y quiera ser bundleizada deberá ser justificada y previamente validada por la oficina de arquitectura creando un ticket Jira de decisión técnica (Tarea genera → tipo: decisión → subtipo: técnica) en el proyecto y asignársela al responsable del departamento LUIS MARTINEZ FONTIVEROS | N/A |
👮 Pauta | 📖 Descripción | 🕵️ Verificación |
|---|---|---|
CV-P1 | Cada microfrontend debe versionar de forma independiente y como consecuencia:
| Revisión de código y Revisión de CMS |
CV-P2 | El control de versiones estará regido por las pautas marcadas por Semantic Version. Mayor.Minor.Patch | Test de regresión |
| CV-P3 | Patch: Indica correcciones sobre la funcionalidad de la versión | Revisión de Changelog |
| CV-P4 | Minor: Indica nuevas funcionalidades que son retrocompatibles, es decir, no existen eliminaciones o actualizaciones en el contrato de integración (api del componente). Los añadidos en el contrato que mantengan la retrocompatibilidad están permitidos. | Revisión de Changelog |
| CV-P5 | Mayor: Indica nuevas funcionalidades que no son retrocompatibles (breaking changes). Existe eliminación o actualización de elementos del contrato de integración (api del componente) | Revisión de Changelog |
| CV-P6 | Cualquier elemento que se desee eliminar deberá ser marcado como deprecado en la versión mayor actual e indicar la alternativa a utilizar que mantiene la funcionalidad y a partir de que mayor está versión será eliminada | Test de regresión |
| CV-P7 | Todas las dependencias del MFE deben ser cargadas desde el CDN del SAS. | Revisión de código y test de integración |
| CV-P8 | Todas las dependencias deben ser definidas en un script de importmap | Revisión de código y test de integración |
| CV-P9 | El script de importmap deberá ser inyectado en el index.html del host en la fase de construcción, obtenido de la documentación del microfronted | Revisión de código |
CV-excepción ALERTA | En caso de necesitar que alguna dependencia no sea cargada desde el CDN del SAS y quiera ser bundleizada deberá ser justificada y previamente validada por la oficina de arquitectura creando un ticket Jira de decisión técnica (Tarea genera → tipo: decisión → subtipo: técnica) en el proyecto y asignársela al responsable del departamento LUIS MARTINEZ FONTIVEROS | N/A |
👮 Pauta | 📖 Descripción | 🕵️ Verificación |
|---|---|---|
| SEG-P1 | En caso identificarse como un microfrontend seguro, el microfrontend es el encargado de gestionar su propia seguridad, proporcionando los recursos y la documentación adecuada para su garantía | Revisión del Diseño, Revisión de código y Revisión de documentación |
| SEG-P2 | La información de seguridad se deberá transmitir a través de jwt | Revisión del Diseño |
| SEG-P3 | El Jwt debe ser firmado en la creación y debe exponer la clave pública para que cualquier elemento pueda validarlo | Revisión del Diseño y Revisión de documentación |
| SEG-P4 | El host NO tiene la responsabilidad de proporcionar los roles y permisos del usuario, sólo el OpenID | Test de integración |
| SEG-P5 | El microfrontend tiene que tener la capacidad de a partir del OpenID del usuario proporcionado por el host obtener un token jwt con la información de seguridad relevante para su contexto | Test unitario y Test de integración |
SEG-excepción ALERTA | En caso de necesitar que alguna dependencia no sea cargada desde el CDN del SAS y quiera ser bundlelizada deberá ser justificada y previamente validada por la oficina de arquitectura creando un ticket Jira de decisión técnica (Tarea genera → tipo: decisión → subtipo: técnica) en el proyecto y asignársela al responsable del departamento LUIS MARTINEZ FONTIVEROS | N/A |
👮 Pauta | 📖 Descripción | 🕵️ Verificación |
|---|---|---|
TEC-P1 | El MFE deberá ser desarrollado estilísticamente en base a las pautas definidas en el sistema de diseño | Revisión del Diseño |
TEC-P2 | El MFE deberá ser desarrollado haciendo uso del catálogo de componentes de la STIC, que estarán acordes a lo definido en el sistema de diseño | Revisión de dependencias y Revisión de código |
TEC-P3 | El MFE deberá ser desarrollado haciendo uso de las variables expuestas por el componente del stic-theme | Revisión de código |
TEC-P4 | El MFE NO deberá instanciar el componente de theming | Test unitario |
TEC-P5 | El host es el responsable de instanciar el theming del que se nutrirá el MFE | Test de integración |
TEC-excepción ALERTA | En caso de necesitar un framework de desarrollo diferente al normativizado deberá ser justificada y previamente validada por la oficina de arquitectura creando un ticket Jira de decisión técnica (Tarea genera → tipo: decisión → subtipo: técnica) en el proyecto y asignársela al responsable del departamento LUIS MARTINEZ FONTIVEROS | N/A |
👮 Pauta | 📖 Descripción | 🕵️ Verificación |
|---|---|---|
CMF-P1 | El host-legacy, siempre que no esté en fase de migración tecnológica, mantendrá la tecnología con la que esté desarrollado en ese momento | Revisión de código |
CMF-P2 | El host nuevo deberá ser desarrollado exclusivamente en Lit | Revisión de código |
CMF-P3 | Los MFE deberán ser realizados exclusivamente en Lit | Revisión de código |
CMF-P4 | Todas las dependencias del MFE deben ser cargadas desde el CDN del SAS. | Revisión de código |
CMF-P5 | Todas las dependencias deben ser definidas en un script de importmap | Revisión de código |
CMF-P6 | El script de importmap deberá ser inyectado en el index.html del host en la fase de construcción, obtenido de la documentación del microfronted | Revisión de código y Revisión de la documentación |
CMF-excepción ALERTA | En caso de necesitar una especialización de los estilos no contemplada en el sistema de diseño y/o en el theme de la STIC, deberá ser justificada y previamente validada por la oficina de arquitectura creando un ticket Jira de decisión técnica (Tarea genera → tipo: decisión → subtipo: técnica) en el proyecto y asignársela al responsable del departamento LUIS MARTINEZ FONTIVEROS | N/A |
| 👮 Pauta | 📖 Descripción | 🕵️ Verificación |
|---|---|---|
| TF-P1 | El microfrontend notificará al host de cualquier error ocurrido a través de un evento de error | Test unitario |
| TF-P2 | El microfrontend debe tener un fallback definido para cualquier excepción o error ocurrido en el microfrontend, es decir, no debe haber unhandled exception | Test unitario |
| TF-P3 | En caso de error el microfrontend no se puede quedar intestable, es decir, debe seguir dando respuesta a las interacciones. | Test unitario |
| TF-P4 | El evento debe tener información de negocio asociado al error, evitando detalles técnicos e información sensible (Contraseñas, LOPDGDD etc.. ) | Revisión de la documentación |
| TF-P5 | El error debe registrarse en la consola de error, con información técnica que ayude a su detección y resolución. NUNCA se debe enviar información sensible (Contraseñas, LOPDGDD etc.. ) | Revisión de código |
TF-excepción ALERTA | En caso de necesitar una especialización de los estilos no contemplada en el sistema de diseño y/o en el theme de la STIC, deberá ser justificada y previamente validada por la oficina de arquitectura creando un ticket Jira de decisión técnica (Tarea genera → tipo: decisión → subtipo: técnica) en el proyecto y asignársela al responsable del departamento LUIS MARTINEZ FONTIVEROS | N/A |
| Concepto a Desarrollar | Estado | POC |
|---|---|---|
Tecnología | DEFINIDO | REALIZADA |
Ejecución | DEFINIDO | REALIZADA |
Integración | DEFINIDO | A MEDIAS |
Enrutamiento (Interno, Dinámico) | DEFINIDO | REALIZADA |
Comunicación (Host- MFE / MFE-MFE) | DEFINIDO | REALIZADA |
Gestión de Estado Compartido | DEFINIDO | REALIZADA |
Control de Versiones | DEFINIDO | REALIZADA |
Seguridad | DEFINIDO | PENDIENTE |
Tema y Estilos Compartidos | DEFINIDO | REALIZADA |
Tolerancia a Fallos | DEFINIDO | PENDIENTE |
Compatibilidad con Múltiples Frameworks | DEFINIDO | REALIZADA |