Creación de aplicaciones web

Arquitectura frontend con aplicación web Blazor

Las aplicaciones web generadas por Lino conectan a los usuarios con casos de uso de backend a través de una interfaz real, no solo a través de llamadas realizadas a las herramientas API. El tipo de interfaz nativa actual es Aplicación web Blazor, preparado para aplicaciones administrativas, portales públicos, back office, áreas de socios e interfaces de dominio específico.

lino web-app new --name <WebAppName>

El comando debe ejecutarse dentro de un proyecto Lino. Solicita el nombre de la Web App, utiliza la plantilla Blazor Web App, confirma los datos seleccionados, crea los archivos necesarios y ejecuta los comandos que conectan el frontend a la solución. aa forma canónica es web-app. aos alias webapp y web Existen para la productividad, pero la documentación y los ejemplos deberían preferirse. lino web-app new para mantener la coherencia.

Lo que se genera

Una aplicación web Blazor generada por Lino no es solo una carpeta suelta de pantallas. Encaja en la misma solución.NET y sigue la organización modular utilizada por el backend, separando las responsabilidades entre host, cliente, componentes compartidos y proyectos de UI por servicio o módulo.

• Proyecto de servidor: aloja la aplicación web Blazor, asigna los componentes raíz, configura los valores predeterminados del servicio, los activos estáticos, antiforgery, los servicios HTTPS, MudBlazor y los modos de renderizado interactivo.
• Proyecto del cliente: concentra los componentes que se ejecutan en el lado de WebAssembly, el enrutamiento, el diseño, la estructura del menú, la configuración del navegador, las capacidades de localización y la integración con MudBlazor.
• Proyecto WebApps Compartidas: centraliza recursos comunes de la interfaz de usuario, notificaciones, cuadros de diálogo, plantillas de cadenas de consulta, resultados de clientes, servicios culturales/de zona horaria y componentes reutilizables.
• Diseños de UI por servicio y módulo.: Cuando la solución tiene servicios y módulos, Lino crea proyectos frontend dentro del marco de la aplicación web para mantener páginas, menús y recursos aislados por contexto.

Los registros de host generados. AddInteractiveServerComponents y AddInteractiveWebAssemblyComponents. Los componentes raíz HeadOutlet y Routes usar InteractiveAuto, lo que permite que la aplicación comience con interactividad a través del servidor y migre a WebAssembly cuando el tiempo de ejecución del cliente esté disponible.

Integración con backend API

Cuando existe una aplicación web, Lino mantiene el backend preparado para el consumo escrito por parte del frontend. aos servicios y módulos pueden recibir proyectos. Api.Contracts y Api.Client, exponiendo contratos de solicitud/respuesta y clientes escritos a los puntos finales generados.

• aa interfaz de usuario no necesita ensamblar manualmente llamadas HTTP sin procesar para cada funcionalidad.
• Las páginas generadas llaman a clientes API escritos y trabajan con modelos de solicitud y respuesta creados junto con el backend.
• Modelos compartidos como ClientResult, QueryParams y PagedQueryParams estandarice el manejo de resultados, filtros, paginación y retroalimentación visual.
• La integración mediante un HttpClient tipado mantiene el frontend alineado con los contratos, permisos, mensajes de validación y culturas utilizadas por el resto de la solución.

El flujo práctico es:

Página Blazor -> cliente de API tipado -> endpoint Minimal API -> Command/Query -> base de datos

Esta ruta preserva la coherencia de toda la pila: el modelo de dominio, los casos de uso, los puntos finales, los contratos, la interfaz localizada, la navegación y los permisos siguen las mismas convenciones del proyecto.

Funciones de interfaz de usuario incluidas

aa Web App generada ya está preparada para las inquietudes comunes de las aplicaciones reales:

• Enrutamiento de componentes Routes.razor generado.
• Diseño, navegación y componentes visuales basados ​​en MudBlazor.
• Generación de menús a partir de las páginas disponibles en cada servicio o módulo.
• Archivos .resx localizar textos en las culturas configuradas en el proyecto.
• Admite autenticación, almacenamiento de tokens, rutas protegidas y servicios de permisos cuando la función de autenticación está habilitada.
• Menús sensibles a la autorización, que muestran entradas solo cuando el usuario actual tiene el permiso requerido.

Múltiples interfaces

