Subdirección de las Tecnologías de la Información y Comunicaciones
Área de Gobernanza y Calidad
Dirección General de Sistemas de Información y Comunicaciones
Áreas de Gobierno Tecnológico de SSII y del Dato
Versión
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 |
|---|
Tabla de Contenido
Cumplimiento Normativo
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
Histórico de cambios
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.
🤖 Tecnología
En esta sección se listarán las pautas a seguir para la creación de un microfrontend.
Las pautas se encuentran enmarcadas en los siguientes contextos:
🎨 Diseño
Estas pautas tratan de la fase de diseño del microfrontend
🎨 Diseño | ||
|---|---|---|
👮 Pauta | 📖 Descripción | 🕵️ Verificación |
TEC-DIS-P1 | Los diseños deben estar alineados las pautas definidas por el sistema de diseño | Flujo de validación del diseño |
TEC-DIS-P2 | Se debe entregar el mapa de componentes del microfrontal | Revisión de la tabla |
| TEC-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 |
| TEC-DIS-P4 | Se deben entregar los HiFi con los diseños finales a implementar | Revisión del HiFi |
| TEC-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 |
TEC-DIS-excepción ALERTA | En caso de necesitar realizar un diseño que esté desalineado con estas pautas 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
Estas pautas tratan los requisitos tecnológicos para el desarrollo del microfrontend👨💻 Desarrollo | ||
|---|---|---|
👮 Pauta | 📖 Descripción | 🕵️ Verificación |
TEC-DES-P1 | Deben ser codificados con Typescript | Revisión de dependencias y Revisión de código |
TEC-DES-P2 | Deben estar basados en el estándar de Web Component | Revisión de código |
| TEC-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 |
| TEC-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 |
TEC-DES-excepción ALERTA | En caso de necesitar realizar un desarrollo que esté desalineado con estas pautas 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 |
🧪 Testing
Estas pautas tratan los requisitos tecnológicos para el testeo del microfrontend
🧪 Testing | ||
|---|---|---|
👮 Pauta | 📖 Descripción | 🕵️ Verificación |
TEC-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 |
TEC-TST-P2 | El runner es Web Test Runner | Revisión de dependencias y Revisión de código |
| TEC-TST-P3 | El framework para mock es Sinon | Revisión de dependencias y Revisión de código |
| TEC-TST-P4 | La herramienta de browser headless es PlayWright | Revisión de dependencias y Revisión de código |
TEC-TST-excepción ALERTA | En caso de necesitar realizar un testeo que esté desalineado con estas pautas 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
En esta sección se listarán las pautas a seguir para el desarrollo de un microfrontend en el ámbito
🌐 General
🌐 General | ||
|---|---|---|
👮 Pauta | 📖 Descripción | 🕵️ Verificación |
DES-P1 | El microfrontend debe extender de SticMicrofrontendView. Esta clase se puede obtener de @sas/wc-stic-microfrontend | Revisión de dependencias y Revisión de código |
DES-P2 | NO debe instanciar ningún theming, delegando dicha responsabilidad al contenedor del microfrontend (Host o un contenedor para el stand-alone) | Revisión de dependencias y Revisión de código |
DES-P3 | NO debe disponer de un layout general, delegando dicha responsabilidad al contenedor del microfrontend (Host o un contenedor para el stand-alone)
| Revisión del diseño y Revisión de código |
DES-P4 | El microfrontend debe exponer todas las propiedades que considere relevantes para ejecutar los casos de uso de los que es responsable. En caso de estar compuesto por otro componente que tenga propiedades relevantes para la ejecución de los casos de uso deberá hacer prop drilling y ser el responsable de exponer dichas propiedades |
|
DES-P5 | Debe seguir las pautas de routing |
|
DES-P6 | Debe seguir las pautas de comunicación |
|
| DES-P7 | Debe seguir las pautas de configuración |
|
| DES-P8 | Debe seguir las pautas de seguridad |
|
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 |
💻 Stand-Alone
💻 Stand-Alone | ||
|---|---|---|
👮 Pauta | 📖 Descripción | 🕵️ Verificación |
DES-SA-P1 | El contenedor será un componente en CMS independiente y su propio repositorio de código | Revisión de dependencias y Revisión de código |
DES-SA-P2 | Se deberán de desarrollar un componente de tipo aplicación (sas-cli). | Revisión de dependencias y Revisión de código |
DES-SA-P3 | Es el responsable de instanciar el theming del microfrontend cuando este se ejecute en modo stand-alone |
|
DES-SA-P4 | Es el responsable de instanciar el layout general del microfrontend cuando este se ejecute en modo stand-alone
| Revisión del diseño y Revisión de código |
DES-SA-P5 | El contenedor hará uso de la versión kernel del microfrontend (ENT-RT-P4), quedando como responsable de la importación correcta de las dependencias (script o importmaps) |
|
DES-SA-P6 | Debe exponer un mecanismo de configuración que indique si se ejecuta de forma embebida o stand-alone.
|
|
DES-SA-P7 | NO es el responsable de exponer propiedades ni emitir eventos |
|
| DES-SA-P8 | 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 |
|
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 |
🚚 Entrega
🏗️ BuildTime
🏗️ BuildTime | ||
|---|---|---|
👮 Pauta | 📖 Descripción | 🕵️ Verificación |
ENT-BT-P1 | Se 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 de dependencias y Revisión de código |
ENT-BT-P2 | No debe estar ni bundelizado ni minificado. |
|
ENT-BT-P3 | Debe proporcionar la configuración configuración interna (CNF-01,CNF-02) para que el Host que lo integre establezca la configuración |
|
ENT-BT-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
🏃♀️ RunTime | ||
|---|---|---|
👮 Pauta | 📖 Descripción | 🕵️ Verificación |
ENT-RT-P1 | Debe existir el paquete npm | Revisión de dependencias y Revisión de código |
ENT-RT-P2 | Se debe solicitar un despliegue en el CDN (DEV, PRE, PRO) |
|
ENT-RT-P3 | En estas versiones serán minificadas, bundelizadas y con la configuración interna (CNF-01,CNF-02) |
|
ENT-RT-P4 | Versión kernel: Esta versión NO incluyen dependencias externas al componente dentro del bundlelizado, esto implica que esta versión no funciona de forma independiente, si no que necesita que quien integra cargue (como script o importmap) todas las dependencia necesarias. |
|
ENT-RT-P5 | Versión full: Esta versión SI incluyen dependencias externas al componente dentro del bundlelizado, esto implica que esta versión funciona de forma independiente. Dependiendo de donde y como se integre (de forma aislada o directa) pueden surgir conflictos tecnológicos y/o algunos problemas de rendimiento debido a la carga multiplicada de la misma librería por los n componentes que cargue. |
|
ENT-RT-P6 | A parte de los script, por entorno se debe proporcionar un listado de los importmaps necesarios para ejecutar la versión kernel del component |
|
ENT-RT-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
💻 Stand-Alone | ||
|---|---|---|
👮 Pauta | 📖 Descripción | 🕵️ Verificación |
ENT-SA-P1 | Debe entregarse el componente de tipo aplicación que permite desplegar en modo stand-alone (DES-P4) | Revisión de dependencias y Revisión de código |
ENT-SA-P2 | En caso de desplegarse en contenedores:
|
|
ENT-SA-P3 | En caso de desplegarse en baremental:
|
|
ENT-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 |
🔗Integración
| 🌐 General | ||
|---|---|---|
| 👮 PAUTA | 📖 Descripción | 🕵️ VERIFICACIÓN |
| INT-01 | Se debe determinar el tipo de integración:
| Revisión de la documentación |
| INT-02 | Se debe determinar el modo integración:
| Revisión de la documentación |
INT-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 |
✉️ Comunicación
| 🌐 General | ||
|---|---|---|
| 👮 PAUTA | 📖 Descripción | 🕵️ VERIFICACIÓN |
| COM-01 | El microfrontend recibirá información a través de propiedades | Test unitarios |
| COM-02 | El microfrontend enviará información a través de eventos | Test unitarios |
COM-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 |
🗺️ Routing
| 🌐 General | ||
|---|---|---|
| 👮 PAUTA | 📖 Descripción | 🕵️ VERIFICACIÓN |
ROU-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 |
ROU-P2 | La navegación será siempre interna, no se hará a través de la url | Test unitario |
| ROU-P3 | El microfrontend debe proporcionar una constante con una lista de los paths disponibles | Test unitario |
| ROU-P4 | El microfrontend debe proporcionar un método métodos para construir los paths con variables | Test unitario |
| ROU-P5 | El microfrontend debe proporcionar en la documentación los paths disponibles juntos con sus variables | Revisión de documentación |
| ROU-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 |
ROU-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 |
🔒 Seguridad
| 🌐 General | ||
|---|---|---|
| 👮 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 | EL microfrontend seguro debe exponer una propiedad que reciba un jwt con el OpenID del usuario | Revisión del Diseño |
| SEG-P3 | 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 | Revisión del Diseño y Revisión de documentación |
| SEG-P4 | El microfrontend seguro será el encargado de gestionar el ciclo de vida del token (generación, refresh, revocación) | Test de integración |
| SEG-P5 | El microfrontend seguro deberá estar conectado con un IDP (propio, LoginSAS) que haga la gestión en back del token. | 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 |
⚙️ Configuración
| 🌐 General | ||
|---|---|---|
| 👮 PAUTA | 📖 Descripción | 🕵️ VERIFICACIÓN |
| CNF-01 | El microfrontend es el responsable de proveer al configuración interna para cada uno de los entornos (DEV, PRE, PRO) (ENT-RT-P3, ENT-BT-P3, ENT-SA-P2, ENT-SA-P3) | Se visualiza en el navegador |
| CNF-02 | La configuración se distribuirá de manera estática:
| |
| CNF-03 | El microfrontend debe exponer la configuración externa a través de propiedades. | Test de integración |
CNF-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 |
📦 Versionado
El versionado de los microfrontend se llevará a cabo respetando el estándar de Semantic Version.
| 🌐 General | ||
|---|---|---|
| 👮 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-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 |
🖌️ Tema y Estilos Compartidos
🌐 General | ||
|---|---|---|
👮 Pauta | 📖 Descripción | 🕵️ Verificación |
TEC-P1 | El microfrontend 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 microfrontend 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 microfrontend deberá ser desarrollado haciendo uso de las variables expuestas por el componente del stic-theme | Revisión de código |
TEC-P4 | El microfrontend NO deberá instanciar el componente de theming | Test unitario |
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 |
📚 Documentación
Deberá dejar cumplimentada la plantilla de integración con cada uno de los microfrontend
Normativas de la arquitectura de referencia tecnológica para el desarrollo frontal de software
| Normativa | Descripción | Versión Activa | Fecha de activa | Versión Pre-Release | Fecha de Pre-release |
|---|---|---|---|---|---|
Clientes JAXRS - FHIR RESTFULL | Normas y recomendaciones sobre como crear servicios y clientes REST orientados a protocolo. | N/A | N/A | 1.0 |
|
Guías de desarrollo frontal
| Normativa | Descripción | Versión Activa | Fecha de activa | Versión Pre-Release | Fecha de Pre-release |
|---|---|---|---|---|---|
| Desarrollo de instaladores en entornos k8s con helm | Esta guía cubre las necesidades de generación de plantillas helm, necesarias para articular las operaciones de instalación de las soluciones basadas en contenedores. | 1.0 |
| - | - |
| Directrices de implementación enfocadas en la calidad. | Está guía proporciona una serie de pautas para el diseño y el desarrollo que facilitan la mantenibilidad, la legibilidad y el cambio del código. | 1.0 |
| ||
| Implementación para arquitecturas limpias | Esta guía pretende impulsar los diseños de las aplicaciones que están basadas en Arquitecturas Limpias y Domain Centric que permitirán un diseño orientado al negocio y un desarrollo que facilite el cambio. | 1.0 |
|
Terminología
| Concepto | Definición |
|---|---|
| Microfrontend | Encapsulación lógica de negocio, que contiene una funcionalidad concreta en su dominio y que está diseñada para incorporarse en un host. |
| Isolated-Microfrontend | Microfrontend que dispone de un contexto de ejecución aislado |
Referencias
Vista general
Herramientas de contenido
- Impreso por Atlassian Confluence 8.7.2