Un único backend puede admitir más de una aplicación web. Esto es útil cuando diferentes audiencias necesitan navegación, seguridad, experiencia e implementación diferentes, pero deben continuar compartiendo los mismos servicios, módulos, casos de uso y API.

• Sitio web público: páginas accesibles para clientes, visitantes o usuarios que aún no están autenticados.
• Oficina administrativa/Administrador: panel de gestión interno para operadores, equipos de soporte y administrativos.
• Portal de socios: Acceso restringido para socios, revendedores, proveedores o integraciones operativas.
• Área de autoservicio: experiencia enfocada al cliente final, con menús y permisos propios.

Cada frontend puede evolucionar con sus propios diseños, recursos, menús y reglas de acceso, mientras que el backend permanece organizado por servicios, módulos, casos de uso y contratos.

Generando paginas web

Después de modelar la entidad, definir los casos de uso y generar comandos, consultas, puntos finales y persistencia, el siguiente paso suele ser exponer la funcionalidad en la interfaz. Lino automatiza este paso con el generador de páginas:

lino page new --service <ServiceName> --module <ModuleName> --entity <EntityName> --webapp <WebAppName>
lino page edit --service <ServiceName> --module <ModuleName> --entity <EntityName> --webapp <WebAppName>
lino page list --service <ServiceName> --module <ModuleName> --entity <EntityName> --webapp <WebAppName>

aas opciones también se pueden informar de forma interactiva. El comando solicita el servicio, módulo, entidad, aplicación web de destino, tipo de página y propiedades que deberían aparecer en la cuadrícula. El tipo más común es CRUD; cuando la entidad solo admite consultas, Lino puede generar una página como Cuadrícula de datos.

Usar page new para crear la primera versión de la pantalla, page edit cuando la página necesita realizar un seguimiento de los cambios en los campos, contratos o comportamiento, y page list para comprender lo que ya se ha generado para una entidad.

Flujo recomendado

1. Cree o seleccione la aplicación web con lino web-app new.
2. Modele la entidad y genere casos de uso, consultas, comandos, puntos finales, contratos API y artefactos de persistencia.
3. Correr lino page new y seleccione la entidad que recibirá la interfaz.
4. Elija con cuidado los campos de la cuadrícula. Se convierten en columnas visibles y ayudan a configurar parámetros de consulta, filtros y paginación.
5. Ejecute la solución a través de AppHost para validar la interfaz de usuario, los API, la autenticación, los permisos y la integración de la base de datos en conjunto.

Estructura generada

Para una página CRUD, Lino crea un paquete de página Blazor completo en lugar de un único archivo Razor:

• Página de registro o índice que coordina el listado, la creación, la edición, los detalles y la eliminación.
• Componente de grid basado en MudBlazor, con carga del lado del servidor, paginación, filtros y mapeo para parámetros de consulta.
• Componente de formulario con ViewModel escrito y extensiones para crear mapas, actualizar y obtener solicitudes de identificación.
• Recursos para títulos, etiquetas, botones, mensajes de validación y textos de interfaz localizados.
• Verificaciones de permisos cuando la autenticación está habilitada, incluida la validación de acceso a la página y los botones condicionales.

Creando una página CRUD para la entidad Vehicle, por ejemplo, en el servicio Fleet, módulo Operations y aplicación web Backoffice, la estructura sigue este formato:

src/WebApps/Backoffice/Services/Fleet/Operations/Pages/Vehicles/Registration/
├── Vehicle.razor
├── Vehicle.razor.cs
├── Resources/
│   ├── VehicleResources.resx
│   └── VehicleResources.Designer.cs
└── Components/
    ├── Form/
    │   ├── VehicleForm.razor
    │   ├── VehicleForm.razor.cs
    │   ├── VehicleFormExtensions.cs
    │   ├── VehicleViewModel.cs
    │   └── Resources/
    │       ├── VehicleFormResources.resx
    │       └── VehicleFormResources.Designer.cs
    └── Grid/
        ├── VehicleGrid.razor
        ├── VehicleGrid.razor.cs
        ├── VehicleGridExtensions.cs
        ├── VehiclePagedQueryParams.cs
        └── Resources/
            ├── VehicleGridResources.resx
            └── VehicleGridResources.Designer.cs

La idea conserva la estructura anterior utilizada en ejemplos como Order: página principal, código subyacente, componentes de formulario, componentes de cuadrícula, extensiones y parámetros paginados. La versión actual agrega características e integración explícita con la organización por aplicación web, servicio y módulo.

Cómo funciona la página generada

La página utiliza los mismos contratos generados para API. La cuadrícula transforma los filtros y la paginación en una solicitud de listado; el formulario transforma el ViewModel en solicitudes de creación o actualización; el cliente API escrito envía la llamada al punto final correspondiente. El punto final ejecuta el comando o consulta generado y devuelve una respuesta escrita a la interfaz de usuario.

Frontend -> API -> Commands/Queries -> base de datos

Cuando existe autorización, el código generado también verifica permisos como enumerar, crear, editar, eliminar y consultar por identificador. Esto afecta tanto al acceso a la página como a la visibilidad de las acciones para el usuario.

El resultado es un flujo completo y consistente: el modelo de dominio, el caso de uso, el punto final, el cliente escrito, la interfaz de usuario localizada, la navegación y los permisos siguen las mismas convenciones de diseño. El generador reduce la repetición, pero los componentes siguen siendo editables para ajustes del producto, usabilidad y reglas específicas.

Interfaz multilingüe

Las aplicaciones web generadas por Lino utilizan archivos .resx para textos localizados. Esto le permite mantener la misma estructura de Razor y variar títulos, etiquetas, botones, mensajes de error, textos de validación y descripciones según la cultura activa.

aa ubicación no debe tratarse como un acabado visual. En páginas administrativas y portales operativos, los términos inconsistentes crean dudas sobre la regla empresarial. Por lo tanto, los recursos son parte de la arquitectura de la interfaz de usuario y deben acompañar a las páginas, formularios, cuadrículas y componentes compartidos.

• Mantenga las claves estables, descriptivas y orientadas al significado, evitando nombres vinculados al diseño temporal de la pantalla.
• Evite el texto codificado en páginas y componentes; Utilice recursos para etiquetas, mensajes, títulos, rutas de navegación, menús y confirmaciones.
• Revise los términos técnicos para mantener la coherencia entre la documentación, los contratos CLI, API y la interfaz.
• Conserve el mismo conjunto de claves en todas las culturas para evitar retrocesos inesperados o pantallas parcialmente traducidas.
• Separe la traducción literal de la adaptación del producto: cuando sea necesario localizar un término para el usuario final, mantenga el significado funcional de la acción.

En las páginas generadas, normalmente hay recursos a nivel de página, formulario y cuadrícula. Esta separación permite que cada parte evolucione sin mezclar textos de listado, edición, validación y navegación.

CRUD responsivo y listo para usar

El CRUD generado acelera la entrega porque crea la base repetitiva de la pantalla: listado, formulario, integración con API, recursos, paginación, filtros, acciones y código subyacente. Aun así, debería considerarse como una experiencia de producto, no sólo como un soporte técnico.

Una buena pantalla CRUD debe permitir al usuario encontrar registros, comprender el estado actual, tomar medidas con confianza y recuperarse de fallas. Esto se aplica tanto a las pantallas internas del back office como a los portales dirigidos a clientes o socios.

• Elija columnas de listado que ayuden a la toma de decisiones; Evite redes con campos técnicos que no digan nada al operador.
• Configurar filtros y paginación según el volumen de datos esperado y los principales criterios de búsqueda del usuario.
• Revise las validaciones y los mensajes de error para explicar el problema en el lenguaje del dominio, no solo en términos de implementación.
• Asegúrese de que haya estados vacío, de carga y de bloqueo para evitar pantallas silenciosas cuando no hay datos, API lleva tiempo o una operación no se completa.
• Confirmar eliminaciones y operaciones irreversibles, dejando claro qué registro se verá afectado.
• Muestre comentarios claros después de guardar, editar, eliminar o fallar al usar notificaciones y mensajes localizados.
• Proteger acciones mediante permiso en el backend y el frontend; Ocultar botones mejora la experiencia, pero no reemplaza la autorización real.
• Verifique la capacidad de respuesta en pantallas más pequeñas, especialmente menús de acciones, filtros, campos obligatorios y cuadrículas con muchas columnas.

El punto de partida generado por Lino debe tratarse como una base coherente e integrada. A partir de ahí, el equipo ajusta la densidad visual, el orden de los campos, las reglas de visualización, los permisos y los textos para reflejar el proceso real del producto.